使用JSON結構建立最適化表單 creating-adaptive-forms-using-json-schema

CAUTION
AEM 6.4已結束延伸支援,本檔案不再更新。 如需詳細資訊,請參閱 技術支援期. 尋找支援的版本 此處.

必備條件 prerequisites

使用JSON結構描述製作最適化表單模型,需要基本了解JSON結構描述。 建議在本文之前閱讀下列內容。

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

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

使用JSON結構描述的主要功能為:

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

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

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

JSON元素、屬性或屬性
最適化表單元件

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

語法,

{

"type" : "string",

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

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

}

下拉元件:

  • enumNames中列出的值將顯示在下拉框中。
  • 列舉中列出的值會用於計算。

具有格式約束的字串屬性。 例如,電子郵件和日期。

語法,

{

"type" : "string",

"format" : "email"

}

  • 類型為字串且格式為電子郵件時,會對應電子郵件元件。
  • 類型為字串且格式為主機名時,會對應具有驗證的TextBox元件。

{

"type" :"string",

}

文字欄位
數字屬性
子類型設定為float的數值欄位
整數屬性
子類型設為整數的數值欄位
布林屬性
切換
物件屬性
面板
陣列屬性
最小值和最大值分別等於minItems和maxItems的可重複面板。 僅支援同質陣列。 因此,項約束必須是對象而不是陣列。

公用架構屬性 common-schema-properties

適用性表單使用JSON結構描述中的可用資訊來對應每個產生的欄位。 特別是:

  • 標題屬性可作為最適化表單元件的標籤。
  • description屬性會設定為適用性表單元件的詳細說明。
  • 預設屬性可作為最適化表單欄位的初始值。
  • maxLength屬性被設定為文本欄位元件的maxlength屬性。
  • 「數值」框元件使用minimum、maximum、exclusiveMinimum和exclusiveMaximum屬性。
  • 為了支援DatePicker元件的範圍,提供了其他JSON結構屬性minDate和maxDate。
  • minItems和maxItems屬性用於限制可從面板元件添加或刪除的項目/欄位數。
  • readOnly屬性設定適用性表單元件的唯讀屬性。
  • 必要屬性會將適用性表單欄位標示為必填欄位,但如果是面板(其中type為object),最終提交的JSON資料則有與該物件對應之空白值的欄位。
  • 模式屬性在適用性表單中設定為驗證模式(規則運算式)。
  • 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
}

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

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

結構屬性
資料類型
說明
Component
maximum
字串
指定數值和日期的上界。 預設會包含最大值。
  • 數值方塊
  • 數值步進器
  • 日期挑選器
minimum
字串
指定數值和日期的下限。 預設會包含最小值。
  • 數值方塊
  • 數值步進器
  • 日期挑選器
exclusiveMaximum
布林值

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

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

  • 數值方塊
  • 數值步進器
  • 日期挑選器
exclusiveMinimum
布林值

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

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

  • 數值方塊
  • 數值步進器
  • 日期挑選器
minLength
字串
指定元件中允許的字元數量最小。 最小長度必須等於或大於零。
  • 文字方塊
maxLength
字串
指定元件中允許的字元數上限。 最大長度必須等於或大於零。
  • 文字方塊
pattern
字串

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

模式屬性映射到相應自適應表單元件的驗證模式。

  • 對應至XSD架構的所有適用性表單元件
maxItems
字串
指定陣列中的項目數上限。 最大項目必須等於或大於零。
minItems
字串
指定陣列中的最小項目數。 最小項目必須等於或大於零。

不支援的構造 non-supported-constructs

適用性表單不支援下列JSON結構:

  • Null類型
  • 聯合類型(如any)和
  • OneOf、AnyOf、AllOf和NOT
  • 僅支援同質陣列。 因此,項約束必須是對象而不是陣列。

常見問題 frequently-asked-questions

為什麼我無法為可重複的子表單拖曳子表單的個別元素(從任何複雜類型產生的結構)(minOccours或maxOccurs值大於1)?

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

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

您有兩個選項:

  • 滾動瀏覽樹結構
  • 使用「搜尋」方塊來尋找元素
recommendation-more-help
a6ebf046-2b8b-4543-bd46-42a0d77792da