使用JSON結構描述建立調適型表單 creating-adaptive-forms-using-json-schema

Last update: Thu Dec 21 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

建立對象：

Beginner
Intermediate
User
Developer

Adobe 建議使用新式且可擴充的資料擷取核心元件，用來建立新的最適化表單或將最適化表單新增到 AEM Sites 頁面。這些元件代表最適化表單建立方面的重大進步，可確保令人印象深刻的使用者體驗。本文會介紹使用基礎元件編寫最適化表單的舊方法。

版本

文章連結

AEM as a Cloud Service

按一下這裡

AEM 6.5

本文章

先決條件 prerequisites

使用JSON結構描述作為自適應表單的表單模型編寫時，需要基本瞭解JSON結構描述。建議您先閱讀下列內容，再閱讀本文。

使用JSON結構描述作為表單模型 using-a-json-schema-as-form-model

Adobe Experience Manager Forms 支援使用現有JSON結構描述作為表單模型來建立調適型表單。此JSON結構描述代表組織中後端系統產生或使用資料的結構。您使用的JSON結構描述應符合 v4規格.

使用JSON結構描述的主要功能包括：

在最適化表單的製作模式下，JSON的結構會在內容尋找器索引標籤中以樹狀結構顯示。您可以從JSON階層拖曳元素並新增至最適化表單。
您可以使用與關聯結構描述相容的JSON預先填入表單。
在提交時，使用者輸入的資料會以JSON格式提交，且符合相關聯的結構描述。

JSON結構描述包含簡單和複雜的元素型別。元素具有將規則新增至元素的屬性。將這些元素和屬性拖曳至最適化表單時，會自動對應至對應的最適化表單元件。

JSON元素與最適化表單元件的對應如下：

