最適化Forms核心元件中的自訂函式

本文介紹如何使用最新最適化表單核心元件建立自訂函式，這些元件具有最新功能，例如：

請確保在您的AEM Forms核心元件環境中設定最新表單版本，以使用自訂函式中的最新功能。

簡介

AEM Forms 6.5包含JavaScript函式，可讓您使用規則編輯器定義複雜的商業規則。 雖然AEM Forms提供多種現成可用的自訂函式，但許多使用案例需要定義您自己的自訂函式，才能用於多個表單。 這些自訂函式可讓您根據特定需求操控和處理輸入的資料，藉此增強表單的功能。 此外，它們允許根據預先定義的條件動態變更表單行為。

使用自訂函式 uses-of-custom-function

在最適化Forms核心元件中使用自訂函式的優點包括：

自訂函式基本上是新增至JavaScript檔案中的使用者端程式庫。 建立自訂函式後，規則編輯器中即會顯示該函式，供使用者在最適化表單中選取。 自訂函式由規則編輯器中的JavaScript註解識別。

支援自訂功能的JavaScript註解 js-annotations

JavaScript註解提供JavaScript程式碼的中繼資料。 它包含以特定符號開頭的註解，例如，/**和@。 註解提供關於程式碼中函式、變數和其他元素的重要資訊。 最適化表單支援下列自訂函式的JavaScript註解：

名稱

Name ​用於識別最適化表單的規則編輯器中的自訂函式。 下列語法可用來命名自訂函式：

參數

引數 ​是自訂函式使用的引數清單。 函式可支援多個引數。 下列語法可用來定義自訂函式中的引數：

引數型別是​ 不區分大小寫，而且引數名稱中不允許有空格。

<Parameter Description>包含有關引數用途的詳細資料。 它可以有多個字詞。

傳回型別

傳回型別會指定自訂函式在執行後傳回的值型別。 下列語法可用來定義自訂函式中的傳回型別：

傳回型別不區分大小寫。

私人

宣告為私用的自訂函式不會出現在最適化表單的規則編輯器中的自訂函式清單中。 自訂函式預設為公用。 宣告自訂函式為私用的語法為@private。

建立自訂函式時的准則 considerations

若要在規則編輯器中列出自訂函式，您可以使用下列任一格式：

包含或不包含jsdoc註解的函式陳述式

您可以建立包含或不包含jsdoc註解的自訂函式。

    function functionName(parameters)
        {
            // code to be executed
        }

如果使用者未將任何JavaScript註解新增至自訂函式，則會依函式名稱在規則編輯器中列出。 不過，建議您加入JavaScript註解，以提升自訂函式的可讀性。

箭頭功能與強制JavaScript註解或註解

您可以使用箭頭函式語法來建立自訂函式：

    /**
    * test function
    * @name testFunction
    * @param {string} a parameter description
    * @param {string=} b parameter description
    * @return {string}
    */
    testFunction = (a, b) => {
    return a + b;
    };
    /** */
    testFunction1=(a) => (return a)
    /** */
    testFunction2 = a => a + 100;

如果使用者沒有將任何JavaScript註解新增到自訂函式，則自訂函式不會列在最適化表單的規則編輯器中。

含有強制JavaScript註解或註解的函式運算式

若要列出最適化表單的規則編輯器中的自訂函式，請以下列格式建立自訂函式：

    /**
    * test function
    * @name testFunction
    * @param {string} input1 parameter description
    * @param {string=} input2 parameter description
    * @return {string}
    */
    testFunction = function(input1,input2)
        {
            // code to be executed
        }

如果使用者沒有將任何JavaScript註解新增到自訂函式，則自訂函式不會列在最適化表單的規則編輯器中。

建立自訂函式的先決條件

開始將自訂函式新增至最適化Forms之前，請確保您的電腦上安裝了下列軟體：

建立自訂函數 create-custom-function

建立自訂函式的步驟如下：

使用AEM專案原型建立使用者端程式庫 create-client-library-archetype

您可以使用AEM Project Archetype🔗，將使用者端程式庫新增至已建立的專案，以新增自訂函式。
如果您有現有的專案，您可以直接將自訂函式新增到您的本機專案。

建立原型專案或使用現有專案後，請建立使用者端程式庫。 若要建立使用者端程式庫，請執行下列步驟：

新增使用者端資料庫資料夾

若要新增使用者端程式庫資料夾至您的[AEM專案目錄]，請遵循下列步驟：

新增檔案和資料夾至使用者端資料庫資料夾

將下列專案新增至新增的使用者端程式庫資料夾：

Location is: [AEMaaCS project directory]/ui.apps/src/main/content/jcr_root/apps/experience-league/customclientlibs/

在filter.xml中包含新資料夾：

