# Yida Create Form Page

> 宜搭表单页面创建与更新技能，支持创建新表单（saveFormSchemaInfo + saveFormSchema + updateFormConfig）和更新已有表单（getFormSchema + saveFormSchema + updateFormConfig），支持 19 种字段类型（含 SerialNumberField 流水号）和字段增删改操作。

- Skill: `openyida/yida-create-form-page-2` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add openyida/yida-create-form-page-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openyida/yida-create-form-page-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: openyida (https://skillmd.com/u/openyida)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/openyida/yida-create-form-page-2

---


# 宜搭表单页面创建与更新技能

## 概述

本技能描述如何通过 HTTP 请求调用宜搭接口**创建**或**更新**表单页面。支持两种模式：

- **create 模式**：创建新表单页面，定义字段列表、字段类型、选项等。先创建空白表单获取 formUuid，再保存表单 Schema。
- **update 模式**：更新已有表单页面，支持对字段进行增删改、调整属性等操作。先获取现有 Schema，应用修改后保存。

## 何时使用

当以下场景发生时使用此技能：
- 用户需要在应用中创建数据收集表单（如报名表、调查表）
- 用户需要创建带有字段的表单页面来存储数据
- 用户需要更新已有表单的字段（增删改）
- 已通过 yida-create-app 创建应用后，需要创建表单来收集数据

## 使用方式

### create 模式（创建新表单）

```bash
node .claude/skills/yida-create-form-page/scripts/create-form-page.js create <appType> <formTitle> <fieldsJsonOrFile>
```

**参数说明**：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `appType` | 是 | 应用 ID，如 `APP_XXX` |
| `formTitle` | 是 | 表单名称 |
| `fieldsJsonOrFile` | 是 | 字段定义，支持两种格式：JSON 字符串（以 `[` 开头）或 JSON 文件路径 |

**示例（JSON 字符串，推荐）**：

```bash
node .claude/skills/yida-create-form-page/scripts/create-form-page.js create "APP_XXX" "用户信息表" '[{"type":"TextField","label":"姓名","required":true},{"type":"SelectField","label":"部门","dataSource":[{"text":{"zh_CN":"技术部","en_US":"技术部","type":"i18n"},"value":"技术部","sid":"serial_xxx","disable":false,"defaultChecked":false},{"text":{"zh_CN":"产品部","en_US":"产品部","type":"i18n"},"value":"产品部","sid":"serial_xxx","disable":false,"defaultChecked":false}]}]'
```
**示例（JSON 文件）**：
```bash
node .claude/skills/yida-create-form-page/scripts/create-form-page.js create "APP_xxx" "用户信息表" .cache/user-info-fields.json
```

**输出**：日志输出到 stderr，JSON 结果输出到 stdout：

```json
{"success":true,"formUuid":"FORM-XXX","formTitle":"用户信息表","appType":"APP_xxx","fieldCount":4,"url":"{base_url}/APP_xxx/workbench/FORM-XXX"}
```

### update 模式（更新已有表单）

```bash
node .claude/skills/yida-create-form-page/scripts/create-form-page.js update <appType> <formUuid> <changesJsonOrFile>
```

**参数说明**：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `appType` | 是 | 应用 ID，如 `APP_XXX` |
| `formUuid` | 是 | 表单页面的唯一标识，如 `FORM-XXX` |
| `changesJsonOrFile` | 是 | 修改定义，支持两种格式：JSON 字符串（以 `[` 开头自动识别）或 JSON 文件路径 |

**示例（JSON 字符串，推荐）**：

```bash
node .claude/skills/yida-create-form-page/scripts/create-form-page.js update "APP_xxx" "FORM-yyy" '[{"action":"add","field":{"type":"TextField","label":"备注"}}]'
```

**示例（JSON 文件）**：

```bash
node .claude/skills/yida-create-form-page/scripts/create-form-page.js update "APP_xxx" "FORM-yyy" changes.json
```

**输出**：日志输出到 stderr，JSON 结果输出到 stdout：

```json
{"success":true,"formUuid":"FORM-YYY","appType":"APP_XXX","changesApplied":3,"changes":[...],"url":"https://www.aliwork.com/APP_XXX/workbench/FORM-YYY"}
```

## 字段定义 JSON 格式

字段定义是一个 JSON 数组，每个元素描述一个字段。

```json
[
  { "type": "TextField", "label": "姓名", "required": true },
  { "type": "SelectField", "label": "部门", "dataSource": [{"text":{"zh_CN":"技术部","en_US":"技术部","type":"i18n"},"value":"技术部","sid":"serial_xxx","disable":false,"defaultChecked":false},{"text":{"zh_CN":"产品部","en_US":"产品部","type":"i18n"},"value":"产品部","sid":"serial_xxx","disable":false,"defaultChecked":false}] },
  { "type": "DateField", "label": "入职日期" },
  { "type": "NumberField", "label": "年龄" },
  { "type": "TableField", "label": "费用明细", "children": [
    { "type": "TextField", "label": "项目" },
    { "type": "NumberField", "label": "金额" }
  ]}
]
```

**字段属性**：

| 属性 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `type` | String | 是 | 字段类型（见下方支持的字段类型） |
| `label` | String | 是 | 字段标签 |
| `required` | Boolean | 否 | 是否必填，**默认 `false`（非必填）** |
| `placeholder` | String | 否 | 占位提示文本 |
| `behavior` | String | 否 | 字段行为，`NORMAL`（正常，默认）/ `READONLY`（只读）/ `HIDDEN`（隐藏） |
| `visibility` | String[] | 否 | 显示端，`["PC", "MOBILE"]`（默认）/ `["PC"]`（仅 PC）/ `["MOBILE"]`（仅移动端） |
| `labelAlign` | String | 否 | 标签对齐方式，`top`（默认）/ `left` / `right` |
| `dataSource` | Array | 条件必填 | 选项数据源数组，**选项类字段（RadioField/SelectField/CheckboxField/MultiSelectField）必填**。每个元素是选项对象，格式详见下方各字段类型说明 |
| `multiple` | Boolean | 否 | 是否多选，`EmployeeField`/`DepartmentSelectField`/`CountrySelectField`/`AssociationFormField` 可用 |
| `children` | Object[] | 条件必填 | 子字段列表，`TableField` 必填 |
| `associationForm` | Object | 条件必填 | 关联表单配置对象，`AssociationFormField` 必填，详见下方说明 |

### 各字段类型默认属性

以下列出各字段类型创建时自动设置的**特有**默认属性（通用属性如 `fieldId`、`label`、`behavior`、`visibility` 等所有字段共享，不再重复列出）。

#### TextField / TextareaField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `validationType` | `"text"` | 校验类型 |
| `maxLength` | `200` | 最大字符数 |
| `hasClear` | `true` | 显示清除按钮 |
| `isCustomStore` | `true` | 自定义存储 |
| `scanCode.enabled` | `false` | 扫码输入 |

#### NumberField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `precision` | `0` | 小数位数 |
| `step` | `1` | 步进值 |
| `thousandsSeparators` | `false` | 千分位分隔符 |
| `isCustomStore` | `true` | 自定义存储 |
| `innerAfter` | "" | 单位 |


#### RateField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `count` | `5` | 星级总数 |
| `allowHalf` | `false` | 允许半星 |
| `showGrade` | `false` | 显示等级文案 |

#### RadioField / CheckboxField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `dataSourceType` | `"custom"` | 数据源类型 |
| `valueType` | `"custom"` | 值类型 |
| `dataSource` | 数组 | 选项数据源数组，每个元素是选项对象 |
| `defaultDataSource` | 对象 | 默认数据源配置，包含 `options` 数组 |

**`dataSource` 数组元素结构**：

| 属性 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `text` | Object | 是 | 选项显示文本，i18n 对象格式 |
| `text.zh_CN` | String | 是 | 中文显示文本，**必须是字符串** |
| `text.en_US` | String | 是 | 英文显示文本，**必须是字符串** |
| `text.type` | String | 是 | 固定为 `"i18n"` |
| `value` | String | 是 | 选项值，**必须是字符串** |
| `sid` | String | 是 | 选项唯一标识，格式为 `serial_xxx` |
| `disable` | Boolean | 否 | 是否禁用，默认 `false` |
| `defaultChecked` | Boolean | 否 | 是否默认选中，默认 `false` |

**`defaultDataSource` 对象结构**：

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `complexType` | String | 固定为 `"custom"` |
| `options` | Array | 选项数组，元素结构与 `dataSource` 相同 |
| `formula` | String | 公式配置，默认空字符串 |
| `url` | String | 数据源 URL，默认空字符串 |
| `searchConfig` | Object | 搜索配置 |
| `searchConfig.type` | String | 请求类型，固定为 `"JSONP"` |
| `searchConfig.url` | String | 请求 URL，默认空字符串 |
| `searchConfig.beforeFetch` | String | 请求前处理脚本，默认空字符串 |
| `searchConfig.afterFetch` | String | 请求后处理脚本，默认空字符串 |

**完整示例**：

```json
{
  "dataSourceType": "custom",
  "dataSource": [
    {
      "text": { "zh_CN": "选项一", "en_US": "Option 1", "type": "i18n" },
      "value": "选项一",
      "sid": "serial_khe7yak4",
      "disable": false,
      "defaultChecked": false
    }
  ],
  "defaultDataSource": {
    "complexType": "custom",
    "options": [
      {
        "text": { "zh_CN": "选项一", "en_US": "Option 1", "type": "i18n" },
        "value": "选项一",
        "sid": "serial_khe7yak4",
        "disable": false,
        "defaultChecked": false
      }
    ],
    "formula": "",
    "url": "",
    "searchConfig": {
      "type": "JSONP",
      "url": "",
      "beforeFetch": "",
      "afterFetch": ""
    }
  }
}
```

#### SelectField / MultiSelectField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `showSearch` | `true` | 支持搜索 |
| `autoWidth` | `true` | 自动宽度 |
| `filterLocal` | `true` | 本地过滤 |
| `mode` | `"single"` / `"multiple"` | 选择模式 |
| `dataSourceType` | `"custom"` | 数据源类型 |
| `dataSource` | 数组 | 选项数据源数组，每个元素是选项对象 |
| `defaultDataSource` | 对象 | 默认数据源配置，包含 `options` 数组 |

**选项数据格式**：与 RadioField/CheckboxField 完全一致，每个选项对象包含以下属性：

| 属性 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `text` | Object | 是 | 选项显示文本，i18n 对象格式 |
| `text.zh_CN` | String | 是 | 中文显示文本，**必须是字符串** |
| `text.en_US` | String | 是 | 英文显示文本，**必须是字符串** |
| `text.type` | String | 是 | 固定为 `"i18n"` |
| `value` | String | 是 | 选项值，**必须是字符串** |
| `sid` | String | 是 | 选项唯一标识，格式为 `serial_xxx` |
| `disable` | Boolean | 否 | 是否禁用，默认 `false` |
| `defaultChecked` | Boolean | 否 | 是否默认选中，默认 `false` |

**`defaultDataSource` 对象结构**：
- `complexType`: `"custom"`
- `options`: 选项数组，元素结构与 `dataSource` 相同
- `formula`: 公式配置，默认空字符串
- `url`: 数据源 URL，默认空字符串
- `searchConfig`: 搜索配置对象，包含 `type`（固定 `"JSONP"`）、`url`、`beforeFetch`、`afterFetch`


#### DateField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `format` | `"YYYY-MM-DD"` | 日期格式 |
| `hasClear` | `true` | 显示清除按钮 |
| `resetTime` | `false` | 重置时间 |
| `disabledDate.type` | `"none"` | 禁用日期规则 |
format 格式：
- `"YYYY"`：年
- `"YYYY-MM"`：年-月
- `"YYYY-MM-DD"`：年-月-日
- `"YYYY-MM-DD HH:mm"`：年-月-日 时分
- `"YYYY-MM-DD HH:mm:ss"`：年-月-日 时分秒


#### CascadeDateField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `format` | `"YYYY-MM-DD"` | 日期格式 |
| `hasClear` | `true` | 显示清除按钮 |
| `resetTime` | `false` | 重置时间 |
format 格式：
- `"YYYY"`：年
- `"YYYY-MM"`：年-月
- `"YYYY-MM-DD"`：年-月-日
- `"YYYY-MM-DD HH:mm"`：年-月-日 时分
- `"YYYY-MM-DD HH:mm:ss"`：年-月-日 时分秒


#### EmployeeField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `userRangeType` | `"ALL"` | 人员范围 |
| `showEmpIdType` | `"NAME"` | 显示方式 |
| `startWithDepartmentId` | `"SELF"` | 起始部门 |
| `renderLinkForView` | `true` | 查看时渲染链接 |
| `closeOnSelect` | `false` | 选择后关闭 |
> 如果需要人员默认选中当前登录人，用法参考 `reference/employee-field.md`


#### DepartmentSelectField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `deptRangeType` | `"ALL"` | 部门范围 |
| `mode` | `"single"` | 选择模式 |
| `isShowDeptFullName` | `false` | 显示部门全路径 |
| `hasSelectAll` | `false` | 全选按钮 |

#### CountrySelectField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `mode` | `"single"` | 选择模式 |
| `showSearch` | `true` | 支持搜索 |
| `hasSelectAll` | `false` | 全选按钮 |

#### AddressField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `countryMode` | `"default"` | 国家模式 |
| `addressType` | `"ADDRESS"` | 地址类型 |
| `enableLocation` | `true` | 启用定位 |
| `showCountry` | `false` | 显示国家 |

#### AttachmentField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `listType` | `"text"` | 列表展示类型 |
| `multiple` | `true` | 允许多文件 |
| `limit` | `9` | 最大文件数 |
| `maxFileSize` | `100` | 最大文件大小(MB) |
| `autoUpload` | `true` | 自动上传 |
| `onlineEdit` | `false` | 在线编辑 |

#### ImageField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `listType` | `"image"` | 列表展示类型 |
| `multiple` | `true` | 允许多图片 |
| `limit` | `9` | 最大图片数 |
| `maxFileSize` | `50` | 最大文件大小(MB) |
| `accept` | `"image/*"` | 接受文件类型 |
| `enableCameraDate` | `true` | 拍照水印日期 |
| `enableCameraLocation` | `true` | 拍照水印定位 |
| `onlyCameraUpload` | `false` | 仅拍照上传 |

#### TableField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `showIndex` | `true` | 显示行号 |
| `pageSize` | `20` | 每页行数 |
| `maxItems` | `500` | 最大行数 |
| `minItems` | `1` | 最小行数 |
| `layout` | `"TABLE"` | PC 端布局 |
| `mobileLayout` | `"TILED"` | 移动端布局 |
| `theme` | `"split"` | 表格主题 |
| `showActions` | `true` | 显示操作列 |
| `showDelAction` | `true` | 显示删除按钮 |
| `showCopyAction` | `false` | 显示复制按钮 |
| `enableExport` | `true` | 允许导出 |
| `enableImport` | `true` | 允许导入 |
| `enableBatchDelete` | `false` | 批量删除 |
| `enableSummary` | `false` | 启用汇总 |
| `isFreezeOperateColumn` | `true` | 冻结操作列 |

#### AssociationFormField

> 详细用法参考 `reference/association-form-field.md`

#### SerialNumberField

| 属性 | 默认值 | 说明 |
| --- | --- | --- |
| `serialNumberRule` | 默认规则（前缀+自动递增） | 流水号生成规则数组 |
| `serialNumPreview` | `"serial00001"` | 流水号预览 |
| `serialNumReset` | `1` | 重置起始值 |
| `syncSerialConfig` | `false` | 是否同步流水号配置 |
| `formula` | 自动生成 | 流水号公式（由系统自动生成，包含 corpId、appType、formUuid、fieldId 和规则配置） |

**默认流水号规则**：
- 规则1：固定前缀 "serial"（4位）
- 规则2：自动递增数字（5位，从1开始，不重置）

**formula 格式**（对象格式，不是字符串）：
```json
{
  "formula": {
    "expression": "SERIALNUMBER(\"<corpId>\", \"<appType>\", \"<formUuid>\", \"<fieldId>\", \"<escapedRuleJson>\")"
  }
}
```

其中 `<escapedRuleJson>` 是 `{ "type": "custom", "value": <serialNumberRule数组> }` 的 JSON 字符串，需对双引号转义（`"` → `\"`）。

> 详细用法参考 `reference/serial-number-field.md`


## 修改定义 JSON 格式（update 模式）

修改定义是一个 JSON 数组，每个元素描述一条修改操作。可以直接作为命令行参数传入 JSON 字符串，也可以写入文件后传入文件路径。

```json
[
  { "action": "add", "field": { "type": "TextField", "label": "姓名", "required": true } },
  { "action": "add", "field": { "type": "SelectField", "label": "部门", "dataSource": [{"text":{"zh_CN":"技术部","en_US":"技术部","type":"i18n"},"value":"技术部","sid":"serial_xxx","disable":false,"defaultChecked":false},{"text":{"zh_CN":"产品部","en_US":"产品部","type":"i18n"},"value":"产品部","sid":"serial_xxx","disable":false,"defaultChecked":false}] }, "after": "姓名" },
  { "action": "delete", "label": "备注" },
  { "action": "update", "label": "年龄", "changes": { "required": true, "placeholder": "请输入年龄" } },
  { "action": "update", "label": "状态", "changes": { "label": "审批状态", "dataSource": [{"text":{"zh_CN":"待审批","en_US":"待审批","type":"i18n"},"value":"待审批","sid":"serial_xxx","disable":false,"defaultChecked":false},{"text":{"zh_CN":"已通过","en_US":"已通过","type":"i18n"},"value":"已通过","sid":"serial_xxx","disable":false,"defaultChecked":false},{"text":{"zh_CN":"已拒绝","en_US":"已拒绝","type":"i18n"},"value":"已拒绝","sid":"serial_xxx","disable":false,"defaultChecked":false}] } }
]
```

### 操作类型

| 操作 | 必填属性 | 可选属性 | 说明 |
| --- | --- | --- | --- |
| `add` | `field.type`, `field.label` | `after`, `before`, `field.required`, `field.options`, `field.placeholder`, `field.multiple`, `field.children`, `field.behavior`, `field.visibility`, `field.labelAlign` | 新增字段，`after`/`before` 指定插入位置（按字段标签匹配） |
| `delete` | `label` | — | 删除指定标签的字段 |
| `update` | `label`, `changes` | `tableLabel` | 修改指定标签字段的属性；若字段在子表内，需通过 `tableLabel` 指定父子表标签 |

### update 的 changes 支持的属性

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| `label` | String | 修改字段标签 |
| `required` | Boolean | 修改是否必填 |
| `placeholder` | String | 修改占位提示 |
| `dataSource` | Array | 修改选项数据源（选项类字段：RadioField/SelectField/CheckboxField/MultiSelectField），每个元素是选项对象，格式见 [RadioField 选项格式](#radiofield--checkboxfield) |
| `multiple` | Boolean | 修改是否多选（EmployeeField/DepartmentSelectField/CountrySelectField） |
| `behavior` | String | 修改字段行为：`NORMAL` / `READONLY` / `HIDDEN` |
| `visibility` | String[] | 修改显示端：`["PC", "MOBILE"]` / `["PC"]` / `["MOBILE"]` |
| `innerAfter` | String | 修改数字字段单位（仅 `NumberField` 可用），如 `"H"`、`"元"` |

### add 的 field 字段定义

与 create 模式的字段定义格式完全一致，参见上方「字段定义 JSON 格式」章节。


## 前置依赖

- Node.js
- 项目根目录存在 `.cache/cookies.json`（首次运行会自动触发扫码登录）

## 调用流程

### create 模式

1. 准备字段定义 JSON 文件
2. 读取项目根目录的 `.cache/cookies.json` 获取登录态（包含 corpId）；若不存在则自动调用 `login.py` 触发扫码登录
3. 调用 `saveFormSchemaInfo` 接口创建空白表单，获取 formUuid；根据响应体 `errorCode` 自动处理异常（详见 `yida-login` 技能文档「错误处理机制」章节）
4. 根据字段定义生成表单 Schema JSON（SerialNumberField 的 formula 会自动使用 corpId、appType、formUuid 和 fieldId 构建）
5. 调用 `saveFormSchema` 接口保存 Schema；同样根据响应体 `errorCode` 自动处理异常
6. 调用 `updateFormConfig` 接口更新表单配置（MINI_RESOURCE = 0）；同样根据响应体 `errorCode` 自动处理异常

### update 模式

1. 读取项目根目录的 `.cache/cookies.json` 获取登录态（包含 corpId）；若不存在则自动调用 `login.py` 触发扫码登录
2. 调用 `getFormSchema` 接口获取当前表单的完整 Schema；根据响应体 `errorCode` 自动处理异常：
   - `errorCode: "TIANSHU_000030"`（csrf 校验失败）→ 自动刷新 csrf_token 后重试
   - `errorCode: "307"`（登录过期）→ 自动重新登录后重试
3. 解析修改定义（JSON 字符串或 JSON 文件）
4. 按顺序执行每条修改操作：
   - **add**：构建新字段组件，插入到指定位置（或末尾）
   - **delete**：按标签查找并移除字段
   - **update**：按标签查找字段并更新其属性
5. 为所有 SerialNumberField 设置 formula（使用 corpId、appType、formUuid 和 fieldId）
6. 调用 `saveFormSchema` 接口保存修改后的 Schema；同样根据响应体 `errorCode` 自动处理异常（同上）
7. 调用 `updateFormConfig` 接口更新表单配置（MINI_RESOURCE = 0）；同样根据响应体 `errorCode` 自动处理异常（同上）

## 文件结构

```
yida-create-form-page/
├── SKILL.md                    # 本文档
└── scripts/
    ├── create-form-page.js     # 表单页面创建 & 更新脚本
```



## 支持的字段类型

| 字段类型 | componentName | 说明 | 特殊属性 |
| --- | --- | --- | --- |
| `TextField` | TextField | 单行文本，用于姓名、标题、编号等 | — |
| `TextareaField` | TextareaField | 多行文本，用于描述、备注等 | — |
| `RadioField` | RadioField | 单选，用于性别、状态等互斥选项 | `options` |
| `SelectField` | SelectField | 下拉单选，适合选项较多（>5）的场景 | `options` |
| `CheckboxField` | CheckboxField | 多选，用于兴趣爱好、技能标签等 | `options` |
| `MultiSelectField` | MultiSelectField | 下拉多选，适合选项较多（>5）的场景 | `options` |
| `NumberField` | NumberField | 数字，用于金额、数量、年龄等 | — |
| `RateField` | RateField | 评分，用于满意度评价等星级打分 | — |
| `DateField` | DateField | 日期，用于生日、截止日期等 | — |
| `CascadeDateField` | CascadeDateField | 级联日期，用于日期范围选择 | — |
| `EmployeeField` | EmployeeField | 成员，选择组织内成员 | `multiple` |
| `DepartmentSelectField` | DepartmentSelectField | 部门，选择组织内部门 | `multiple` |
| `CountrySelectField` | CountrySelectField | 国家，选择国家/地区 | `multiple` |
| `AddressField` | AddressField | 地址，用于收货地址等 | — |
| `AttachmentField` | AttachmentField | 附件上传 | — |
| `ImageField` | ImageField | 图片上传 | — |
| `TableField` | TableField | 表格（子表），用于结构化数据 | `children` |
| `AssociationFormField` | AssociationFormField | 关联表单 | `associationForm` |
| `SerialNumberField` | SerialNumberField | 流水号，自动生成唯一编号 | `serialNumberRule` |

## 与其他技能配合

1. **创建应用** → 使用 `yida-create-app` 技能获取 `appType`
2. **创建表单页面** → 本技能（create 模式），获取 `formUuid` 和字段 ID
3. **更新表单页面** → 本技能（update 模式），对已有表单进行字段增删改
4. **获取表单 Schema** → 可使用 `get-schema` 技能预先查看当前表单结构
5. **记录配置** → 将 `formUuid` 和字段 ID 写入 `prd/<项目名>.md`
6. **创建自定义页面** → 使用 `yida-create-page` 技能
7. **部署页面代码** → 使用 `yida-publish` 技能

> **提示**：如果需要创建的是自定义展示页面（无字段，用于部署 JSX 代码），请使用 `yida-create-page` 和 `yida-custom-page` 技能。


## 注意事项
- **临时文件写在当前工程根目录的 .cache 文件夹中，如果没有就创建一个文件夹，注意不要写在系统的其他文件夹中**
- update 模式中，修改定义 JSON 的操作按顺序执行，注意操作间的依赖关系（如先删后加）
- 字段匹配基于中文标签（`label.zh_CN`），确保标签名称准确
- 新增字段时会自动更新 `componentsMap`，无需手动处理
- 建议在重要修改前先通过 `get-schema` 技能查看当前 Schema 结构
- 脚本兼容旧的 create 模式调用方式（不带 `create` 前缀），但推荐使用新的显式模式参数


## 其他 yida-api 参考路径

| 文档 | 路径 | 说明 |
| --- | --- | --- |
| 宜搭 JS API | `reference/yida-api.md` | 表单操作类 API（7 个）、流程操作类 API（6 个）、表单设计类 API（4 个）、工具类 API（14 个），共 31 个 API 的完整参数与示例 |
| 大模型 AI 接口 | `reference/model-api.md` | AI 文本生成接口的请求参数、返回值结构与调用示例 |

### 表单设计类 API 说明

表单设计类 API 位于 `reference/yida-api.md` 的「表单设计类 API」章节，包含以下 4 个接口：

| 接口 | 说明 |
| --- | --- |
| `saveFormSchemaInfo` | 创建空白表单（create 模式），返回新创建的 `formUuid` |
| `getFormSchema` | 获取表单 Schema（update 模式），返回完整的表单 Schema JSON |
| `saveFormSchema` | 保存表单 Schema（create/update 两种模式共用） |
| `updateFormConfig` | 更新表单配置（设置 `MINI_RESOURCE` 等配置项） |

### 表单数据操作 API 说明

表单操作类 API 位于 `reference/yida-api.md` 的「表单操作类 API」章节，包含以下 7 个接口：

| 接口 | 说明 |
| --- | --- |
| `saveFormData` | 新建表单实例，用于提交表单数据 |
| `updateFormData` | 更新表单中指定组件值 |
| `searchFormDataIds` | 根据条件搜索表单实例 ID 列表 |
| `getFormComponentDefinationList` | 获取表单定义（字段结构） |
| `deleteFormData` | 删除表单实例 |
| `getFormDataById` | 根据表单实例 ID 查询表单实例详情 |
| `searchFormDatas` | 根据条件搜索表单实例详情列表 |

**常用场景**：

- **Mock 数据**：使用 `saveFormData` 批量创建测试数据
- **数据查询**：使用 `searchFormDatas` 或 `getFormDataById` 获取表单数据
- **数据更新**：使用 `updateFormData` 修改已有表单数据
- **数据清理**：使用 `deleteFormData` 删除测试数据

**使用示例**（Mock 数据）：

```javascript
// 创建测试数据
this.utils.yida.saveFormData({
  formUuid: 'FORM-XXX',
  appType: 'APP_XXX',
  formDataJson: JSON.stringify({
    textField_xxx: '测试姓名',
    selectField_xxx: '选项一',
    numberField_xxx: 100,
  }),
}).then((res) => {
  console.log('创建成功，实例ID:', res.result);
});
```


