Ninox 中未列入文件的函式

有些函式並未收錄在 Ninox 的官方文件中。它們是我們檢視程式碼、理解其行為之後發現的。

TypeOf

typeof 函式回傳指定欄位的型別。

範例：

typeof(first(select Customer).'First Name');

Eval

eval 函式會在指定記錄的環境中執行以參數傳入的腳本。它回傳該腳本的值，或是一段指出腳本有誤的文字。

範例：

eval("---{this.'First Name'} {this.'Last Name'}---", first(select Customer));

輸出：

Sofia Young

DebugValueInfo

debugValueInfo 函式回傳一段文字，指出所傳入參數的型別與值。
這在 Ninox 主控台中試驗片段程式碼時特別好用。

範例：

debugValueInfo(eval("---{this.'First Name'} {this.'Last Name'}---", first(select Customer)));

輸出：
any("Sofia Young")

Debug

debug 函式相當於 JavaScript 中的 console.log。
它會把以參數傳入的值送到瀏覽器的開發者主控台。這對於在公式中除錯很有幫助。

範例：

(select Customer where 'First Name' like "a").(
  var 'firstName' := this.'First Name';
  var lastName := this.'Last Name';
  debug("Debug info: " + 'firstName' + " " + lastName);
)

結果會出現在瀏覽器的開發者主控台中（透過開發者工具開啟）。

Records

records 函式依指定的數字陣列回傳記錄。

**注意：**這個陣列必須是寫死的，不能是變數，這使得這個函式較不靈活。它主要適用於需要固定取得同一批記錄的場合。

範例：

records(Customer, [1, 3, 6]).'First Name';

這會取出 ID 為 1、3 與 6 的記錄的名字。

nx-file

Ninox 的 http() 函式可以從遠端伺服器取得資料。它回傳一個 JSON 物件，由 error 和／或 result 兩個鍵組成。result 鍵中裝的是伺服器回傳的內容。

如果那份內容是文字格式（例如 HTML、JavaScript、JSON 或其他文字檔），一切都沒問題。但如果它是二進位檔案（例如影像、PDF、Word 文件等）或部分為二進位，Ninox 就會試著把這些內容存進一個 text 變數。這會造成問題，因為某些二進位值會被轉義（例如值 92，十六進位為 0x5C，也就是「\」這個轉義字元）。

原因在於 Ninox 無法直接處理位元組陣列。要繞過這個問題，我們可以使用 Base64，把二進位資料轉換成文字形式。關於 Base64 的更多資訊，請參閱：
https://www.freecodecamp.org/news/what-is-base64-encoding/?utm_source=chatgpt.com

Ninox 提供了一些操作 Base64 編碼資料的函式，例如 loadFileAsBase64() 或 loadFileAsBase64URL()。它們可以把（存在記錄中的）檔案以 Base64 格式取出。

回到我們的情境：我們需要讀取一個遠端的二進位檔案，並把它存進 Ninox 的記錄中。在 http() 函式裡可以定義標頭選項，通常只要用 content-type 這個鍵指定想要讀取的格式即可。不過，若要處理二進位資料，就得再加上一個未列入文件的鍵 nx-file，並把它的值設為 "base64url"。

加上 nx-file 這個鍵之後，Ninox 處理伺服器回傳內容的方式就會改變。一般情況下，Ninox 會「原封不動」地回傳內容；有了 nx-file，Ninox 則會把回應轉換成 Base64URL。於是，您收到的不再是像這樣的東西：

{"result":"�PNG\r\n\u001a\n\u0000\rIHDR\u0000\u0002�\u0000\u0002\u001f\b\u0006\u0000����\u0000\u0001DiCCPicc\u0000\u0018�c``<���[�$����WR\u0014��\u0010\u0011..."}

……而是：

{"result":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAqoAAAIfCAYAAAC4gv6sAAABRGlDQ1BpY2MAABiVY2BgPJGTnFvMJMDAkJtXUhTk7qQQERmlwP6IgZlBhIGTgY9BNjG5uM..."}

這種新格式（Base64URL）可以直接搭配 Ninox 的 importFile() 函式使用，該函式會把它解讀成本機的 Base64 URL，並存進指定的記錄。

請記得，大多數遠端伺服器只接受來自其他伺服器（而非用戶端）的請求。這就是為什麼把 http() 函式放在 do as server 環境中執行很重要。

下面是一個 Ninox 全域函式範例，可以把二進位資料（影像、PDF、Word 文件、Excel 檔等）讀取成 Base64URL：

function loadFileOnBase64FromUrl(URL : text) do
 var fileName := extractx(URL, "\/([^\/?#]+)[^\/]*$", "$1");
 {
  fileName: fileName,
  content: do as server
    http("get", URL, {
      'content-type': "application/octet-stream",
      'nx-file': "base64url"
    }, null).result
  end
 }
end;

以下則是這個函式的使用範例：

var base64UrlFile := loadFileOnBase64FromUrl(url);
importFile(this, text(base64UrlFile.content), text(base64UrlFile.fileName));

這樣一來，您就能取得遠端的二進位檔案，把它轉換成 Base64URL，並直接匯入 Ninox 的記錄中。