HTML 輔助函式

直接從 HTML/JavaScript 呼叫 Ninox 函式

Ninext 讓您可以從 HTML 或 JavaScript 程式碼直接呼叫 Ninox 函式，因而更容易打造與 Ninox 整合的 HTML 介面。雖然 Ninox 的 html 函式已能在公式中輕鬆產生 HTML 元件，但若不動用更複雜的解法，要與 Ninox 的邏輯互動仍相當麻煩。

以一個需要觸發 Ninox 相關行為的輸入欄位為例。傳統做法是透過 REST API 把資料送到伺服器，再由伺服器更新本機的顯示。這個方法確實有效，卻有幾個缺點：

**技術門檻高：**實作 API 呼叫需要對 JavaScript 中的 HTTP 請求有紮實的理解。
**互動性受限：**變更只影響伺服器端的資料，無法立即在介面上觸發本機更新。

有了 Ninext，整合就順暢多了：您可以把 HTML/JavaScript 元件直接連結到 Ninox 函式，在沒有 API 呼叫種種限制的情況下，提升應用程式的互動性。

callNinoxFunction

callNinoxFunction 函式讓您可以從 JavaScript 程式碼呼叫 Ninox 腳本。這樣的整合在與 Ninox 互動時帶來極大的彈性，特別適用於：

傳送輸入欄位的值，
在 onclick、onfocus、onblur、ontimer 等事件發生時執行動作，
以回呼處理非同步作業。

格式與參數

ninext.callNinoxFunction(functionName, htmlElement, ...args, [callback])

參數	說明
`functionName`	要呼叫的 Ninox 函式名稱。
`htmlElement`	可以是 HTML 元素的 ID（例如 `"myId"`），也可以是元素本身（例如 `this` 或 `document.getElementById("myId")`）。
`...args`	要傳給 Ninox 函式的其他參數。
`callback`	（選用）用來以非同步方式處理結果的函式。若有提供，它會以 `(error, result)` 被呼叫。

回傳值

同步模式（不使用回呼）

此函式回傳一個 JSON 物件，結構為下列其中一種：

成功時：

{
    result: <value>    // The value returned by the Ninox function
}

發生錯誤時：

{
    error: <string>    // Error message describing what went wrong
}

非同步模式（使用回呼）

當最後一個引數是回呼函式時，該回呼會收到兩個參數：

callback(error, result)

參數	說明
`error`	若發生問題則為 `Error` 物件，成功時則為 `undefined`。
`result`	Ninox 函式回傳的值；若發生錯誤則為 `null`。

運作方式

核心概念是在 HTML 頁面的環境中執行 Ninox 腳本。運作方式如下：

定義 Ninox 函式
在您的 Ninox 公式中定義一個函式（例如 myOnblur），用來處理從 JavaScript 傳來的參數。這個函式與腳本的其餘部分互相隔離，並在目前記錄的環境中執行（相當於 Ninox 中的 this）。
建立 HTML 介面
在公式中嵌入一個 HTML 元件（例如輸入欄位）。在事件屬性（例如 onblur）中，用 callNinoxFunction 呼叫對應的 Ninox 函式，並傳入所需的參數。
觸發事件
當 HTML 事件被觸發時，callNinoxFunction 會呼叫指定的 Ninox 函式，將它隔離出來，並帶著給定的環境與參數（例如輸入欄位的值）執行。

這套機制模擬了原生觸發器的行為，同時還能把一個或多個自訂參數傳給要執行的 Ninox 函式。

使用範例

基本範例：帶 onblur 的輸入欄位

定義 Ninox 函式

在您的 Ninox 公式中加入下列函式：

function myOnblur(inputValue : text) do
    alert("Input of record " + this.Id + " is " + inputValue)
end;

這個函式會顯示一則警示，內容是目前記錄的 ID 與傳入的值。

整合 HTML 輸入欄位

接著插入下列 HTML 程式碼，以顯示一個輸入欄位並定義 onblur 事件：

function myOnblur(inputValue : text) do
    alert("Input of record " + this.Id + " is " + inputValue)
end;

html("
    <input
        class='nx-input nx-input--editing'
        style='width: 100%; height: 100%;'
        onblur=""ninext.callNinoxFunction('myOnblur', this, this.value)""
    />
")

運作方式：

當使用者離開輸入欄位時（onblur 事件），
ninext.callNinoxFunction 函式會以下列引數被呼叫：
- 'myOnblur'：要執行的 Ninox 函式名稱，
- this：HTML 元素本身，
- this.value：輸入欄位目前的值。

如此一來，Ninox 腳本 myOnblur 就會在目前記錄的環境中執行，彷彿是由 Ninox 原生觸發的一樣，同時還能把輸入欄位的值當作參數收下。

同步用法範例

// Basic call - checking the result
const response = ninext.callNinoxFunction('myFunction', this, 'param1');
if (response.error) {
    console.error('Error:', response.error);
} else {
    console.log('Result:', response.result);
}

// Direct access to result (when you're confident there's no error)
alert(ninext.callNinoxFunction('getValue', this).result);

// With error handling
const res = ninext.callNinoxFunction('calculateTotal', 'myButtonId', 100, 0.2);
if (res.error) {
    alert('Calculation failed: ' + res.error);
} else {
    document.getElementById('total').textContent = res.result;
}

非同步用法範例（使用回呼）

// Basic callback usage
ninext.callNinoxFunction('myFunction', this, 'param1', function(error, result) {
    if (error) {
        console.error('Error:', error.message);
    } else {
        console.log('Result:', result);
    }
});

// Update UI after async operation
ninext.callNinoxFunction('loadData', 'myContainer', recordId, function(error, result) {
    if (error) {
        alert('Failed to load data: ' + error.message);
        return;
    }
    document.getElementById('output').innerHTML = result;
});

// Using arrow function syntax
ninext.callNinoxFunction('calculateTotal', this, 100, 0.2, (error, result) => {
    if (!error) {
        document.getElementById('total').textContent = result;
    }
});

何時該用回呼？

在下列情況請採用回呼的寫法：

Ninox 函式會執行非同步作業（API 呼叫、複雜運算），
您需要在函式完成後更新使用者介面，
您想把多個作業依序串接起來。

重點

環境脈絡：
Ninox 函式執行時，this 代表目前的記錄，確保執行環境的一致性。
彈性：
您可以透過 ...args 視需要加入任意數量的參數，讓 Ninox 函式的行為配合您應用程式的具體需求。
錯誤處理：
同步與非同步兩種模式都會清楚回報錯誤，讓除錯更容易。
多樣用途：
這套機制特別適合把 HTML/JavaScript 使用者介面與 Ninox 中定義的商業邏輯做複雜的整合。