透過CRXDE建立及部署自訂函式 create-add-custom-function

如果您使用最新的AEM Forms和Forms附加元件，可以透過CRXDE建立自訂函式，以使用自訂函式的最新更新。 若要這麼做，請執行下列步驟：

您可以參考下列自訂函式資料夾。 下載此資料夾並安裝在您的AEM執行個體上。

現在，您可以新增使用者端程式庫，以在最適化表單中使用自訂函式。

在最適化表單中新增使用者端程式庫 add-client-library

將使用者端程式庫部署到AEM Forms環境後，請在最適化表單中使用其功能。 若要在最適化表單中新增使用者端程式庫

現在，您可以建立規則，以在規則編輯器中使用自訂函式：

現在，讓我們瞭解如何在AEM Forms 6.5🔗中使用規則編輯器的Invoke服務來設定和使用自訂函式

在最適化表單中使用自訂函式 use-custom-functions

在最適化表單中，您可以在規則編輯器🔗中使用自訂函式。
讓我們將下列程式碼新增至JavaScript檔案（Function.js檔案），以根據出生日期(YYYY-MM-DD)計算年齡。 建立自訂函式為calculateAge()，它以出生日期作為輸入並傳回年齡：

    /**
        * Calculates Age
        * @name calculateAge
        * @param {object} field
        * @return {string}
    */

    function calculateAge(field) {
    var dob = new Date(field);
    var now = new Date();

    var age = now.getFullYear() - dob.getFullYear();
    var monthDiff = now.getMonth() - dob.getMonth();

    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
    age--;
    }

    return age;
    }

在上述範例中，當使用者以(YYYY-MM-DD)格式輸入出生日期時，會叫用自訂函式calculateAge並傳回年齡。

讓我們預覽表單，以觀察如何透過規則編輯器實作自訂函式：

支援自訂函式中的非同步函式 support-of-async-functions

非同步自訂函式未出現在規則編輯器清單中。 不過，您也可以在使用同步函式運算式建立的自訂函式中叫用非同步函式。

檢視以下程式碼，瞭解如何使用自訂函式叫用非同步函式：

    async function asyncFunction() {
    const response = await fetch('https://petstore.swagger.io/v2/store/inventory');
    const data = await response.json();
    return data;
    }

    /**
    * callAsyncFunction
    * @name callAsyncFunction callAsyncFunction
    */
    function callAsyncFunction() {
    asyncFunction()
        .then(responseData => {
        console.log('Response data:', responseData);
        })
        .catch(error => {
         console.error('Error:', error);
    });
}

在上述範例中，asyncFunction函式是asynchronous function。 它透過向https://petstore.swagger.io/v2/store/inventory發出GET請求來執行非同步操作。 它會使用await等待回應、使用response.json()將回應本文剖析為JSON，然後傳回資料。 callAsyncFunction函式是同步自訂函式，會叫用asyncFunction函式並在主控台中顯示回應資料。 雖然callAsyncFunction函式是同步的，但它會呼叫非同步asyncFunction函式，並以then和catch陳述式處理其結果。

若要檢視其運作情況，讓我們新增按鈕，並為按鈕建立規則，此規則會在按鈕按一下時叫用非同步函式。

請參考下方主控台視窗的圖例，以示範當使用者按一下Fetch按鈕時，會叫用自訂函式callAsyncFunction，進而呼叫非同步函式asyncFunction。 Inspect主控台視窗中，檢視按下按鈕時的回應：

讓我們來探討自訂函式的功能。

自訂功能的各種功能

您可以使用自訂函式，將個人化功能新增至表單。 這些函式支援各種功能，例如使用特定欄位、使用全域欄位或快取。 此彈性可讓您根據組織的需求自訂表格。

自訂函式中的欄位和全域範圍物件 support-field-and-global-objects

欄位物件是指表單中的個別元件或元素，例如文字欄位、核取方塊。 全域物件包含唯讀變數，例如表單例項、目標欄位例項，以及在自訂函式內進行表單修改的方法。

讓我們瞭解自訂函式如何透過使用不同使用案例的Contact Us表單來使用欄位和全域物件。

使用案例：使用SetProperty規則顯示面板

在自訂函式中新增下列程式碼（如create-custom-function區段中所述），以將表單欄位設為Required。

    /**
    * enablePanel
    * @name enablePanel
    * @param {object} field1
    * @param {object} field2
    * @param {scope} globals
    */

    function enablePanel(field1,field2, globals)
    {
       if(globals.functions.validate(field1).length === 0)
       {
       globals.functions.setProperty(field2, {visible: true});
       }
    }

在此範例中，在按一下按鈕時就會進行personaldetails面板的驗證。 如果在面板中未偵測到任何錯誤，則按一下按鈕時，另一個面板（feedback面板）會變成可見。

