为自适应表单设计 JSON 架构 creating-adaptive-forms-using-json-schema

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

创建对象：

初学者
中级
用户
开发人员

版本

文章链接

核心组件

单击此处

Foundation

本文

Adobe 建议使用现代、可扩展的数据捕获核心组件，以创建新的自适应表单或将自适应表单添加到 AEM Sites 页面。这些组件代表有关创建自适应表单的重大改进，确保实现令人印象深刻的用户体验。本文介绍了使用基础组件创作自适应表单的旧方法。

版本

文章链接

AEM 6.5

单击此处

AEM as a Cloud Service

本文

先决条件 prerequisites

使用JSON架构作为自适应表单的表单模型创作时，需要基本了解JSON架构。建议在阅读本文之前通读以下内容。

使用JSON架构作为表单模型 using-a-json-schema-as-form-model

Adobe Experience Manager表单支持使用现有JSON架构作为表单模型来创建自适应表单。此JSON架构表示组织中的后端系统生成或使用数据的结构。您使用的JSON架构应符合v4规范。

使用JSON架构的主要功能包括：

在自适应表单的创作模式下，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",
              "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"

}

当类型为字符串且格式为电子邮件时，将映射电子邮件组件。
当类型为字符串且格式为hostname时，将映射带验证的文本框组件。

{

"type" : "string",

}

文本字段

数字属性

子类型设置为float
的数值字段

整数属性

子类型设置为integer
的数字字段

布尔属性

交换机

对象属性

面板

数组属性

可重复面板，最小值和最大值分别等于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。例如，<文件名>.schema.json。

示例JSON架构 sample-json-schema

JSON架构v4

code language-json

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

{
"$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架构2012-20

code language-json

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", "aem:afProperties": { "sling:resourceType": "/libs/fd/af/components/guidetelephone", "guideNodeClass": "guideTelephone" } }, "address": { "type": "string" } } } } }

{
  "$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",
          "aem:afProperties": {
            "sling:resourceType": "/libs/fd/af/components/guidetelephone",
            "guideNodeClass": "guideTelephone"
          }
        },
        "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" }
  }
}

上例定义了一个客户记录，其中每个客户都有一个送货地址和账单地址。两个地址的结构相同（地址具有街道地址、城市和州/省），因此最好不要重复这些地址。它还使得添加和删除字段对于任何未来的更改都非常容易。

在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架构元素添加以下限制，以限制自适应表单组件可以接受的值：

架构属性

数据类型

描述

组件

maximum

字符串

指定数值和日期的上限。默认情况下，包含最大值。

数值框
数值步进器
日期选取器

minimum

字符串

指定数值和日期的下限。默认情况下，将包含最小值。

数值框
数值步进器
日期选取器

exclusiveMaximum

布尔值

如果为true，则表单的组件中指定的数值或日期必须小于为maximum属性指定的数值或日期。

如果为false，则表单的组件中指定的数值或日期必须小于或等于为maximum属性指定的数值或日期。

数值框
数值步进器
日期选取器

exclusiveMinimum

布尔值

如果为true，则表单的组件中指定的数值或日期必须大于为最小属性指定的数值或日期。

如果为false，则表单的组件中指定的数值或日期必须大于或等于为minimum属性指定的数值或日期。

数值框
数值步进器
日期选取器

minLength

字符串

指定组件中允许的最小字符数。最小长度必须等于或大于零。

文本框

maxLength

字符串

指定组件中允许的最大字符数。最大长度必须等于或大于零。

文本框

pattern

字符串

指定字符的顺序。如果字符符合指定的模式，则组件接受这些字符。

pattern属性映射到相应自适应表单组件的验证模式。

映射到XSD架构的所有自适应Forms组件

maxItems

字符串

指定数组中的最大项数。最大项数必须等于或大于零。

minItems

字符串

指定数组中的最小项数。最小项数必须等于或大于零。

启用符合架构的数据 enablig-schema-compliant-data

要启用所有基于JSON架构的自适应Forms在提交表单时生成与架构兼容的数据，请执行以下步骤：

转到https://server:host/system/console/configMgr上的Experience ManagerWeb控制台。
找到 自适应表单和交互通信Web渠道配置。
选择以在编辑模式下打开配置。
选中 生成符合架构的数据 复选框。
保存设置。

自适应表单和交互式通信Web渠道配置

不受支持的结构 non-supported-constructs

自适应Forms不支持以下JSON架构结构：

空类型
合并类型，例如any和
OneOf、AnyOf、All和NOT
仅支持同质数组。因此，项约束必须是对象，而不是数组。
$ref中的URI引用

常见问题解答 frequently-asked-questions

为什么我无法为可重复的子表单（minOccours或maxOccurs值大于1）拖动子表单的单个元素（从任何复杂类型生成的结构）？

在可重复的子表单中，必须使用完整的子表单。如果只需要选择字段，请使用整个结构并删除不需要的字段。

我在内容查找器中有一个长且复杂的结构。如何查找特定元素？

您有两个选项：

滚动浏览树结构
使用搜索框查找元素

JSON架构文件的扩展名应该是什么？

JSON架构文件的扩展名必须是.schema.json。例如，<文件名>.schema.json。

另请参阅 see-also

recommendation-more-help

fbcff2a9-b6fe-4574-b04a-21e75df764ab