cloud-web-corejs 1.0.54-dev.8 → 1.0.54-dev.800

package/src/components/xform/docs//345/220/216/345/217/260/345/255/227/346/256/265/357/274/210/345/212/250/346/200/201/347/224/237/346/210/220/357/274/211JSON /350/257/264/346/230/216.md"

@@ -0,0 +1,1286 @@
+# 后台字段（动态生成）JSON 说明
+
+> 适用场景：
+> - 表格布局容器（`table`）启用 **动态字段**（`dynamicSchemaSourceType` 为 `script` 或 `api`）
+> - 数据表格（`data-table`）启用 **接口动态列**（`dynamicColumnSourceType: api`）或 **前端列脚本**（`script`）
+>
+> 二者共用同一套请求/响应与字段定义 JSON 格式（见 `utils/dynamicSchemaUtil.js`）。
+>
+> **文档分工：** 本文维护控件类型与 options（**唯一维护点**）；数据表格差异（width、formatS、操作列等）见 [`数据表格动态列 JSON 说明.md`](./数据表格动态列%20JSON%20说明.md)。
+>
+> 相关代码：`form-render/container-item/dynamicFieldMixin.js`、`data-table-mixin.js`
+
+---
+
+## 1. 调用流程
+
+```
+table mounted
+  → 加载条件脚本（可选）
+  → script：执行 dynamicSchemaScript
+  → api：请求 dynamicSchemaScriptCode
+  → 解析 objx → 按 dynamicSchemaMode 插入行布局
+  → 各字段控件初始化（下拉/状态等可能再次请求选项数据）
+  → （业务需要时）脚本调用 loadDynamicSchema() 重新加载，见 §1.5
+```
+
+| 设计器配置 | 属性名 |
+|-----------|--------|
+| 动态字段来源 | `dynamicSchemaSourceType`：`none` / `script` / `api` |
+| 前端字段脚本 | `dynamicSchemaScript` |
+| 脚本编码 | `dynamicSchemaScriptCode` |
+| 额外参数 | `dynamicSchemaScriptParam` |
+| 转换脚本 | `dynamicSchemaConvert` |
+| 加载条件 | `dynamicSchemaLoadScript` |
+| 生成模式 | `dynamicSchemaMode`：`append` / `replace` / `anchor` |
+
+> 设计器入口：选中 **table 容器** → 属性面板 **动态字段** 区块（布局与数据表格「列与动态列」一致）。  
+> 旧表单若仍含 `dynamicSchemaEnabled: true`，运行时按 `api` 模式兼容。
+
+### 1.1 请求参数（前端 → 后台字段脚本）
+
+```json
+{
+  "formData": {
+    "id": "10001",
+    "billType": "PO"
+  },
+  "bizType": "A"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `formData` | 当前表单数据（`formModel`），固定传入 |
+| 其余字段 | 由容器属性「额外参数」脚本动态返回 |
+
+### 1.2 响应外层结构
+
+```json
+{
+  "type": "success",
+  "message": "ok",
+  "objx": []
+}
+```
+
+### 1.3 objx 解析规则（未配置转换脚本时）
+
+按以下优先级取字段/列定义数组：
+
+| 优先级 | 结构 | 场景 |
+|--------|------|------|
+| 1 | `objx` 为数组 | 通用 |
+| 2 | `objx.fields` 为数组 | 表头动态字段 |
+| 3 | `objx.columns` 为数组 | 数据表格动态列 |
+
+配置了 **转换脚本** `dynamicSchemaConvert` 时，入参为完整 `res`，需返回数组或 `{ fields: [...] }` / `{ columns: [...] }`。
+
+### 1.4 数据表格接口动态列
+
+数据表格请求时会额外携带 `formCode`、`formVersion`、`taBm`、`dataId`，内层 `data` 仍为 `{ formData, ...extra }`。
+
+后台可返回与表头字段相同的 `type` + `keyName` 定义，前端自动映射为列 `formatS`（如 `input` → `editInput`）。展示列使用 `keyName` + `formatS`。
+
+**数据表格专用文档（含各列类型完整示例）：** [`数据表格动态列 JSON 说明.md`](./数据表格动态列%20JSON%20说明.md)
+
+### 1.5 脚本重新加载（表头动态字段）
+
+首次加载在 `table` 容器 `mounted` 时自动执行（可通过 `dynamicSchemaLoadScript` 控制是否加载）。主表数据或业务条件变化后，需在脚本里**手动**调用以重新加载字段。
+
+**任意字段 / 按钮脚本（写法相同）：**
+
+```javascript
+this.getWidgetRef("headerTable").loadDynamicSchema();
+```
+
+> 字段与容器共用表单级 `refList`，**无需** `getParentTarget().getWidgetRef(...)`。  
+> `getParentTarget()` 仅用于操作列等场景直接调用**父级 data-table** 的方法（如 `deleteRow`），见本文数据表格文档操作列示例。
+
+**等待加载完成：**
+
+```javascript
+this.getWidgetRef("headerTable").loadDynamicSchema().then(() => {
+  // 动态行已重新生成，formModel 已补全新字段默认值
+});
+```
+
+| 项目 | 说明 |
+|------|------|
+| 方法 | `loadDynamicSchema()` |
+| 挂载组件 | `table-item`（`dynamicFieldMixin.js`） |
+| `api` 模式 | 重新请求 `dynamicSchemaScriptCode`，解析 `objx` 后按生成模式插入行 |
+| `script` 模式 | 重新执行 `dynamicSchemaScript` 并刷新字段 |
+| 行为 | 删除上次动态生成的行 → 按 `dynamicSchemaMode` 插入 |
+| 默认 loading | 不显示全屏 loading |
+| 前提 | `dynamicSchemaSourceType` 为 `api` 或 `script`，且对应脚本已配置 |
+
+典型场景：主表 `billType` 变更、保存/加载单据后、点击「刷新表头」按钮。
+
+数据表格动态列重新加载见 [`数据表格动态列 JSON 说明.md`](./数据表格动态列%20JSON%20说明.md) **§1.4**。
+
+---
+
+## 2. 通用字段定义 Schema
+
+### 2.0 最小字段集（维护约定）
+
+**新脚本只维护以下顶层字段；`required` 等字段级属性写顶层，`options` 只放控件扩展配置：**
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `keyName` | **是** | 字段绑定名 |
+| `type` | 否 | 控件类型，默认 `input` |
+| `label` | 推荐 | 显示标签 |
+| `optionItems` | 否 | 静态选项（select / radio / checkbox） |
+| `required` / `readonly` / `disabled` / `hidden` | 否 | 字段级属性，**写顶层** |
+| `defaultValue` / `placeholder` | 否 | 默认值 / 占位符，**写顶层** |
+| `options` | 否 | 控件扩展配置（`formScriptCode`、`min`、`searchDialogConfig`、`onClick` 等） |
+
+**表头额外：** `colspan`（默认 `1`，单列时可不写）
+
+**数据表格额外：** `width`、`formatS`（展示列）→ 见 [`数据表格动态列 JSON 说明.md`](./数据表格动态列%20JSON%20说明.md) §2
+
+**操作列（仅数据表格）：** 无 `keyName`，`label` 写顶层；`onClick` 写 `options`；dropdown 的 `dropdownItems` 写顶层。
+
+**默认值（与控件设计器一致，一般无需写入 JSON / Java）：**
+
+| 场景 | 无需维护 |
+|------|----------|
+| 表头布局 | `colspan: 1` |
+| 静态选项 | `formScriptEnabled`、`commonAttributeEnabled`（默认均为 false） |
+| 脚本选项 | `labelKey` / `valueKey`（默认 `label` / `value`；返回自定义字段名时除外） |
+| 系统词汇 | `labelKey` / `valueKey`（前端固定 `value` / `sn`） |
+| radio / checkbox | `displayStyle: inline`、`buttonStyle`、`border` |
+| select | `clearable: true`、`multiple: false`；`filterable` 默认 false，需搜索时再设 |
+| input | `options.type: text`、`clearable: true`、`maxLength: null` |
+| date | `format` / `valueFormat` 默认 `yyyy-MM-dd` |
+| textarea | `rows: 3`、`maxLength: null`、`showWordLimit: false` |
+| 空值占位 | 无业务要求时不写 `defaultValue: ""`、`placeholder` 等 |
+
+**推荐模板：**
+
+```json
+{
+  "type": "input",
+  "keyName": "contractNo",
+  "label": "合同编号",
+  "required": true
+}
+```
+
+### 2.1 顶层公共属性
+
+| 属性 | 说明 |
+|------|------|
+| `keyName` | 字段绑定名，**必填** |
+| `type` | 控件类型 |
+| `label` | 显示标签 |
+| `colspan` | 表头占列数，默认 `1` |
+| `optionItems` | 静态选项 |
+| `required` / `readonly` / `disabled` / `hidden` | 字段级属性（**顶层**） |
+| `defaultValue` / `placeholder` | 默认值 / 占位符（**顶层**） |
+| `options` | 控件扩展配置（**不含** `required` 等字段级属性） |
+
+> 未提供 `keyName` 的字段定义会被忽略（操作列除外，见数据表格文档）。
+
+### 2.2 选项类控件三种数据来源
+
+适用于：`select`、`radio`、`checkbox`、`status`
+
+| 模式 | options 关键配置 | 说明 |
+|------|------------------|------|
+| 静态选项 | `optionItems` 或 `statusParam` | 后台字段脚本一次性下发 |
+| 后台脚本 | `formScriptEnabled: true` + `formScriptCode` | 控件初始化时再次请求脚本 |
+| 系统词汇 | `commonAttributeEnabled: true` + `commonAttributeCode` | 请求 `/user/common_attribute/listItems` |
+
+**互斥规则：** `formScriptEnabled` 与 `commonAttributeEnabled` 不能同时为 `true`。
+
+**系统词汇：** 只需 `commonAttributeEnabled` + `commonAttributeCode`，**无需**配置 `labelKey` / `valueKey`（前端固定：显示字段 `value`，关联字段 `sn`）。
+
+**脚本选项：** 返回字段默认为 `label` / `value`，一般无需配置 `labelKey` / `valueKey`（脚本返回自定义字段名时除外）。
+
+**选项脚本返回格式：**
+
+```json
+{
+  "type": "success",
+  "objx": {
+    "records": [
+      { "label": "选项A", "value": "A" }
+    ]
+  }
+}
+```
+
+或直接数组：
+
+```json
+{
+  "type": "success",
+  "objx": [
+    { "label": "选项A", "value": "A" }
+  ]
+}
+```
+
+**词汇接口返回格式：**
+
+```json
+[
+  { "sn": "1", "value": "草稿", "code": "ORDER_STATUS", "enabled": true, "sortNo": 1 },
+  { "sn": "2", "value": "已提交", "code": "ORDER_STATUS", "enabled": true, "sortNo": 2 }
+]
+```
+
+---
+
+## 3. 各控件类型 JSON 说明
+
+### 3.1 单行输入（type: `input`）
+
+```json
+{
+  "type": "input",
+  "keyName": "contractNo",
+  "label": "合同编号",
+  "required": true
+}
+```
+
+> `maxLength` 默认 `null`（不限制）；需限长或字数统计时再设 `maxLength` / `showWordLimit`。
+
+| options 字段 | 类型 | 默认值 | 说明 |
+|-------------|------|--------|------|
+| `type` | string | `text` | 输入类型：`text` / `password` 等 |
+| `clearable` | boolean | true | 可清空 |
+| `showPassword` | boolean | false | 密码框 |
+| `minLength` | number | null | 最小长度 |
+| `maxLength` | number | null | 最大长度 |
+| `showWordLimit` | boolean | false | 显示字数统计 |
+| `prefixIcon` | string | - | 前缀图标 |
+| `suffixIcon` | string | - | 后缀图标 |
+| `validation` | string | - | 校验规则表达式 |
+| `validationHint` | string | - | 校验失败提示 |
+
+---
+
+### 3.2 多行输入（type: `textarea`）
+
+```json
+{
+  "type": "textarea",
+  "keyName": "remark",
+  "label": "备注",
+  "colspan": 2
+}
+```
+
+> `rows` 默认 `3`；`maxLength` 默认不限制。
+
+| options 字段 | 类型 | 默认值 | 说明 |
+|-------------|------|--------|------|
+| `rows` | number | 3 | 可见行数 |
+| `minLength` | number | null | 最小长度 |
+| `maxLength` | number | null | 最大长度 |
+| `showWordLimit` | boolean | false | 显示字数统计 |
+
+---
+
+### 3.3 计数器（type: `number`）
+
+```json
+{
+  "type": "number",
+  "keyName": "totalQty",
+  "label": "数量",
+  "required": true,
+  "defaultValue": 0,
+  "options": {
+    "min": 0,
+    "max": 999999,
+    "precision": 0
+  }
+}
+```
+
+| options 字段 | 类型 | 默认值 | 说明 |
+|-------------|------|--------|------|
+| `min` | number | - | 最小值 |
+| `max` | number | - | 最大值 |
+| `precision` | number | 0 | 小数精度 |
+| `step` | number | 1 | 步长 |
+| `controlsPosition` | string | `right` | 按钮位置 |
+| `formulaEnabled` | boolean | false | 启用公式 |
+| `formula` | string | - | 公式表达式 |
+
+---
+
+### 3.4 单选项（type: `radio`）
+
+#### 静态选项
+
+```json
+{
+  "type": "radio",
+  "keyName": "urgentFlag",
+  "label": "是否加急",
+  "defaultValue": "0",
+  "optionItems": [
+    { "label": "否", "value": "0" },
+    { "label": "是", "value": "1" }
+  ]
+}
+```
+
+#### 后台脚本加载选项
+
+```json
+{
+  "type": "radio",
+  "keyName": "payType",
+  "label": "付款方式",
+  "options": {
+    "formScriptEnabled": true,
+    "formScriptCode": "payTypeList",
+    "formScriptParam": "return { parentCode: this.formModel.billType }"
+  }
+}
+```
+
+#### 系统词汇
+
+```json
+{
+  "type": "radio",
+  "keyName": "yesNo",
+  "label": "是否",
+  "defaultValue": "1",
+  "options": {
+    "commonAttributeEnabled": true,
+    "commonAttributeCode": "YES_NO"
+  }
+}
+```
+
+| options 字段 | 说明 |
+|-------------|------|
+| `displayStyle` | `inline` 行内 / `block` 块级 |
+| `buttonStyle` | 按钮风格 |
+| `border` | 是否带边框 |
+
+---
+
+### 3.5 多选项（type: `checkbox`）
+
+#### 静态选项
+
+```json
+{
+  "type": "checkbox",
+  "keyName": "notifyTypes",
+  "label": "通知方式",
+  "defaultValue": ["SMS", "EMAIL"],
+  "colspan": 2,
+  "optionItems": [
+    { "label": "短信", "value": "SMS" },
+    { "label": "邮件", "value": "EMAIL" },
+    { "label": "站内信", "value": "MSG" }
+  ]
+}
+```
+
+#### 后台脚本 / 系统词汇
+
+配置方式与 `radio`、`select` 相同：脚本模式写 `formScriptEnabled` + `formScriptCode`；词汇模式写 `commonAttributeEnabled` + `commonAttributeCode`。
+
+---
+
+### 3.6 下拉选项（type: `select`）
+
+#### 静态选项
+
+```json
+{
+  "type": "select",
+  "keyName": "payType",
+  "label": "付款方式",
+  "defaultValue": "CASH",
+  "optionItems": [
+    { "label": "现金", "value": "CASH" },
+    { "label": "转账", "value": "TRANSFER" }
+  ],
+  "required": true,
+  "options": {
+    "filterable": true
+  }
+}
+```
+
+#### 后台脚本加载选项
+
+```json
+{
+  "type": "select",
+  "keyName": "subPayType",
+  "label": "子付款方式",
+  "options": {
+    "formScriptEnabled": true,
+    "formScriptCode": "subPayTypeList",
+    "formScriptParam": "return { parentPayType: this.formModel.payType }",
+    "filterable": true
+  }
+}
+```
+
+**选项脚本请求参数（前端自动发起）：**
+
+```json
+{
+  "formCode": "PO_ORDER_FORM",
+  "formVersion": "1.0",
+  "taBm": "subPayType",
+  "data": {
+    "parentPayType": "CASH"
+  }
+}
+```
+
+#### 系统词汇
+
+```json
+{
+  "type": "select",
+  "keyName": "orderStatus",
+  "label": "订单状态",
+  "defaultValue": "1",
+  "options": {
+    "commonAttributeEnabled": true,
+    "commonAttributeCode": "ORDER_STATUS",
+    "filterable": true
+  }
+}
+```
+
+#### 自定义字段名的脚本返回
+
+```json
+{
+  "type": "select",
+  "keyName": "deptCode",
+  "label": "部门",
+  "options": {
+    "formScriptEnabled": true,
+    "formScriptCode": "deptList",
+    "labelKey": "deptName",
+    "valueKey": "deptCode"
+  }
+}
+```
+
+对应脚本返回：
+
+```json
+{
+  "type": "success",
+  "objx": {
+    "records": [
+      { "deptName": "采购部", "deptCode": "D001" },
+      { "deptName": "财务部", "deptCode": "D002" }
+    ]
+  }
+}
+```
+
+| options 字段 | 说明 |
+|-------------|------|
+| `clearable` | 可清空 |
+| `filterable` | 可搜索 |
+| `multiple` | 是否多选 |
+| `multipleLimit` | 多选上限，0=不限 |
+| `allowCreate` | 允许创建新条目 |
+| `remote` | 远程搜索 |
+| `showCollapseTags` | 多选时折叠标签 |
+
+---
+
+### 3.7 日期（type: `date`）
+
+```json
+{
+  "type": "date",
+  "keyName": "orderDate",
+  "label": "订单日期",
+  "required": true
+}
+```
+
+> `format` / `valueFormat` 默认均为 `yyyy-MM-dd`，非特殊格式无需配置。
+
+| options.type | 说明 |
+|-------------|------|
+| `date` | 日期 |
+| `datetime` | 日期时间 |
+| `month` | 月份 |
+| `year` | 年份 |
+
+| options 字段 | 说明 |
+|-------------|------|
+| `format` | 显示格式 |
+| `valueFormat` | 绑定值格式 |
+| `minDate` / `maxDate` | 可选范围 |
+| `utcTransformEnabled` | UTC 转换 |
+
+---
+
+### 3.8 文本（type: `text`）
+
+只读展示字段，绑定 formModel 中的值并展示（非输入框）。
+
+```json
+{
+  "type": "text",
+  "keyName": "createByName",
+  "label": "创建人"
+}
+```
+
+| options 字段 | 说明 |
+|-------------|------|
+| `colorClass` | 文字颜色样式类 |
+| `formatType` | 格式化类型 |
+| `renderHandle` | 自定义渲染脚本 |
+| `autoValueEnabled` | 启用自动取值 |
+| `autoValueHanlde` | 自动取值脚本 |
+
+---
+
+### 3.9 凭证（type: `vabUpload` / `baseAttachment`）
+
+附件上传控件，绑定值为**文件数组**。`baseAttachment` 与 `vabUpload` 的 `keyName` 规则相同。
+
+**`keyName` 格式（必填遵守）：**
+
+```
+attachments_<唯一后缀>
+```
+
+| 部分 | 说明 |
+|------|------|
+| 固定前缀 | `attachments_`（与设计器 `keyNamePrefixMap` 一致，**不可省略**） |
+| 唯一后缀 | 同表单内唯一，设计器拖入时默认生成 UUID；后台脚本自行指定时也须保证不重复 |
+| 完整示例 | `attachments_a1b2c3d4e5f6789012345678abcdef` |
+
+> 同一张表单若有多个附件字段，每个字段使用不同的后缀；`formModel`、保存接口、`getList` 的 `taBm` 均使用**完整** `keyName`（含前缀）。  
+> 勿使用 `attachments` 等无前缀或无前缀+后缀的写法。
+
+```json
+{
+  "type": "vabUpload",
+  "keyName": "attachments_a1b2c3d4e5f6789012345678abcdef",
+  "label": "附件",
+  "colspan": 2,
+  "options": {
+    "limit": 10
+  }
+}
+```
+
+> `formScriptCode` 加载历史附件默认 `getList`，一般无需配置。  
+> **无需**维护 `entityTableCode` / `entityTableDesc`（设计器「实体表」配置已废弃；凭证按 `formCode` + 字段 `keyName`（`taBm`）+ 单据 `dataId` 加载）。
+
+| options 字段 | 类型 | 说明 |
+|-------------|------|------|
+| `limit` | number | 最大文件数，`1` 为单文件 |
+| `hideRemoveButton` | boolean | 隐藏删除按钮 |
+| `hiddenFileInfo` | boolean | 隐藏文件信息区 |
+| `hiddenFileName` | boolean | 隐藏文件名 |
+| `showFileSize` | boolean | 显示文件大小 |
+| `showFileCreateBy` | boolean | 显示上传人 |
+| `showFileCreateDate` | boolean | 显示上传时间 |
+| `widgetSize` | number | 展示尺寸 |
+| `formScriptCode` | string | 加载已有附件的脚本，默认 `getList` |
+
+**凭证加载脚本请求参数：**
+
+```json
+{
+  "formCode": "PO_ORDER_FORM",
+  "formVersion": "1.0",
+  "taBm": "attachments_a1b2c3d4e5f6789012345678abcdef",
+  "data": {
+    "id": "10001"
+  }
+}
+```
+
+**凭证加载脚本返回（objx 为文件数组）：**
+
+```json
+{
+  "type": "success",
+  "objx": [
+    {
+      "id": "file001",
+      "fileName": "合同.pdf",
+      "fileUrl": "https://xxx/contract.pdf",
+      "fileSize": 102400,
+      "createBy": "张三",
+      "createDate": "2026-06-15 10:00:00"
+    }
+  ]
+}
+```
+
+> 仅在表单已有 `dataId`（编辑态）时，`onCreated` 默认脚本才会加载历史附件。
+
+---
+
+### 3.10 搜索框（type: `vabsearch`）
+
+弹窗选择控件。存值字段为 `keyName`，显示名称通常存于 `vabSearchName` 对应字段。
+
+```json
+{
+  "type": "vabsearch",
+  "keyName": "supplierCode",
+  "label": "供应商",
+  "required": true,
+  "options": {
+    "vabSearchName": "supplierName",
+    "searchDialogConfig": {
+      "formCode": "SUPPLIER_LIST",
+      "valueSourceField": "supplierCode",
+      "labelSourceField": "supplierName"
+    }
+  }
+}
+```
+
+扩展配置（按需）示例：
+
+```json
+{
+  "options": {
+    "searchDialogConfig": {
+      "formCode": "SUPPLIER_LIST",
+      "formName": "供应商列表",
+      "valueSourceField": "supplierCode",
+      "labelSourceField": "supplierName",
+      "tableEnabled": true,
+      "dialogQueryParam": "return { status: '1' }",
+      "dialogCustomParam": "return { title: '选择供应商' }"
+    }
+  }
+}
+```
+
+| options 字段 | 说明 |
+|-------------|------|
+| `vabSearchName` | 显示名称存入 formModel 的字段名（如 `supplierName`） |
+| `readonly` | 输入框只读（通常 true） |
+| `multipleChoices` | 是否多选 |
+| `dialogModel` | 弹框模式 |
+| `valueField` | 多选时的值字段（可选） |
+
+**searchDialogConfig 字段：**
+
+| 字段 | 说明 |
+|------|------|
+| `formCode` | 弹窗列表表单编码（必填） |
+| `valueSourceField` | 选中行的值字段（写入 keyName） |
+| `labelSourceField` | 选中行的显示字段（写入 vabSearchName） |
+| `multipleChoices` | 是否多选 |
+| `tableEnabled` | 启用表格模式 |
+| `dialogQueryParam` | 弹窗查询参数脚本 |
+| `dialogCustomParam` | 弹窗额外参数脚本 |
+| `confirmCallback` | 确认回调脚本 |
+
+**选中后 formModel 示例：**
+
+```json
+{
+  "supplierCode": "SUP001",
+  "supplierName": "某某供应商有限公司"
+}
+```
+
+**多选搜索框示例（type 也可用 `multiSearch`）：**
+
+```json
+{
+  "type": "vabsearch",
+  "keyName": "supplierList",
+  "label": "供应商(多选)",
+  "options": {
+    "vabSearchName": "supplierName",
+    "multipleChoices": true,
+    "valueField": "supplierCode",
+    "searchDialogConfig": {
+      "formCode": "SUPPLIER_LIST",
+      "valueSourceField": "supplierCode",
+      "labelSourceField": "supplierName",
+      "multipleChoices": true
+    }
+  }
+}
+```
+
+---
+
+### 3.11 状态（type: `status`）
+
+根据字段值展示带颜色标签的状态文本（非输入控件）。
+
+#### 静态状态配置
+
+```json
+{
+  "type": "status",
+  "keyName": "orderStatus",
+  "label": "订单状态",
+  "defaultValue": "1",
+  "options": {
+    "statusParam": [
+      { "label": "草稿", "value": "1", "type": "info" },
+      { "label": "已提交", "value": "2", "type": "warning" },
+      { "label": "已审核", "value": "3", "type": "success" },
+      { "label": "已驳回", "value": "4", "type": "danger" }
+    ]
+  }
+}
+```
+
+**statusParam 字段说明：**
+
+| 字段 | 说明 |
+|------|------|
+| `label` | 显示名称 |
+| `value` | 状态值（与 formModel 中 keyName 对应） |
+| `type` | 颜色：`""`(蓝) / `success`(绿) / `warning`(橙) / `info`(灰) / `danger`(红) |
+
+**optionItemValueType 值类型：**
+
+| 值 | 说明 |
+|----|------|
+| `0` | 文本 |
+| `1` | 数值 |
+| `2` | 布尔（自动生成 是/否 两项） |
+
+数值型示例：
+
+```json
+{
+  "type": "status",
+  "keyName": "auditStatus",
+  "label": "审核状态",
+  "defaultValue": 0,
+  "options": {
+    "optionItemValueType": 1,
+    "statusParam": [
+      { "label": "待审核", "value": 0, "type": "warning" },
+      { "label": "已通过", "value": 1, "type": "success" },
+      { "label": "已拒绝", "value": 2, "type": "danger" }
+    ]
+  }
+}
+```
+
+#### 后台脚本加载状态项
+
+```json
+{
+  "type": "status",
+  "keyName": "wfStatus",
+  "label": "流程状态",
+  "options": {
+    "formScriptEnabled": true,
+    "formScriptCode": "wfStatusList",
+    "formScriptParam": "return { processId: this.formModel.processId }"
+  }
+}
+```
+
+脚本返回的选项会写入 `statusParam`（与 select 选项加载机制相同）。
+
+#### 系统词汇加载状态
+
+```json
+{
+  "type": "status",
+  "keyName": "billStatus",
+  "label": "单据状态",
+  "options": {
+    "commonAttributeEnabled": true,
+    "commonAttributeCode": "BILL_STATUS"
+  }
+}
+```
+
+> 词汇模式下状态标签不显示颜色样式（仅纯文本），静态 `statusParam` 才支持 `type` 颜色。
+
+---
+
+## 4. 完整综合示例
+
+```json
+{
+  "type": "success",
+  "message": "ok",
+  "objx": [
+    {
+      "type": "input",
+      "keyName": "contractNo",
+      "label": "合同编号",
+      "required": true
+    },
+    {
+      "type": "textarea",
+      "keyName": "remark",
+      "label": "备注",
+      "colspan": 2
+    },
+    {
+      "type": "number",
+      "keyName": "totalQty",
+      "label": "数量",
+      "defaultValue": 1,
+      "options": { "min": 0, "precision": 0 }
+    },
+    {
+      "type": "radio",
+      "keyName": "urgentFlag",
+      "label": "是否加急",
+      "defaultValue": "0",
+      "optionItems": [
+        { "label": "否", "value": "0" },
+        { "label": "是", "value": "1" }
+      ]
+    },
+    {
+      "type": "checkbox",
+      "keyName": "notifyTypes",
+      "label": "通知方式",
+      "defaultValue": [],
+      "colspan": 2,
+      "optionItems": [
+        { "label": "短信", "value": "SMS" },
+        { "label": "邮件", "value": "EMAIL" }
+      ]
+    },
+    {
+      "type": "select",
+      "keyName": "payType",
+      "label": "付款方式",
+      "options": {
+        "formScriptEnabled": true,
+        "formScriptCode": "payTypeList"
+      }
+    },
+    {
+      "type": "date",
+      "keyName": "orderDate",
+      "label": "订单日期"
+    },
+    {
+      "type": "text",
+      "keyName": "createByName",
+      "label": "创建人"
+    },
+    {
+      "type": "vabUpload",
+      "keyName": "attachments_a1b2c3d4e5f6789012345678abcdef",
+      "label": "附件",
+      "colspan": 2,
+      "options": {
+        "limit": 10
+      }
+    },
+    {
+      "type": "vabsearch",
+      "keyName": "supplierCode",
+      "label": "供应商",
+      "required": true,
+      "options": {
+        "vabSearchName": "supplierName",
+        "searchDialogConfig": {
+          "formCode": "SUPPLIER_LIST",
+          "valueSourceField": "supplierCode",
+          "labelSourceField": "supplierName"
+        }
+      }
+    },
+    {
+      "type": "status",
+      "keyName": "orderStatus",
+      "label": "订单状态",
+      "defaultValue": "1",
+      "options": {
+        "statusParam": [
+          { "label": "草稿", "value": "1", "type": "info" },
+          { "label": "已提交", "value": "2", "type": "warning" },
+          { "label": "已审核", "value": "3", "type": "success" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 5. 完整综合 Java 示例代码
+
+脚本编码建议：`getDynamicSchemaFields`（配置在 table 容器「接口动态字段 → 脚本编码」）  
+返回类型：`List<Map<String, Object>>`，平台自动包装为响应 `objx` 数组。
+
+**前端字段脚本**（`dynamicSchemaSourceType: script`）不调接口，在设计器「前端字段脚本」中直接 `return` 与下方 JSON 相同结构的数组或 `{ fields: [...] }`。
+
+### 5.1 脚本约定
+
+| 项目 | 说明 |
+|------|------|
+| 返回类型 | `List<Map<String, Object>>`，每个 Map 为一条字段定义 |
+| 嵌套配置 | 控件扩展属性放在 `options`（`Map`）中 |
+| 默认值 | 与控件设计器默认相同的属性**无需写入**，见 **§2.0** |
+| 静态选项 | `select` / `radio` / `checkbox` 可直接 `put("optionItems", list)` |
+| 请求入参 | Java 脚本通过 `this.getBinding().getVariables()` 获取；表头脚本直接读 `formData`，见下方示例 |
+| 二次请求 | 下拉/状态等 `formScriptCode`、凭证 `getList` 需**单独维护**选项脚本 |
+
+读取表单数据示例（表头接口动态字段脚本）：
+
+```java
+Map<String, Object> variables = this.getBinding().getVariables();
+Map<String, Object> formModel = (Map<String, Object>) variables.get("formData");
+String billType = formModel.get("billType").toString();
+```
+
+数据表格动态列脚本读内层 `data`，见 [`数据表格动态列 JSON 说明.md`](./数据表格动态列%20JSON%20说明.md) §0.2 / §1.1。
+
+### 5.2 主脚本：返回全部字段定义
+
+```java
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+List<Map<String, Object>> fields = new ArrayList<>();
+
+// ========== 1. 单行输入 input ==========
+Map<String, Object> f1 = new HashMap<>();
+f1.put("type", "input");
+f1.put("keyName", "contractNo");
+f1.put("label", "合同编号");
+f1.put("required", true);
+fields.add(f1);
+
+// ========== 2. 多行输入 textarea ==========
+Map<String, Object> f2 = new HashMap<>();
+f2.put("type", "textarea");
+f2.put("keyName", "remark");
+f2.put("label", "备注");
+f2.put("colspan", 2);
+fields.add(f2);
+
+// ========== 3. 计数器 number ==========
+Map<String, Object> f3 = new HashMap<>();
+f3.put("type", "number");
+f3.put("keyName", "totalQty");
+f3.put("label", "数量");
+f3.put("defaultValue", 1);
+Map<String, Object> f3Opt = new HashMap<>();
+f3Opt.put("min", 0);
+f3Opt.put("precision", 0);
+f3.put("options", f3Opt);
+fields.add(f3);
+
+// ========== 4. 单选项 radio（静态 optionItems） ==========
+Map<String, Object> f4 = new HashMap<>();
+f4.put("type", "radio");
+f4.put("keyName", "urgentFlag");
+f4.put("label", "是否加急");
+f4.put("defaultValue", "0");
+List<Map<String, Object>> f4Items = new ArrayList<>();
+Map<String, Object> f4Item1 = new HashMap<>();
+f4Item1.put("label", "否");
+f4Item1.put("value", "0");
+f4Items.add(f4Item1);
+Map<String, Object> f4Item2 = new HashMap<>();
+f4Item2.put("label", "是");
+f4Item2.put("value", "1");
+f4Items.add(f4Item2);
+f4.put("optionItems", f4Items);
+fields.add(f4);
+
+// ========== 5. 多选项 checkbox（静态 optionItems） ==========
+Map<String, Object> f5 = new HashMap<>();
+f5.put("type", "checkbox");
+f5.put("keyName", "notifyTypes");
+f5.put("label", "通知方式");
+f5.put("defaultValue", new ArrayList<>());
+f5.put("colspan", 2);
+List<Map<String, Object>> f5Items = new ArrayList<>();
+Map<String, Object> f5Item1 = new HashMap<>();
+f5Item1.put("label", "短信");
+f5Item1.put("value", "SMS");
+f5Items.add(f5Item1);
+Map<String, Object> f5Item2 = new HashMap<>();
+f5Item2.put("label", "邮件");
+f5Item2.put("value", "EMAIL");
+f5Items.add(f5Item2);
+f5.put("optionItems", f5Items);
+fields.add(f5);
+
+// ========== 6. 下拉选项 select（表单脚本加载选项） ==========
+Map<String, Object> f6 = new HashMap<>();
+f6.put("type", "select");
+f6.put("keyName", "payType");
+f6.put("label", "付款方式");
+f6.put("required", true);
+Map<String, Object> f6Opt = new HashMap<>();
+f6Opt.put("formScriptEnabled", true);
+f6Opt.put("formScriptCode", "payTypeList");
+// formScriptParam 为前端 JS 脚本字符串，非 Java
+f6Opt.put("formScriptParam", "return { billType: this.formModel.billType }");
+f6.put("options", f6Opt);
+fields.add(f6);
+
+// ========== 6b. 下拉选项 select（系统词汇） ==========
+Map<String, Object> f6b = new HashMap<>();
+f6b.put("type", "select");
+f6b.put("keyName", "orderStatus");
+f6b.put("label", "订单状态");
+f6b.put("defaultValue", "1");
+Map<String, Object> f6bOpt = new HashMap<>();
+f6bOpt.put("commonAttributeEnabled", true);
+f6bOpt.put("commonAttributeCode", "ORDER_STATUS");
+f6b.put("options", f6bOpt);
+fields.add(f6b);
+
+// ========== 7. 日期 date ==========
+Map<String, Object> f7 = new HashMap<>();
+f7.put("type", "date");
+f7.put("keyName", "orderDate");
+f7.put("label", "订单日期");
+fields.add(f7);
+
+// ========== 8. 文本 text（只读展示） ==========
+Map<String, Object> f8 = new HashMap<>();
+f8.put("type", "text");
+f8.put("keyName", "createByName");
+f8.put("label", "创建人");
+fields.add(f8);
+
+// ========== 9. 凭证 vabUpload ==========
+Map<String, Object> f9 = new HashMap<>();
+f9.put("type", "vabUpload");
+f9.put("keyName", "attachments_a1b2c3d4e5f6789012345678abcdef");
+f9.put("label", "附件");
+f9.put("colspan", 2);
+Map<String, Object> f9Opt = new HashMap<>();
+f9Opt.put("limit", 10);
+f9.put("options", f9Opt);
+fields.add(f9);
+
+// ========== 10. 搜索框 vabsearch ==========
+Map<String, Object> f10 = new HashMap<>();
+f10.put("type", "vabsearch");
+f10.put("keyName", "supplierCode");
+f10.put("label", "供应商");
+f10.put("required", true);
+Map<String, Object> f10Opt = new HashMap<>();
+f10Opt.put("vabSearchName", "supplierName");
+Map<String, Object> f10Dialog = new HashMap<>();
+f10Dialog.put("formCode", "SUPPLIER_LIST");
+f10Dialog.put("valueSourceField", "supplierCode");
+f10Dialog.put("labelSourceField", "supplierName");
+f10Opt.put("searchDialogConfig", f10Dialog);
+f10.put("options", f10Opt);
+fields.add(f10);
+
+// ========== 11. 状态 status（静态 statusParam + 颜色） ==========
+Map<String, Object> f11 = new HashMap<>();
+f11.put("type", "status");
+f11.put("keyName", "wfStatus");
+f11.put("label", "流程状态");
+f11.put("defaultValue", "1");
+Map<String, Object> f11Opt = new HashMap<>();
+List<Map<String, Object>> f11Status = new ArrayList<>();
+Map<String, Object> s1 = new HashMap<>();
+s1.put("label", "草稿");
+s1.put("value", "1");
+s1.put("type", "info");
+f11Status.add(s1);
+Map<String, Object> s2 = new HashMap<>();
+s2.put("label", "已提交");
+s2.put("value", "2");
+s2.put("type", "warning");
+f11Status.add(s2);
+Map<String, Object> s3 = new HashMap<>();
+s3.put("label", "已审核");
+s3.put("value", "3");
+s3.put("type", "success");
+f11Status.add(s3);
+f11Opt.put("statusParam", f11Status);
+f11.put("options", f11Opt);
+fields.add(f11);
+
+return fields;
+```
+
+### 5.3 附属脚本：下拉选项 payTypeList
+
+字段定义里 `formScriptCode: "payTypeList"` 时，控件初始化会**二次请求**该脚本。
+
+```java
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+// 请求 taBm = payType，data 含 formScriptParam 脚本返回的参数
+List<Map<String, Object>> list = new ArrayList<>();
+
+Map<String, Object> item1 = new HashMap<>();
+item1.put("label", "现金");
+item1.put("value", "CASH");
+list.add(item1);
+
+Map<String, Object> item2 = new HashMap<>();
+item2.put("label", "银行转账");
+item2.put("value", "TRANSFER");
+list.add(item2);
+
+Map<String, Object> item3 = new HashMap<>();
+item3.put("label", "承兑汇票");
+item3.put("value", "ACCEPT");
+list.add(item3);
+
+return list;
+```
+
+### 5.4 附属脚本：凭证 getList
+
+字段 `attachments_<唯一后缀>` 在编辑态（有 dataId）时，通过 `formScriptCode: "getList"` 加载历史附件；`taBm` 与 `keyName` 一致。
+
+```java
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+// 请求 data.id = 单据主键
+List<Map<String, Object>> files = new ArrayList<>();
+
+Map<String, Object> file1 = new HashMap<>();
+file1.put("id", "file001");
+file1.put("fileName", "合同.pdf");
+file1.put("fileUrl", "https://xxx/contract.pdf");
+file1.put("fileSize", 102400);
+file1.put("createBy", "张三");
+file1.put("createDate", "2026-06-15 10:00:00");
+files.add(file1);
+
+return files;
+```
+
+### 5.5 按业务条件动态裁剪字段
+
+```java
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+List<Map<String, Object>> fields = new ArrayList<>();
+
+Map<String, Object> variables = this.getBinding().getVariables();
+Map<String, Object> formModel = (Map<String, Object>) variables.get("formData");
+String billType = formModel.get("billType").toString();
+
+// 所有单据都有合同编号
+Map<String, Object> contractNo = new HashMap<>();
+contractNo.put("type", "input");
+contractNo.put("keyName", "contractNo");
+contractNo.put("label", "合同编号");
+contractNo.put("required", true);
+contractNo.put("colspan", 1);
+fields.add(contractNo);
+
+// 仅采购单显示供应商搜索框
+if ("PO".equals(billType)) {
+  Map<String, Object> supplier = new HashMap<>();
+  supplier.put("type", "vabsearch");
+  supplier.put("keyName", "supplierCode");
+  supplier.put("label", "供应商");
+  supplier.put("colspan", 1);
+  Map<String, Object> opt = new HashMap<>();
+  opt.put("vabSearchName", "supplierName");
+  Map<String, Object> dialog = new HashMap<>();
+  dialog.put("formCode", "SUPPLIER_LIST");
+  dialog.put("valueSourceField", "supplierCode");
+  dialog.put("labelSourceField", "supplierName");
+  opt.put("searchDialogConfig", dialog);
+  supplier.put("options", opt);
+  fields.add(supplier);
+}
+
+return fields;
+```
+
+### 5.6 使用前替换占位
+
+| 占位 | 说明 |
+|------|------|
+| `getDynamicSchemaFields` | table 容器「接口动态字段 → 脚本编码」 |
+| `payTypeList` | 下拉选项二次请求脚本 |
+| `ORDER_STATUS` | 系统词汇编码 |
+| `SUPPLIER_LIST` | 搜索弹框表单编码 |
+| 各字段 `keyName` | 与 formModel / 保存接口字段一致 |
+
+联调建议：先返回 `input` + `select`(静态 optionItems) 两列验证通路，再逐步放开其余类型。
+
+---
+
+## 6. 布局说明
+
+| 容器配置 | 说明 |
+|---------|------|
+| `dynamicSchemaSourceType: none` | 不加载动态字段（默认） |
+| `dynamicSchemaSourceType: script` | 执行 `dynamicSchemaScript` 生成字段 |
+| `dynamicSchemaSourceType: api` | 请求 `dynamicSchemaScriptCode` 生成字段 |
+| `dynamicSchemaLoadScript` | 初始化前执行；`return false` 时不加载 |
+| `dynamicSchemaAnchorRowId` | anchor 模式占位行 id |
+| `dynamicSchemaAnchorPosition` | `replace` / `before` / `after`（设计器为下拉框） |
+| `dynamicSchemaInheritLayout` | anchor 模式是否继承占位行单元格布局 |
+| `dynamicSchemaColumns` | 每行列数，默认 4 |
+| `dynamicSchemaMode: append` | 追加到已有行之后 |
+| `dynamicSchemaMode: replace` | 清空已有行后替换 |
+| `dynamicSchemaMode: anchor` | 插入到占位锚点行 |
+| 字段 `colspan` | 占几列，超出自动换行 |
+
+---
+
+## 7. 注意事项
+
+1. **type 必须已注册**：未在设计器字段库中注册的 type 会被跳过。
+2. **keyName 唯一**：不要与表单已有字段重复。
+3. **只写差异属性**：与控件设计器默认值相同的属性无需维护，见 **§2.0 默认值**。
+4. **动态规则分离**：运行时显隐/必填/只读等规则在「表单设置 → 动态字段规则」配置，不在本 JSON 中动态下发（初始 `hidden/required` 等仍可在定义里设置）。
+5. **formScriptParam / dialogQueryParam 等**：均为 JS 脚本字符串，不是 JSON 对象。
+6. **选项脚本与词汇互斥**：同一控件只能启用一种选项来源。
+7. **凭证仅编辑态加载**：无 `dataId` 时不请求历史附件。
+
+---
+
+## 8. 相关文件
+
+| 文件 | 说明 |
+|------|------|
+| `utils/dynamicSchemaUtil.js` | 协议常量（`DYNAMIC_SCHEMA_CORE_KEYS` 等）与规范化 |
+| `form-render/container-item/dynamicFieldMixin.js` | 表头动态字段运行时 |
+| `form-render/container-item/data-table-mixin.js` | 数据表格动态列运行时 |
+| `form-designer/.../table-dynamicField-editor.vue` | 表头设计器配置 |
+| `form-designer/.../data-table-editor.vue` | 数据表格设计器配置 |
+| [`数据表格动态列 JSON 说明.md`](./数据表格动态列%20JSON%20说明.md) | 数据表格差异说明 |