為最適化表單設計 JSON 綱要

必備條件

使用JSON架構作為其表單模型創作自適應表單需要對JSON架構有基本的瞭解。 建議在本文之前閱讀以下內容。

將JSON架構用作表單模型

Adobe Experience Manager格式支援使用現有JSON架構作為表單模型建立自適應表單。 此JSON架構表示組織中後端系統生成或使用資料的結構。 您使用的JSON架構應與 v4規格

使用JSON架構的主要功能有:

  • JSON的結構在Adaptive Form的創作模式下的「內容查找器」頁籤中顯示為樹。 您可以將元素從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"

}

  • 當類型為字串且格式為電子郵件時,將映射電子郵件元件。
  • 當類型為字串且格式為主機名時,將映射帶驗證的文本框元件。

{

"type" : "string",

}



文本欄位


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

公用架構屬性

自適應表單使用JSON架構中的可用資訊來映射每個生成的欄位。 特別是:

  • title 屬性用作Adaptive Form元件的標籤。
  • description 屬性設定為Adaptive Form元件的長說明。
  • default 屬性用作「自適應表單」欄位的初始值。
  • maxLength 屬性設定為 maxlength 文本欄位元件的屬性。
  • minimummaximumexclusiveMinimum, exclusiveMaximum 屬性用於「數字」框元件。
  • 支援範圍 DatePicker component 其他JSON架構屬性 minDatemaxDate
  • minItemsmaxItems 屬性用於限制可從面板元件中添加或刪除的項/欄位數。
  • readOnly 屬性設定 readonly 自適應表單元件的屬性。
  • required 屬性將「自適應表單」欄位標籤為必需欄位,而在面板(其中type為object)中,最終提交的JSON資料具有與該對象對應的空值欄位。
  • pattern 屬性設定為Adaptive Form中的驗證模式(規則運算式)。
  • 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 屬性,用於預配置要映射到自定義Adaptive Form元件的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架構元素,以限制Adaptive Form元件可接受的值:

架構屬性

資料類型

說明

元件

maximum

字串

指定數值和日期的上限。 預設情況下,包括最大值。

  • 數字框
  • 數值步進器
  • 日期挑選器

minimum

字串

指定數值和日期的下界。 預設情況下,包括最小值。

  • 數字框
  • 數值步進器
  • 日期挑選器

exclusiveMaximum

布林值 (Boolean)

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

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

  • 數字框
  • 數值步進器
  • 日期挑選器

exclusiveMinimum

布林值 (Boolean)

如果為true,則在窗體元件中指定的數值或日期必須大於為minimum屬性指定的數值或日期。

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

  • 數字框
  • 數值步進器
  • 日期挑選器

minLength

字串

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

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

pattern

字串

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

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

  • 映射到XSD架構的所有自適應Forms元件
maxItems 字串 指定陣列中的最大項數。 最大項必須等於或大於零。
minItems 字串 指定陣列中最小項數。 最小項必須等於或大於零。

不支援的構造

自適應Forms不支援以下JSON架構構造:

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

常見問題

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

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

我在Content Finder中有一個很長的複雜結構。 如何找到特定元素?

您有兩個選擇:

  • 滾動瀏覽樹結構
  • 使用「搜索」框查找元素

JSON架構檔案的副檔名應是什麼?

JSON架構檔案的副檔名必須為.schema.json。 比如說, <filename>.schema.json。

本頁內容