使用JSON結構建立最適化表單

必備條件

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

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

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",

}



文字欄位


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

公用架構屬性

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

  • title 屬性可作為最適化表單元件的標籤。
  • description 屬性會設定為適用性表單元件的長說明。
  • default 屬性可作為最適化表單欄位的初始值。
  • maxLength 屬性設為 maxlength 屬性。
  • minimum, maximum, exclusiveMinimum,和 exclusiveMaximum 屬性用於數值框元件。
  • 支援範圍 DatePicker component 其他JSON結構屬性 minDatemaxDate 已提供……
  • minItemsmaxItems 屬性可用來限制可從面板元件新增或移除的項目/欄位數。
  • readOnly 屬性設定 readonly 適用性表單元件的屬性。
  • required 屬性會將適用性表單欄位標示為必填欄位,但在面板中(其中type為object),最終提交的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"
  }
 }
}

可重複使用的架構定義

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

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

配置表單對象的指令碼或表達式

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組 配置表單對象的指令碼或表達式。 下表列出最適化表單元件支援的所有指令碼事件。

元件\事件 初始化
計算 可見性 驗證 已啟用 提交值 按一下 選項
文字欄位
數值欄位
數值步進器
選項按鈕
電話
切換
按鈕
核取方塊
下拉式清單
影像選擇
資料輸入欄位
日期挑選器
電子郵件
檔案附件
影像
Draw
面板

在JSON中使用事件的一些範例是,在初始化事件時隱藏欄位,並在值提交事件時設定其他欄位的值。 如需為指令碼事件建立運算式的詳細資訊,請參閱 適用性表單運算式.

以下是先前提及範例的範例JSON程式碼。

在初始化事件時隱藏欄位

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

在值提交事件時配置另一個欄位的值

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

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

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

結構屬性

資料類型

說明

Component

maximum

字串

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

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

minimum

字串

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

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

exclusiveMaximum

布林值

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

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

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

exclusiveMinimum

布林值

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

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

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

minLength

字串

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

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

pattern

字串

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

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

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

不支援的構造

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

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

常見問題

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

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

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

您有兩個選項:

  • 滾動瀏覽樹結構
  • 使用「搜尋」方塊來尋找元素

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

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

本頁內容