为自适应表单设计 JSON 架构

前提条件

使用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"

}

  • 当类型为字符串且格式为电子邮件时,将映射电子邮件组件。
  • 当类型为字符串且格式为hostname时,将映射带验证的Textbox组件。

{

"type" : "string",

}



文本字段


数字属性
子类型设置为float的数字字段
integer属性
子类型设置为整数的数字字段
布尔属性
开关
对象属性
面板
数组属性 最小值和最大值分别等于minItems和maxItems的可重复面板。 仅支持同质数组。 因此,项约束必须是一个对象,而不是数组。

通用架构属性

自适应表单使用JSON架构中可用的信息来映射每个生成的字段。 特别是:

  • title 属性用作自适应表单组件的标签。
  • description 属性设置为自适应表单组件的详细说明。
  • default 属性用作自适应表单字段的初始值。
  • maxLength 属性设置为 maxlength 文本字段组件的属性。
  • minimummaximumexclusiveMinimum、和 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"
  }
 }
}

可重用架构定义

定义键用于标识可重用的架构。 可重用架构定义用于创建片段。 下面给出了具有定义的示例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,则表单组件中指定的数值或日期必须大于为最小属性指定的数值或日期。

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

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

minLength

字符串

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

  • 文本框
maxLength 字符串 指定组件中允许的最大字符数。 最大长度必须等于或大于零。
  • 文本框

pattern

字符串

指定字符的序列。 如果字符符合指定的模式,组件将接受这些字符。

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

  • 映射到XSD架构的所有自适应Forms组件
maxItems 字符串 指定数组中的最大项数。 最大项数必须等于或大于零。
minItems 字符串 指定数组中的最小项数。 最小项数必须等于或大于零。

不受支持的结构

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

  • 空类型
  • 合并类型,例如any和
  • OneOf、AnyOf、AllOf和NOT
  • 仅支持同质数组。 因此,项约束必须是对象,而不是数组。

常见问题

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

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

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

您有两个选项:

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

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

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

在此页面上