JSON Schema 表单规范🧾 JSON Schema 表单规范 v1.0 JSON示例 Swift Demo h

🧾 JSON Schema 表单规范 v1.0

该规范用于描述一个表单页面的 UI、字段规则、交互逻辑和校验要求。支持分组、动态显隐、联动、正则等高级能力。

JSON示例

{
  "title": "注册信息",
  "sections": [
    {
      "title": "基础信息",
      "fields": [
        {
          "key": "name",
          "label": "姓名",
          "type": "text",
          "required": true,
          "placeholder": "请输入姓名"
        },
        {
          "key": "gender",
          "label": "性别",
          "type": "radio",
          "required": true,
          "options": [
            { "label": "男", "value": "male" },
            { "label": "女", "value": "female" }
          ]
        },
        {
          "key": "militaryStatus",
          "label": "服兵役情况",
          "type": "text",
          "placeholder": "如已服役/未服役",
          "visibleIf": {
            "gender": "male"
          }
        }
      ]
    },
    {
      "title": "联系方式",
      "fields": [
        {
          "key": "phone",
          "label": "手机号码",
          "type": "text",
          "validators": [
            {
              "type": "regex",
              "pattern": "^1[0-9]{10}$",
              "message": "请输入有效手机号"
            }
          ]
        }
      ]
    }
  ]
}

Swift Demo

chatgpt.com/canvas/shar…

📌 顶层结构

{
  "title": "表单标题",
  "sections": [ FormSection, ... ]
}

字段	类型	含义
title	string	整个表单的标题
sections	array	分区数组，每个分区有一个标题与若干字段

📦 FormSection

{
  "title": "分区标题",
  "fields": [ FormField, ... ]
}

字段	类型	含义
title	string	分区标题
fields	array	表单字段列表

🧩 FormField 字段属性说明

{
  "key": "字段标识",
  "label": "显示名称",
  "type": "字段类型",
  "required": true,
  "placeholder": "提示文本",
  "editable": true,
  "hidden": false,
  "options": [ Option ],
  "visibleIf": { "gender": "male" },
  "validators": [ Validator ]
}

字段	类型	说明
key	string	字段唯一标识（存值取值）
label	string	显示名
type	string	字段类型（见下表）
required	boolean	是否必填
placeholder	string	输入框提示文字
editable	boolean	是否可编辑
hidden	boolean	是否默认隐藏（不可见）
options	array of `Option`	可选项，仅限 select/radio
visibleIf	object `{k: v}`	显示条件（当 key==value 时显示）
validators	array of `Validator`	校验规则

支持的字段类型（type）：

类型	说明
text	普通文本输入框
textarea	多行文本
number	数字输入
select	下拉菜单
radio	单选组
checkbox	多选组（待扩展）
date	日期选择（可扩展）

🎛️ Option 配置（用于 select / radio）

{ "label": "男", "value": "male" }

字段	类型	含义
label	string	用户可见文字
value	string	实际提交值

✅ 校验 Validator

{
  "type": "regex",
  "pattern": "^1[0-9]{10}$",
  "message": "请输入有效手机号"
}

字段	类型	说明
type	string	当前仅支持 `"regex"`
pattern	string	正则表达式
message	string	错误提示文本

🎯 visibleIf 条件控制说明

用于控制字段是否显示，格式如下：

"visibleIf": {
  "gender": "male"
}

当 gender == "male" 时，该字段显示
支持多个条件（与关系）
可扩展支持数组值（如某字段 ∈ 多个值）

🧪 示例片段

{
  "key": "militaryStatus",
  "label": "服兵役情况",
  "type": "text",
  "visibleIf": {
    "gender": "male"
  }
}

🏁 约定建议（团队协作）

建议	说明
key 唯一	必须唯一，用于表单存储
所有文本请支持 i18n 协议	label / placeholder / message
支持 UI 端自定义字段类型扩展	可在 type 扩展为 `imageUploader`, `mapPicker` 等
使用 camelCase 命名字段	推荐风格一致