為最適化表單欄位建立自訂外觀

簡介

最適化表單運用外觀架構，協助您建立最適化表單欄位的自訂外觀，並提供不同的使用者體驗。例如，以切換按鈕取代選項按鈕和核取方塊，或使用自訂jQuery增效模組來限制使用者在諸如電話號碼或電子郵件ID等欄位中的輸入。

本檔案說明如何使用jQuery外掛程式來建立最適化表單欄位的替代體驗。此外，它還展示了一個示例，用於為數字欄位元件建立自定義外觀，以顯示為數字步進器或滑塊。

我們先來看一下本文使用的關鍵術語和概念。

外觀：指最適化表單欄位中各種元素的樣式、外觀和組織。它通常包含標籤、提供輸入的互動區域、說明圖示，以及欄位的簡短和長篇說明。本文討論的外觀定制適用於該領域輸入區域的外觀。

jQuery plugin提供基於jQuery Widget架構的標準機制，以實作替代外觀。

ClientLib 由複雜的JavaScript和CSS程式碼驅動的AEM用戶端處理中的用戶端程式庫系統。如需詳細資訊，請參閱使用用戶端程式庫。

ArchetypeA Maven專案範本工具套件，定義為Maven專案的原始圖樣或模型。如需詳細資訊，請參閱原型簡介。

User Control指介面工具集中包含欄位值的主要元素，並由外觀架構用來將自訂介面工具集UI與最適化表單模型系結。

建立自訂外觀的步驟

建立自定義外觀的高級步驟如下：

建立專案:建立Maven專案，以產生要部署在AEM上的內容套件。
擴充現有的Widget類別:擴充現有的介面工具集類別並覆寫所需的類別。
建立客戶端庫:建立程 clientLib: af.customwidget 式庫並新增所需的JavaScript和CSS檔案。
建立並安裝專案:建立Maven專案，並在AEM上安裝產生的內容套件。
更新最適化表單:更新最適化表單欄位屬性，以使用自訂外觀。

建立專案

主原型是建立自訂外觀的起點。待用原型的詳細內容如下：

儲存庫:https://repo.adobe.com/nexus/content/groups/public/
對象ID:自訂外觀原型
群組ID:com.adobe.aemforms
版本:1.0.4

執行以下命令以基於原型建立本地項目：

mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4

該命令從儲存庫下載Maven插件和原型資訊，並根據以下資訊生成項目：

groupId:產生的Maven專案所使用的群組ID
artifactId:生成的Maven項目使用的對象ID。
版本:產生的Maven專案版本。
package:用於檔案結構的包。
artifactName:產生的AEM套件的對象名稱。
packageGroup:產生的AEM套件的套件群組。
widgetName:用於參考的外觀名稱。

生成的項目具有以下結構：

─<artifactId>

 └───src

     └───main

         └───content

             └───jcr_root

                 └───etc

                     └───clientlibs

                         └───custom

                             └───<widgetName>

                                 ├───common [client library - af.customwidgets which encapsulates below clientLibs]

                                 ├───integration [client library - af.customwidgets.<widgetName>_widget which contains template files for integrating a third-party plugin with Adaptive Forms]

                                 │   ├───css

                                 │   └───javascript

                                 └───jqueryplugin [client library - af.customwidgets.<widgetName>_plugin which holds the third-party plugins and related dependencies]

                                     ├───css

                                     └───javascript

建立專案範本後，請視需要進行下列變更：

將協力廠商外掛程式相依性加入專案。
1. 將協力廠商或自訂jQuery增效模組置於jqueryplugin/javascript檔案夾，並將相關的CSS檔案置於jqueryplugin/css檔案夾。如需詳細資訊，請參閱jqueryplugin/javascript and jqueryplugin/css資料夾下的JS和CSS檔案。
2. 修改js.txt和css.txt檔案，以包含jQuery外掛程式的任何其他JavaScript和CSS檔案。
將協力廠商外掛程式與架構整合，讓自訂外觀架構與jQuery外掛程式之間互動。新介面工具集只有在您擴充或覆寫下列函式後，才能運作。

