為最適化表單設計 JSON 綱要

上次更新: 2023-10-18
  • 建立對象:
  • Beginner
    Intermediate
    User
    Developer

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

版本 文章連結
AEM 6.5 按一下這裡
AEM as a Cloud Service 本文章

先決條件

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

使用JSON結構描述作為表單模型

Adobe Experience Manager表單支援使用現有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。 僅支援同質陣列。 因此專案限制必須是物件,而不是陣列。

通用結構描述屬性

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

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

範例JSON結構描述

以下是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"
  }
 }
}

可重複使用的結構描述定義

定義索引鍵是用來識別可重複使用的結構描述。 可重複使用的結構描述定義用於建立片段。 具有定義的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結構描述定義中預先設定欄位

您可以使用 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
}

限制最適化表單元件的可接受值

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

結構描述屬性

資料類型

說明

元件

maximum

字串

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

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

minimum

字串

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

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

exclusiveMaximum

布林值

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

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

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

exclusiveMinimum

布林值

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

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

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

minLength

字串

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

  • 文字方塊
maxLength 字串 指定元件中允許的最大字元數。 最大長度必須等於或大於零。
  • 文字方塊

pattern

字串

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

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

  • 所有對應至XSD結構描述的最適化Forms元件
maxItems 字串 指定陣列中專案的最大數量。 最大專案數必須等於或大於零。
minItems 字串 指定陣列中專案的最小數目。 最小專案數必須等於或大於零。

啟用符合結構描述的資料

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

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

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

不支援的建構

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

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

常見問題

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

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

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

您有兩個選項:

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

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

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

另請參閱

此頁面上的