"birthDate": {
              "type": "string",
              "format": "date",
              "pattern": "date{DD MMMM, YYYY}",
              "aem:affKeyword": [
                "DOB",
                "Date of Birth"
              ],
              "description": "Date of birth in DD MMMM, YYYY",
              "aem:afProperties": {
                "displayPictureClause": "date{DD MMMM, YYYY}",
                "displayPatternType": "date{DD MMMM, YYYY}",
                "validationPatternType": "date{DD MMMM, YYYY}",
                "validatePictureClause": "date{DD MMMM, YYYY}",
                "validatePictureClauseMessage": "Date must be in DD MMMM, YYYY format."
              }

JSON元素、屬性或屬性

最適化表單元件

具有enum和enumNames條件約束的字串屬性。

語法，

{

"type" : "string",

"enum" : ["M", "F"]

"enumNames" : ["Male", "Female"]

}

下拉式元件：

enumNames中列出的值會顯示在拖放方塊中。
列舉中列出的值會用於計算。

具有格式限制的字串屬性。例如，電子郵件和日期。

語法，

{

"type" : "string",

"format" : "email"

}

當型別為字串且格式為電子郵件時，會對映電子郵件元件。
當型別為字串且格式為主機名稱時，會對應具有驗證的Textbox元件。

{

"type" : "string",

}

文字欄位

number屬性

子型別設定為浮點數的數值欄位

integer屬性

子型別設為整數的數值欄位

布林值屬性

切換

物件屬性

面板

陣列屬性

可重複面板，最小值和最大值分別等於minItems和maxItems。僅支援同質陣列。因此專案限制必須是物件，而不是陣列。

通用結構描述屬性 common-schema-properties

最適化表單會使用JSON結構描述中可用的資訊來對應每個產生的欄位。尤其是：

此 title 屬性可作為最適化表單元件的標籤。
此 description 屬性會設定為最適化表單元件的完整說明。
此 default 屬性會作為最適化表單欄位的初始值。
此 maxLength 屬性設為 maxlength 文字欄位元件的屬性。
此 minimum， maximum， exclusiveMinimum、和 exclusiveMaximum 屬性用於數值方塊元件。
若要支援範圍 DatePicker component 其他JSON結構屬性 minDate 和 maxDate 提供……
此 minItems 和 maxItems 屬性是用來限制可從面板元件新增或移除的專案/欄位數量。
此 readOnly 屬性會設定 readonly 最適化表單元件的屬性。
此 required 屬性將調適型表單欄位標籤為必填欄位，但在面板（其中type為object）中，最終提交的JSON資料具有的欄位具有對應於該物件的空白值。
此 pattern 屬性已設定為最適化表單中的驗證模式（規則運算式）。
JSON結構描述檔案的副檔名必須保留為.schema.json。例如， <filename>.schema.json。

範例JSON結構描述 sample-json-schema

以下是JSON結構描述的範例。

{
 "$schema": "https://json-schema.org/draft-04/schema#",
 "definitions": {
  "employee": {
   "type": "object",
   "properties": {
    "userName": {
     "type": "string"
    },
    "dateOfBirth": {
     "type": "string",
     "format": "date"
    },
    "email": {
     "type": "string",
     "format": "email"
    },
    "language": {
     "type": "string"
    },
    "personalDetails": {
     "$ref": "#/definitions/personalDetails"
    },
    "projectDetails": {
     "$ref": "#/definitions/projectDetails"
    }
   },
   "required": [
    "userName",
    "dateOfBirth",
    "language"
   ]
  },
  "personalDetails": {
   "type": "object",
   "properties": {
    "GeneralDetails": {
     "$ref": "#/definitions/GeneralDetails"
    },
    "Family": {
     "$ref": "#/definitions/Family"
    },
    "Income": {
     "$ref": "#/definitions/Income"
    }
   }
  },
  "projectDetails": {
   "type": "array",
   "items": {
    "properties": {
     "name": {
      "type": "string"
     },
     "age": {
      "type": "number"
     },
     "projects": {
      "$ref": "#/definitions/projects"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  },
  "projects": {
   "type": "array",
   "items": {
    "properties": {
     "name": {
      "type": "string"
     },
     "age": {
      "type": "number"
     },
     "projectsAdditional": {
      "$ref": "#/definitions/projectsAdditional"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  },
  "projectsAdditional": {
   "type": "array",
   "items": {
    "properties": {
     "Additional_name": {
      "type": "string"
     },
     "Additional_areacode": {
      "type": "number"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  },
  "GeneralDetails": {
   "type": "object",
   "properties": {
    "age": {
     "type": "number"
    },
    "married": {
     "type": "boolean"
    },
    "phone": {
     "type": "number",
     "aem:afProperties": {
      "sling:resourceType": "/libs/fd/af/components/guidetelephone",
      "guideNodeClass": "guideTelephone"
     }
    },
    "address": {
     "type": "string"
    }
   }
  },
  "Family": {
   "type": "object",
   "properties": {
    "spouse": {
     "$ref": "#/definitions/spouse"
    },
    "kids": {
     "$ref": "#/definitions/kids"
    }
   }
  },
  "Income": {
   "type": "object",
   "properties": {
    "monthly": {
     "type": "number"
    },
    "yearly": {
     "type": "number"
    }
   }
  },
  "spouse": {
   "type": "object",
   "properties": {
    "name": {
     "type": "string"
    },
    "Income": {
     "$ref": "#/definitions/Income"
    }
   }
  },
  "kids": {
   "type": "array",
   "items": {
    "properties": {
     "name": {
      "type": "string"
     },
     "age": {
      "type": "number"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  }
 },
 "type": "object",
 "properties": {
  "employee": {
   "$ref": "#/definitions/employee"
  }
 }
}

可重複使用的結構描述定義 reusable-schema-definitions

定義索引鍵是用來識別可重複使用的結構描述。可重複使用的結構描述定義用於建立片段。這類似於在XSD中識別複雜型別。具有定義的JSON結構描述範例如下：

{
  "$schema": "https://json-schema.org/draft-04/schema#",

  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city":           { "type": "string" },
        "state":          { "type": "string" }
      },
      "required": ["street_address", "city", "state"]
    }
  },

  "type": "object",

  "properties": {
    "billing_address": { "$ref": "#/definitions/address" },
    "shipping_address": { "$ref": "#/definitions/address" }
  }
}

上述範例會定義客戶記錄，其中每個客戶都有送貨和帳單地址。兩個地址的結構相同（地址有街道地址、城市和州/省），因此最好不要重複這些地址。它也會讓您日後在變更欄位時輕鬆新增和刪除欄位。

在JSON結構描述定義中預先設定欄位 pre-configuring-fields-in-json-schema-definition

您可以使用 aem：afProperties 屬性來預先設定JSON結構描述欄位，以對應至自訂最適化表單元件。範例如下：

{
    "properties": {
        "sizeInMB": {
            "type": "integer",
            "minimum": 16,
            "maximum": 512,
            "aem:afProperties" : {
                 "sling:resourceType" : "/apps/fd/af/components/guideTextBox",
                 "guideNodeClass" : "guideTextBox"
             }
        }
    },
    "required": [ "sizeInMB" ],
    "additionalProperties": false
}

設定表單物件的指令碼或運算式 configure-scripts-or-expressions-for-form-objects

JavaScript是適用性表單的運算式語言。所有運算式都是有效的JavaScript運算式，並使用適用性表單指令碼模型API。您可以將表單物件預先設定為評估運算式在表單事件上。

使用aem：afproperties屬性預先設定最適化表單元件的最適化表單運算式或指令碼。例如，觸發初始化事件時，以下程式碼會設定電話欄位的值，並將值列印至記錄檔：

"telephone": {
  "type": "string",
  "pattern": "/\\d{10}/",
  "aem:affKeyword": ["phone", "telephone","mobile phone", "work phone", "home phone", "telephone number", "telephone no", "phone number"],
  "description": "Telephone Number",
  "aem:afProperties" : {
    "sling:resourceType" : "fd/af/components/guidetelephone",
    "guideNodeClass" : "guideTelephone",
    "events": {
      "Initialize" : "this.value = \"1234567890\"; console.log(\"ef:gh\") "
    }
  }
}

您應該是 forms-power-user group 設定表單物件的指令碼或運算式。下表列出最適化表單元件支援的所有指令碼事件。

元件\事件

初始化

計算

可見性

驗證

已啟用

提交值

按一下

選項

文字欄位

數值欄位

數值步進器

選項按鈕

電話

切換

按鈕

核取方塊

下拉式清單

影像選擇

資料輸入欄位

日期挑選器

電子郵件

檔案附件

影像

Draw

面板

在JSON中使用事件的一些範例包括：在初始化事件上隱藏欄位，以及在值認可事件上設定另一個欄位的值。如需建立指令碼事件運算式的詳細資訊，請參閱最適化表單運算式.

以下是上述範例的JSON程式碼範例。

在初始化事件上隱藏欄位 hiding-a-field-on-initialize-event

"name": {
    "type": "string",
    "aem:afProperties": {
        "events" : {
            "Initialize" : "this.visible = false;"
        }
    }
}

在值認可事件上設定另一個欄位的值 configure-value-of-another-field-on-value-commit-event

"Income": {
    "type": "object",
    "properties": {
        "monthly": {
            "type": "number",
            "aem:afProperties": {
                "events" : {
                    "Value Commit" : "IncomeYearly.value = this.value * 12;"
                }
            }
        },
        "yearly": {
            "type": "number",
            "aem:afProperties": {
                "name": "IncomeYearly"
            }
        }
    }
}

限制最適化表單元件的可接受值 limit-acceptable-values-for-an-adaptive-form-component

您可以將下列限制新增至JSON結構元素，以限制最適化表單元件可接受的值：

結構描述屬性

資料類型

說明

元件

maximum

字串

指定數值和日期的上限。預設會包含最大值。

數值方塊
數值步進器
日期挑選器

minimum

字串

指定數值和日期的下限。預設會包含最小值。

數值方塊
數值步進器
日期挑選器

exclusiveMaximum

布林值

如果為true，則表單元件中指定的數值或日期必須小於為maximum屬性指定的數值或日期。

如果為false，則表單元件中指定的數值或日期必須小於或等於為maximum屬性指定的數值或日期。

數值方塊
數值步進器
日期挑選器

exclusiveMinimum

布林值

如果為true，則表單元件中指定的數值或日期必須大於針對minimum屬性指定的數值或日期。

若為false，則表單元件中指定的數值或日期必須大於或等於針對minimum屬性指定的數值或日期。

數值方塊
數值步進器
日期挑選器

minLength

字串

指定元件中允許的最小字元數。最小長度必須等於或大於零。

文字方塊

maxLength

字串

指定元件中允許的最大字元數。最大長度必須等於或大於零。

文字方塊

pattern

字串

指定字元順序。如果字元符合指定的模式，元件會接受字元。

pattern屬性對應至對應的最適化表單元件的驗證模式。

對應至XSD結構描述的所有調適型表單元件

maxItems

字串

指定陣列中專案的最大數量。最大專案數必須等於或大於零。

minItems

字串

指定陣列中專案的最小數目。最小專案數必須等於或大於零。

啟用符合結構描述的資料 enablig-schema-compliant-data

若要讓所有JSON結構描述型最適化Forms在表單提交時產生結構描述相容的資料，請遵循下列步驟：

前往Experience Manager網頁主控台，位於 https://server:host/system/console/configMgr.
尋找 最適化表單和互動式通訊Web通道設定.
選取以在編輯模式中開啟設定。
選取 產生符合結構描述的資料 核取方塊。
儲存設定。

最適化表單和互動式通訊Web頻道設定

不支援的建構 non-supported-constructs

調適型表單不支援下列JSON結構描述：

Null型別
等位型別，例如any和
OneOf、AnyOf、AllOf及NOT
僅支援同質陣列。因此，專案限制必須是物件，而不是陣列。

常見問題 frequently-asked-questions

我為何無法為可重複的子表單（minOccours或maxOccurs值大於1）拖曳子表單的個別元素（由任何複雜型別產生的結構）？

在可重複的子表單中，您必須使用完整的子表單。如果您只想使用選擇性欄位，請使用整個結構並刪除不需要的結構。

我在內容尋找器中有個長而複雜的結構。如何尋找特定元素？

您有兩個選項：

捲動瀏覽樹狀結構
使用搜尋方塊來尋找元素

JSON結構描述檔案的副檔名應該為何？

JSON結構描述檔案的副檔名必須是.schema.json。例如， <filename>.schema.json。

recommendation-more-help

19ffd973-7af2-44d0-84b5-d547b0dffee2