函數	說明
`render`	render函式返回構件的預設HTML元素的jQuery對象。預設的HTML元素應為可聚焦類型。例如，`<a>`、`<input>`和`<li>`。傳回的元素會用作`$userControl`。如果`$userControl`指定上述限制，則`AbstractWidget`類別的函式會如預期般運作，否則某些常用API（焦點，按一下）需要變更。
`getEventMap`	傳回將HTML事件轉換為XFA事件的地圖。 `{ blur: XFA_EXIT_EVENT, }` 此範例顯示 `blur` 是HTML事件， `XFA_EXIT_EVENT` 是對應的XFA事件。
`getOptionsMap`	傳回地圖，其中提供選項變更時要執行之動作的詳細資訊。鍵是提供給介面工具集的選項，值是在偵測到選項變更時呼叫的函式。介面工具集為所有常用選項（`value`和`displayValue`除外）提供處理常式。
`getCommitValue`	每當jQuery Widget的值儲存在XFA模型（例如在文字欄位的退出事件上）時，jQuery Widget架構就會載入函式。實作應傳回儲存在介面工具集中的值。處理常式會隨附選項的新值。
`showValue`	預設情況下，在XFA中，輸入事件時，將顯示該欄位的`rawValue`。此函式被調用，以向用戶顯示`rawValue`。
`showDisplayValue`	依預設，在退出事件時的XFA中，會顯示欄位的`formattedValue`。此函式被調用，以向用戶顯示`formattedValue`。

視需要更新integration/javascript資料夾中的JavaScript檔案。
- 將文字__widgetName__取代為實際的介面工具集名稱。
- 從適當的現成可用介面工具集類別擴充介面工具集。在大多數情況下，它是與要替換的現有Widget對應的Widget類。父類名稱用於多個位置，因此建議搜索檔案中字串xfaWidget.textField的所有實例，並將它們替換為實際使用的父類。
- 擴充render方法以提供替代UI。它是呼叫jQuery外掛程式以更新UI或互動行為的位置。 render方法應傳回使用者控制元素。
- 延伸getOptionsMap方法，以覆寫因介面工具集變更而影響的任何選項設定。函式返回映射，該映射提供了在選項更改時要執行的操作的詳細資訊。鍵是提供給介面工具集的選項，而值是偵測到選項變更時呼叫的函式。
- getEventMap方法會映射由介面工具集觸發的事件，以及最適化表單模型所需的事件。預設值會對應預設介面工具集的標準HTML事件，若觸發替代事件，則需要更新。
- showDisplayValue和showValue會套用顯示和編輯圖片子句，並可覆寫以具有替代行為。
- 當commit事件發生時，最適化表單架構會呼叫getCommitValue方法。通常是退出事件，但下拉式清單、選項按鈕和核取方塊元素在變更時除外)。如需詳細資訊，請參閱最適化表單運算式。
- 範本檔案提供各種方法的範例實作。移除不要擴充的方法。

建立客戶端庫

Maven原型產生的範例專案會自動建立必要的用戶端程式庫，並將它們封裝在具有af.customwidgets類別的用戶端程式庫中。 af.customwidgets中可用的JavaScript和CSS檔案會在執行時期中自動包含。

建立並安裝

若要建立專案，請在shell上執行下列命令，以產生需要安裝在AEM伺服器上的CRX套件。

mvn clean install

注意

主項目引用POM檔案中的遠程儲存庫。這僅供參考，根據Maven標準，儲存庫資訊將在settings.xml檔案中捕獲。

更新最適化表單

要將自定義外觀應用於最適化表單域，請執行以下操作：

在編輯模式中開啟最適化表單。
為要應用自定義外觀的欄位開啟屬性對話框。
在Styling標籤中，更新CSS class屬性，以widget_<widgetName>格式新增外觀名稱。例如：widget_numericstepper

範例：建立自訂外觀

現在，讓我們看一個示例，以建立數字欄位的自定義外觀，使其顯示為數字步進器或滑塊。執行以下步驟：

執行以下命令以基於Maven原型建立本地項目：

mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4

它提示您指定下列參數的值。
此範例中使用的值會以粗體反白顯示。

Define value for property 'groupId': com.adobe.afwidgets

Define value for property 'artifactId': customWidgets

Define value for property 'version': 1.0.1-SNAPSHOT

Define value for property 'package': com.adobe.afwidgets

Define value for property 'artifactName': customWidgets

Define value for property 'packageGroup': adobe/customWidgets

Define value for property 'widgetName': numericStepper
導覽至customWidgets（為artifactID屬性指定的值）目錄，然後執行下列命令以產生Eclipse專案：

mvn eclipse:eclipse
開啟Eclipse工具並執行下列動作以匯入Eclipse專案：
1. 選擇「檔案>匯入>現有專案」至Workspace。
2. 瀏覽並選擇執行archetype:generate命令的資料夾。
3. 按一下完成。
選擇要用於自訂外觀的介面工具集。此範例使用下列數值步進器Widget:

https://www.jqueryscript.net/form/User-Friendly-Number-Input-Spinner-with-jQuery-Bootstrap.html

在Eclipse專案中，請檢閱plugin.js檔案中的外掛程式碼，以確保它符合外觀的要求。在此示例中，外觀滿足以下要求：
- 數字步進器應從- $.xfaWidget.numericInput擴展。
- 介面工具集的set value方法會在焦點位於欄位後設定值。這是最適化表單Widget的必備要求。
- render方法需要被覆寫，才能調用bootstrapNumber方法。
- 除了外掛程式的主要原始碼外，外掛程式沒有其他相依性。
- 範例不會在步進器上執行任何樣式，因此不需要額外的CSS。
- $userControl物件應可用於render方法。它是text類型的欄位，使用插件代碼克隆。
- 在禁用欄位時，+和-按鈕應禁用。
將bootstrap-number-input.js(jQuery plugin)的內容取代為numericStepper-plugin.js檔案的內容。

在numericStepper-widget.js檔案中，新增下列程式碼以覆寫演算方法以叫用外掛程式並傳回$userControl物件：

render : function() {
     var control = $.xfaWidget.numericInput.prototype.render.apply(this, arguments);
     var $control = $(control);
     var controlObject;
     try{
         if($control){
         $control.bootstrapNumber();
         var id = $control.attr("id");
         controlObject = $("#"+id);
         }
     }catch (exc){
          console.log(exc);
     }
     return controlObject;
}

在numericStepper-widget.js檔案中，覆寫getOptionsMap屬性以覆寫存取選項，並隱藏停用模式中的+和——按鈕。

getOptionsMap: function(){
    var parentOptionsMap = $.xfaWidget.numericInput.prototype.getOptionsMap.apply(this,arguments),

    newMap = $.extend({},parentOptionsMap,

     {

           "access": function(val) {
           switch(val) {
              case "open" :
                this.$userControl.removeAttr("readOnly");
                this.$userControl.removeAttr("aria-readonly");
                this.$userControl.removeAttr("disabled");
                this.$userControl.removeAttr("aria-disabled");
                this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                break;
              case "nonInteractive" :
              case "protected" :
                this.$userControl.attr("disabled", "disabled");
                this.$userControl.attr("aria-disabled", "true");
                this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                break;
             case "readOnly" :
                this.$userControl.attr("readOnly", "readOnly");
                this.$userControl.attr("aria-readonly", "true");
                this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                break;
            default :
                this.$userControl.removeAttr("disabled");
                this.$userControl.removeAttr("aria-disabled");
                this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                break;
          }
       },
   });
   return newMap;
 }

保存更改，導航到包含pom.xml檔案的資料夾，然後執行以下Maven命令來生成項目：

mvn clean install
使用AEM Package Manager安裝套件。
在編輯模式中開啟您要套用自訂外觀的最適化表單，並執行下列動作：
1. 按一下右鍵要應用外觀的欄位，然後按一下Edit開啟「編輯元件」對話框。
2. 在「樣式」標籤中，更新CSS類別屬性以新增widget_numericStepper。