讓我們為Next按鈕建立規則，以驗證personaldetails面板，並讓使用者按一下Next按鈕時顯示feedback面板。

請參閱下圖以示範，按一下Next按鈕後，personaldetails面板在哪裡驗證。 如果personaldetails中的所有欄位都已驗證，feedback面板就會顯示出來。

如果「personaldetails」面板的欄位中存在錯誤，則按一下「Next」按鈕後，這些錯誤將顯示在欄位層級，而「feedback」面板將保持隱藏狀態。

使用案例：驗證欄位。

依照create-custom-function區段中的說明，在自訂函式中新增下列程式碼，以驗證欄位。

    /**
    * validateField
    * @name validateField
    * @param {object} field
    * @param {scope} globals
    */
    function validateField(field,globals)
    {

        globals.functions.validate(field);

    }

在此範例中，自訂驗證模式套用至contact欄位。 使用者必須輸入以10開頭後接8位數的電話號碼。 如果使用者輸入的電話號碼不是以10開頭或包含多於8位數，則按一下按鈕時會出現驗證錯誤訊息：

現在，下一步是為Next按鈕建立規則，以驗證按鈕點選上的contact欄位。

請參考下圖以示範，如果使用者輸入的電話號碼不是以10開頭，則欄位層級會顯示錯誤訊息：

如果使用者輸入有效的電話號碼且personaldetails面板中的所有欄位都經過驗證，feedback面板就會顯示在畫面上：

使用案例：重設面板

依照create-custom-function區段中的說明，在自訂函式中新增下列程式碼，以重設面板。

    /**
    * resetField
    * @name  resetField
    * @param {string} input1
    * @param {object} field
    * @param {scope} globals
    */
    function  resetField(field,globals)
    {

        globals.functions.reset(field);

    }

在此範例中，按一下Clear按鈕時，personaldetails面板會重設。 下一步是為Clear按鈕建立規則，以在按鈕點選時重設面板。

請參閱下圖以顯示，如果使用者按一下clear按鈕，personaldetails面板會重設：

使用案例：在欄位層級顯示自訂訊息並將欄位標籤為無效

您可以使用markFieldAsInvalid()函式將欄位定義為無效，並在欄位層級設定自訂錯誤訊息。 fieldIdentifier值可以是fieldId、field qualifiedName或field dataRef。 名稱為option的物件值可以是{useId: true}、{useQualifiedName: true}或{useDataRef: true}。
用於將欄位標示為無效並設定自訂訊息的語法如下：

在自訂函式中新增下列程式碼（如create-custom-function區段中所述），以在欄位層級啟用自訂訊息。

    /**
    * customMessage
    * @name customMessage
    * @param {object} field
    * @param {scope} globals
    */
    function customMessage(field, globals) {
    const minLength = 15;
    const comments = field.$value.trim();
    if (comments.length < minLength) {
        globals.functions.markFieldAsInvalid(field.$id, "Comments must be at least 15 characters long.", { useId: true });
    }
}

在此範例中，如果使用者在註解文字方塊中輸入少於15個字元，則欄位層級會顯示自訂訊息。

下一步是為comments欄位建立規則：

請參閱下列示範，說明在comments欄位中輸入負面意見會觸發在欄位層級顯示自訂訊息：

如果使用者在評論文字方塊中輸入超過15個字元，則欄位會通過驗證並提交表單：

使用案例：將變更的資料提交至伺服器

下列程式碼行：
globals.functions.submitForm(globals.functions.exportData(), false);用於在操作後提交表單資料。

在自訂函式中新增下列程式碼（如create-custom-function區段中所述），以在伺服器上提交操作過的資料：

    /**
    * submitData
    * @name submitData
    * @param {object} field
    * @param {scope} globals
    */
    function submitData(globals)
    {

    var data = globals.functions.exportData();
    if(!data.comments) {
    data.comments = 'NA';
    }
    console.log('After update:{}',data);
    globals.functions.submitForm(data, false);
    }

在此範例中，如果使用者將comments文字方塊留空，則在提交表單時會將NA提交至伺服器。

現在為提交資料的Submit按鈕建立規則：

請參考下圖console window以示範，如果使用者將comments文字方塊留空，則會在伺服器上提交值為NA：

您也可以檢查主控台視窗，以檢視提交給伺服器的資料：

在主控台視窗

自訂函式的快取支援

Adaptive Forms會在規則編輯器中擷取自訂函式清單時，實作自訂函式的快取，以增強回應時間。 在error.log檔案中會顯示訊息為Fetched following custom functions list from cache。

具有快取支援的

如果修改自訂函式，快取會失效，並加以剖析。

疑難排解 troubleshooting

考量事項