文件AEM as a Cloud Service使用手冊

設計自適應表單的 JSON 綱要 (核心元件) creating-adaptive-forms-using-json-schema

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主題：

建立對象：

  • undefined
  • undefined
  • undefined
  • undefined
版本
文章連結
Foundation
按一下這裡
核心元件
本文章

先決條件 prerequisites

使用JSON結構描述作為表單模型，根據核心元件製作調適型表單需要基本瞭解JSON結構描述。 建議您先閱讀下列內容，再閱讀本文。

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

Adobe Experience Manager Forms支援以現有JSON結構描述作為表單模型，根據核心元件建立最適化表單。 此JSON結構描述代表組織中後端系統產生或使用資料的結構。 您使用的JSON結構描述應符合v4規格。

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

  • JSON的結構在最適化表單的製作模式中，會以樹狀結構顯示在「內容尋找器」標籤中。 您可以根據核心元件，將元素從JSON階層拖曳並新增至調適型表單。
  • 您可以使用與關聯結構描述相容的JSON預先填入表單。
  • 在提交時，使用者輸入的資料會以JSON格式提交，且符合相關聯的結構描述。
  • 您也可以根據2012-20 version的規格，以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",
              }
JSON元素、屬性或屬性
最適化表單元件

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

語法，

{

"type" : "string",

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

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

}

下拉式元件：

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

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

語法，

{

"type" : "string",

"format" : "email"

}

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

{

"type" : "string",

}

文字欄位
number屬性
子型別設定為float
的數值欄位
整數屬性
子型別設定為整數
的數值欄位
布林值屬性
切換
物件屬性
面板
陣列屬性
可重複面板，最小值和最大值分別等於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屬性將最適化表單欄位標籤為必要，但在面板（其中型別為物件）中，最終提交的JSON資料具有的欄位具有與該物件對應的空白值。
  • pattern屬性設定為最適化表單中的驗證模式（規則運算式）。
  • JSON結構描述檔案的副檔名必須保留為.schema.json。 例如，<filename>.schema.json。

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

JSON結構描述v4
code language-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",
  },
  "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"
}
}
}
JSON結構描述2012-20
code language-json 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/employee.schema.json",
  "$defs": {
    "employee": {
      "type": "object",
      "properties": {
        "userName": {
          "type": "string"
        },
        "dateOfBirth": {
          "type": "string",
          "format": "date"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "language": {
          "type": "string"
        },
        "personalDetails": {
          "$ref": "#/$defs/personalDetails"
        },
        "projectDetails": {
          "$ref": "#/$defs/projectDetails"
        }
      },
      "required": [
        "userName",
        "dateOfBirth",
        "language"
      ]
    },
    "personalDetails": {
      "type": "object",
      "properties": {
        "GeneralDetails": {
          "$ref": "#/$defs/GeneralDetails"
        },
        "Family": {
          "$ref": "#/$defs/Family"
        },
        "Income": {
          "$ref": "#/$defs/Income"
        }
      }
    },
    "projectDetails": {
      "type": "array",
      "items": {
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "number"
          },
          "projects": {
            "$ref": "#/$defs/projects"
          }
        }
      },
      "minItems": 1,
      "maxItems": 4
    },
    "projects": {
      "type": "array",
      "items": {
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "number"
          },
          "projectsAdditional": {
            "$ref": "#/$defs/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",
        },
        "address": {
          "type": "string"
        }
      }
      }
  }
  }

從JSON結構描述V4到2020-12版本規範的主要變更為：

  • ID宣告為$id
  • 定義宣告為$defs

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

定義索引鍵是用來識別可重複使用的結構描述。 可重複使用的結構描述定義用於建立片段。 具有定義的範例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" }
  }
}

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

限制最適化表單元件的可接受值 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結構描述的最適化Forms元件
maxItems
字串
指定陣列中專案的最大數量。 最大專案數必須等於或大於零。
minItems
字串
指定陣列中專案的最小數目。 最小專案數必須等於或大於零。

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

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

  1. 前往https://server:host/system/console/configMgr的Experience ManagerWeb主控台。
  2. 找到​ 最適化表單與互動式通訊Web通道組態。
  3. 選取以在編輯模式中開啟設定。
  4. 選取​ 產生符合結構描述的資料 ​核取方塊。
  5. 儲存設定。

最適化表單與互動式通訊Web通道組態

不支援的建構 non-supported-constructs

最適化Forms不支援下列JSON結構描述：

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

常見問題 frequently-asked-questions

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

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

我在內容尋找器中有長而複雜的結構。 如何找到特定專案？

您有兩個選項：

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

什麼應該是JSON結構描述檔案的副檔名？

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

在基於核心元件的最適化Forms中，是否支援aem:afProperties作為JSON結構描述的一部分？

否，核心元件不支援aem:afProperties。 此屬性僅支援用於基礎元件。

另請參閱 see-also

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab