cloud-web-corejs 1.0.54-dev.687 → 1.0.54-dev.688

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,1356 @@
+# 后台字段（动态生成）JSON 说明
+
+> 适用场景：表格布局容器（`table`）启用 **后台字段（动态生成）**（`dynamicSchemaEnabled`）后，后台脚本返回字段定义，前端运行时生成并渲染表单控件。
+>
+> 相关代码：`form-render/container-item/dynamicFieldMixin.js`
+
+---
+
+## 1. 调用流程
+
+```
+表单渲染
+  → table 容器请求 dynamicSchemaScriptCode 脚本
+  → 解析响应为「字段定义数组」
+  → 按生成模式(append/replace/anchor)插入行布局
+  → 各字段控件初始化（下拉/状态等可能再次请求选项数据）
+```
+
+### 1.1 请求参数（前端 → 后台字段脚本）
+
+```json
+{
+  "formData": {
+    "id": "10001",
+    "billType": "PO"
+  },
+  "bizType": "A"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `formData` | 当前表单数据（`formModel`），固定传入 |
+| 其余字段 | 由容器属性「脚本返回对应的参数值」脚本动态返回 |
+
+### 1.2 响应外层结构
+
+```json
+{
+  "success": true,
+  "message": "ok",
+  "objx": []
+}
+```
+
+### 1.3 objx 解析规则（未配置转换脚本时）
+
+按以下优先级取字段定义数组：
+
+| 优先级 | 结构 |
+|--------|------|
+| 1 | `objx` 本身为数组 |
+| 2 | `objx.fields` 为数组 |
+| 3 | `objx.columns` 为数组 |
+
+配置了 **转换脚本** 时，入参为完整 `res`，需返回数组或 `{ fields: [...] }`。
+
+---
+
+## 2. 通用字段定义 Schema
+
+每条字段定义会被转成 xform 控件 schema：
+
+```json
+{
+  "type": "input",
+  "keyName": "contractNo",
+  "label": "合同编号",
+  "required": true,
+  "readonly": false,
+  "disabled": false,
+  "hidden": false,
+  "defaultValue": "",
+  "placeholder": "请输入",
+  "colspan": 1,
+  "optionItems": [],
+  "options": {}
+}
+```
+
+### 2.1 顶层公共属性
+
+| 属性 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `type` | 否 | string | 控件类型，默认 `input` |
+| `keyName` | **是*** | string | 字段绑定名（写入 formModel）。也可用 `field` / `name`，优先级：`keyName` > `field` > `name` |
+| `label` | 否 | string | 显示标签 |
+| `required` | 否 | boolean | 是否必填 |
+| `readonly` | 否 | boolean | 是否只读 |
+| `disabled` | 否 | boolean | 是否禁用 |
+| `hidden` | 否 | boolean | 是否隐藏 |
+| `defaultValue` | 否 | any | 默认值 |
+| `placeholder` | 否 | string | 占位符（控件支持时生效） |
+| `colspan` | 否 | number | 占列数，默认 `1` |
+| `optionItems` | 否 | array | 静态选项（select/radio/checkbox 等） |
+| `options` | 否 | object | 控件扩展配置，合并进 `widget.options` |
+
+> *`keyName` / `field` / `name` 至少提供一个，否则该条定义会被忽略。
+
+### 2.2 选项类控件三种数据来源
+
+适用于：`select`、`radio`、`checkbox`、`status`
+
+| 模式 | options 关键配置 | 说明 |
+|------|------------------|------|
+| 静态选项 | `optionItems` 或 `statusParam` | 后台字段脚本一次性下发 |
+| 后台脚本 | `formScriptEnabled: true` + `formScriptCode` | 控件初始化时再次请求脚本 |
+| 系统词汇 | `commonAttributeEnabled: true` + `commonAttributeCode` | 请求 `/user/common_attribute/listItems` |
+
+**互斥规则：** `formScriptEnabled` 与 `commonAttributeEnabled` 不能同时为 `true`。
+
+**词汇下拉/状态 labelKey/valueKey：**
+
+```json
+{
+  "labelKey": "value",
+  "valueKey": "sn"
+}
+```
+
+**脚本下拉 labelKey/valueKey（默认）：**
+
+```json
+{
+  "labelKey": "label",
+  "valueKey": "value"
+}
+```
+
+**选项脚本返回格式：**
+
+```json
+{
+  "success": true,
+  "objx": {
+    "records": [
+      { "label": "选项A", "value": "A" }
+    ]
+  }
+}
+```
+
+或直接数组：
+
+```json
+{
+  "success": true,
+  "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,
+  "placeholder": "请输入合同编号",
+  "defaultValue": "",
+  "colspan": 1,
+  "options": {
+    "type": "text",
+    "clearable": true,
+    "showPassword": false,
+    "minLength": null,
+    "maxLength": 50,
+    "showWordLimit": true,
+    "prefixIcon": "",
+    "suffixIcon": "",
+    "validation": "",
+    "validationHint": ""
+  }
+}
+```
+
+| 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": "备注",
+  "placeholder": "请输入备注",
+  "defaultValue": "",
+  "colspan": 2,
+  "options": {
+    "rows": 3,
+    "minLength": null,
+    "maxLength": 500,
+    "showWordLimit": true
+  }
+}
+```
+
+| 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,
+  "colspan": 1,
+  "options": {
+    "min": 0,
+    "max": 999999,
+    "precision": 0,
+    "step": 1,
+    "controlsPosition": "right",
+    "formulaEnabled": false,
+    "formula": ""
+  }
+}
+```
+
+| 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",
+  "colspan": 1,
+  "optionItems": [
+    { "label": "否", "value": "0", "disabled": false },
+    { "label": "是", "value": "1", "disabled": false }
+  ],
+  "options": {
+    "formScriptEnabled": false,
+    "commonAttributeEnabled": false,
+    "displayStyle": "inline",
+    "buttonStyle": false,
+    "border": false
+  }
+}
+```
+
+#### 后台脚本加载选项
+
+```json
+{
+  "type": "radio",
+  "keyName": "payType",
+  "label": "付款方式",
+  "options": {
+    "formScriptEnabled": true,
+    "commonAttributeEnabled": false,
+    "formScriptCode": "payTypeList",
+    "labelKey": "label",
+    "valueKey": "value",
+    "formScriptParam": "return { parentCode: this.formModel.billType }",
+    "displayStyle": "inline"
+  }
+}
+```
+
+#### 系统词汇
+
+```json
+{
+  "type": "radio",
+  "keyName": "yesNo",
+  "label": "是否",
+  "defaultValue": "1",
+  "options": {
+    "formScriptEnabled": false,
+    "commonAttributeEnabled": true,
+    "commonAttributeCode": "YES_NO",
+    "labelKey": "value",
+    "valueKey": "sn"
+  }
+}
+```
+
+| 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" }
+  ],
+  "options": {
+    "formScriptEnabled": false,
+    "commonAttributeEnabled": false,
+    "displayStyle": "inline"
+  }
+}
+```
+
+#### 后台脚本 / 系统词汇
+
+配置方式与 `radio`、`select` 相同，将 `formScriptEnabled` 或 `commonAttributeEnabled` 放入 `options` 即可。
+
+---
+
+### 3.6 下拉选项（type: `select`）
+
+#### 静态选项
+
+```json
+{
+  "type": "select",
+  "keyName": "payType",
+  "label": "付款方式",
+  "required": true,
+  "defaultValue": "CASH",
+  "placeholder": "请选择",
+  "colspan": 1,
+  "optionItems": [
+    { "label": "现金", "value": "CASH", "disabled": false },
+    { "label": "转账", "value": "TRANSFER", "disabled": false }
+  ],
+  "options": {
+    "formScriptEnabled": false,
+    "commonAttributeEnabled": false,
+    "clearable": true,
+    "filterable": true,
+    "multiple": false,
+    "multipleLimit": 0
+  }
+}
+```
+
+#### 后台脚本加载选项
+
+```json
+{
+  "type": "select",
+  "keyName": "subPayType",
+  "label": "子付款方式",
+  "options": {
+    "formScriptEnabled": true,
+    "commonAttributeEnabled": false,
+    "formScriptCode": "subPayTypeList",
+    "labelKey": "label",
+    "valueKey": "value",
+    "formScriptParam": "return { parentPayType: this.formModel.payType }",
+    "clearable": true,
+    "filterable": true
+  }
+}
+```
+
+**选项脚本请求参数（前端自动发起）：**
+
+```json
+{
+  "formCode": "PO_ORDER_FORM",
+  "formVersion": "1.0",
+  "taBm": "subPayType",
+  "data": {
+    "parentPayType": "CASH"
+  }
+}
+```
+
+#### 系统词汇
+
+```json
+{
+  "type": "select",
+  "keyName": "orderStatus",
+  "label": "订单状态",
+  "defaultValue": "1",
+  "options": {
+    "formScriptEnabled": false,
+    "commonAttributeEnabled": true,
+    "commonAttributeCode": "ORDER_STATUS",
+    "labelKey": "value",
+    "valueKey": "sn",
+    "clearable": true,
+    "filterable": true
+  }
+}
+```
+
+#### 自定义字段名的脚本返回
+
+```json
+{
+  "type": "select",
+  "keyName": "deptCode",
+  "label": "部门",
+  "options": {
+    "formScriptEnabled": true,
+    "formScriptCode": "deptList",
+    "labelKey": "deptName",
+    "valueKey": "deptCode"
+  }
+}
+```
+
+对应脚本返回：
+
+```json
+{
+  "success": true,
+  "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,
+  "defaultValue": null,
+  "placeholder": "请选择日期",
+  "colspan": 1,
+  "options": {
+    "type": "date",
+    "format": "yyyy-MM-dd",
+    "valueFormat": "yyyy-MM-dd",
+    "clearable": true,
+    "editable": false,
+    "readonly": false,
+    "minDate": null,
+    "maxDate": null,
+    "utcTransformEnabled": false
+  }
+}
+```
+
+| options.type | 说明 |
+|-------------|------|
+| `date` | 日期 |
+| `datetime` | 日期时间 |
+| `month` | 月份 |
+| `year` | 年份 |
+
+| options 字段 | 说明 |
+|-------------|------|
+| `format` | 显示格式 |
+| `valueFormat` | 绑定值格式 |
+| `minDate` / `maxDate` | 可选范围 |
+| `utcTransformEnabled` | UTC 转换 |
+
+---
+
+### 3.8 文本（type: `text`）
+
+只读展示字段，绑定 formModel 中的值并展示（非输入框）。
+
+```json
+{
+  "type": "text",
+  "keyName": "createByName",
+  "label": "创建人",
+  "defaultValue": "",
+  "colspan": 1,
+  "options": {
+    "colorClass": "",
+    "formatType": null,
+    "renderHandle": null,
+    "autoValueEnabled": false,
+    "autoValueHanlde": null,
+    "utcTransformEnabled": false
+  }
+}
+```
+
+| options 字段 | 说明 |
+|-------------|------|
+| `colorClass` | 文字颜色样式类 |
+| `formatType` | 格式化类型 |
+| `renderHandle` | 自定义渲染脚本 |
+| `autoValueEnabled` | 启用自动取值 |
+| `autoValueHanlde` | 自动取值脚本 |
+
+---
+
+### 3.9 凭证（type: `vabUpload`）
+
+附件上传控件，绑定值为文件数组。
+
+```json
+{
+  "type": "vabUpload",
+  "keyName": "attachments",
+  "label": "附件",
+  "required": false,
+  "colspan": 2,
+  "options": {
+    "limit": 10,
+    "hideRemoveButton": false,
+    "entityTableCode": "PO_ORDER",
+    "entityTableDesc": "采购订单",
+    "hiddenFileInfo": false,
+    "hiddenFileName": false,
+    "showFileSize": true,
+    "showFileCreateBy": false,
+    "showFileCreateDate": false,
+    "widgetSize": 2,
+    "formScriptEnabled": true,
+    "formScriptCode": "getList",
+    "formScriptParam": "return { id: dataId }"
+  }
+}
+```
+
+| options 字段 | 类型 | 说明 |
+|-------------|------|------|
+| `limit` | number | 最大文件数，`1` 为单文件 |
+| `hideRemoveButton` | boolean | 隐藏删除按钮 |
+| `entityTableCode` | string | 业务表编码（附件关联） |
+| `entityTableDesc` | string | 业务表描述 |
+| `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",
+  "data": {
+    "id": "10001"
+  }
+}
+```
+
+**凭证加载脚本返回（objx 为文件数组）：**
+
+```json
+{
+  "success": true,
+  "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,
+  "colspan": 1,
+  "options": {
+    "vabSearchName": "supplierName",
+    "readonly": true,
+    "multipleChoices": false,
+    "dialogModel": "1",
+    "searchDialogConfig": {
+      "formCode": "SUPPLIER_LIST",
+      "formName": "供应商列表",
+      "valueSourceField": "supplierCode",
+      "labelSourceField": "supplierName",
+      "multipleChoices": false,
+      "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",
+  "colspan": 1,
+  "options": {
+    "formScriptEnabled": false,
+    "commonAttributeEnabled": false,
+    "optionItemValueType": 0,
+    "labelKey": "label",
+    "valueKey": "value",
+    "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,
+    "commonAttributeEnabled": false,
+    "formScriptCode": "wfStatusList",
+    "labelKey": "label",
+    "valueKey": "value",
+    "formScriptParam": "return { processId: this.formModel.processId }"
+  }
+}
+```
+
+脚本返回的选项会写入 `statusParam`（与 select 选项加载机制相同）。
+
+#### 系统词汇加载状态
+
+```json
+{
+  "type": "status",
+  "keyName": "billStatus",
+  "label": "单据状态",
+  "options": {
+    "formScriptEnabled": false,
+    "commonAttributeEnabled": true,
+    "commonAttributeCode": "BILL_STATUS",
+    "labelKey": "value",
+    "valueKey": "sn"
+  }
+}
+```
+
+> 词汇模式下状态标签不显示颜色样式（仅纯文本），静态 `statusParam` 才支持 `type` 颜色。
+
+---
+
+## 4. 完整综合示例
+
+```json
+{
+  "success": true,
+  "message": "ok",
+  "objx": [
+    {
+      "type": "input",
+      "keyName": "contractNo",
+      "label": "合同编号",
+      "required": true,
+      "colspan": 1
+    },
+    {
+      "type": "textarea",
+      "keyName": "remark",
+      "label": "备注",
+      "colspan": 2,
+      "options": { "rows": 3, "maxLength": 500, "showWordLimit": true }
+    },
+    {
+      "type": "number",
+      "keyName": "totalQty",
+      "label": "数量",
+      "defaultValue": 1,
+      "colspan": 1,
+      "options": { "min": 0, "precision": 0 }
+    },
+    {
+      "type": "radio",
+      "keyName": "urgentFlag",
+      "label": "是否加急",
+      "defaultValue": "0",
+      "optionItems": [
+        { "label": "否", "value": "0" },
+        { "label": "是", "value": "1" }
+      ],
+      "colspan": 1
+    },
+    {
+      "type": "checkbox",
+      "keyName": "notifyTypes",
+      "label": "通知方式",
+      "defaultValue": [],
+      "optionItems": [
+        { "label": "短信", "value": "SMS" },
+        { "label": "邮件", "value": "EMAIL" }
+      ],
+      "colspan": 2
+    },
+    {
+      "type": "select",
+      "keyName": "payType",
+      "label": "付款方式",
+      "options": {
+        "formScriptEnabled": true,
+        "formScriptCode": "payTypeList",
+        "labelKey": "label",
+        "valueKey": "value"
+      },
+      "colspan": 1
+    },
+    {
+      "type": "date",
+      "keyName": "orderDate",
+      "label": "订单日期",
+      "colspan": 1,
+      "options": {
+        "format": "yyyy-MM-dd",
+        "valueFormat": "yyyy-MM-dd"
+      }
+    },
+    {
+      "type": "text",
+      "keyName": "createByName",
+      "label": "创建人",
+      "colspan": 1
+    },
+    {
+      "type": "vabUpload",
+      "keyName": "attachments",
+      "label": "附件",
+      "colspan": 2,
+      "options": {
+        "limit": 10,
+        "entityTableCode": "PO_ORDER",
+        "formScriptCode": "getList"
+      }
+    },
+    {
+      "type": "vabsearch",
+      "keyName": "supplierCode",
+      "label": "供应商",
+      "required": true,
+      "colspan": 1,
+      "options": {
+        "vabSearchName": "supplierName",
+        "searchDialogConfig": {
+          "formCode": "SUPPLIER_LIST",
+          "valueSourceField": "supplierCode",
+          "labelSourceField": "supplierName",
+          "multipleChoices": false
+        }
+      }
+    },
+    {
+      "type": "status",
+      "keyName": "orderStatus",
+      "label": "订单状态",
+      "defaultValue": "1",
+      "colspan": 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` 数组。
+
+### 5.1 脚本约定
+
+| 项目 | 说明 |
+|------|------|
+| 返回类型 | `List<Map<String, Object>>`，每个 Map 为一条字段定义 |
+| 嵌套配置 | 控件扩展属性放在 `options`（`Map`）中 |
+| 静态选项 | `select` / `radio` / `checkbox` 可直接 `put("optionItems", list)` |
+| 请求入参 | 前端请求体含 `formData`（当前表单数据）及容器「脚本返回对应的参数值」 |
+| 二次请求 | 下拉/状态等 `formScriptCode`、凭证 `getList` 需**单独维护**选项脚本 |
+
+读取表单数据示例（变量名以平台脚本引擎为准）：
+
+```java
+// Map data = ...; // 平台注入的请求体
+Map<String, Object> formData = (Map<String, Object>) data.get("formData");
+String billType = formData != null ? String.valueOf(formData.get("billType")) : null;
+```
+
+### 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);
+f1.put("placeholder", "请输入合同编号");
+f1.put("colspan", 1);
+Map<String, Object> f1Opt = new HashMap<>();
+f1Opt.put("type", "text");
+f1Opt.put("clearable", true);
+f1Opt.put("maxLength", 50);
+f1Opt.put("showWordLimit", true);
+f1.put("options", f1Opt);
+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);
+Map<String, Object> f2Opt = new HashMap<>();
+f2Opt.put("rows", 3);
+f2Opt.put("maxLength", 500);
+f2Opt.put("showWordLimit", true);
+f2.put("options", f2Opt);
+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);
+f3.put("colspan", 1);
+Map<String, Object> f3Opt = new HashMap<>();
+f3Opt.put("min", 0);
+f3Opt.put("max", 999999);
+f3Opt.put("precision", 0);
+f3Opt.put("step", 1);
+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");
+f4.put("colspan", 1);
+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);
+Map<String, Object> f4Opt = new HashMap<>();
+f4Opt.put("formScriptEnabled", false);
+f4Opt.put("commonAttributeEnabled", false);
+f4Opt.put("displayStyle", "inline");
+f4.put("options", f4Opt);
+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);
+f6.put("colspan", 1);
+Map<String, Object> f6Opt = new HashMap<>();
+f6Opt.put("formScriptEnabled", true);
+f6Opt.put("commonAttributeEnabled", false);
+f6Opt.put("formScriptCode", "payTypeList");
+f6Opt.put("labelKey", "label");
+f6Opt.put("valueKey", "value");
+// formScriptParam 为前端 JS 脚本字符串，非 Java
+f6Opt.put("formScriptParam", "return { billType: this.formModel.billType }");
+f6Opt.put("clearable", true);
+f6Opt.put("filterable", true);
+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");
+f6b.put("colspan", 1);
+Map<String, Object> f6bOpt = new HashMap<>();
+f6bOpt.put("formScriptEnabled", false);
+f6bOpt.put("commonAttributeEnabled", true);
+f6bOpt.put("commonAttributeCode", "ORDER_STATUS");
+f6bOpt.put("labelKey", "value");
+f6bOpt.put("valueKey", "sn");
+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", "订单日期");
+f7.put("colspan", 1);
+Map<String, Object> f7Opt = new HashMap<>();
+f7Opt.put("type", "date");
+f7Opt.put("format", "yyyy-MM-dd");
+f7Opt.put("valueFormat", "yyyy-MM-dd");
+f7Opt.put("clearable", true);
+f7.put("options", f7Opt);
+fields.add(f7);
+
+// ========== 8. 文本 text（只读展示） ==========
+Map<String, Object> f8 = new HashMap<>();
+f8.put("type", "text");
+f8.put("keyName", "createByName");
+f8.put("label", "创建人");
+f8.put("colspan", 1);
+Map<String, Object> f8Opt = new HashMap<>();
+f8Opt.put("colorClass", "");
+f8.put("utcTransformEnabled", false);
+f8.put("options", f8Opt);
+fields.add(f8);
+
+// ========== 9. 凭证 vabUpload ==========
+Map<String, Object> f9 = new HashMap<>();
+f9.put("type", "vabUpload");
+f9.put("keyName", "attachments");
+f9.put("label", "附件");
+f9.put("colspan", 2);
+Map<String, Object> f9Opt = new HashMap<>();
+f9Opt.put("limit", 10);
+f9Opt.put("entityTableCode", "PO_ORDER");
+f9Opt.put("entityTableDesc", "采购订单");
+f9Opt.put("hideRemoveButton", false);
+f9Opt.put("showFileSize", true);
+f9Opt.put("formScriptCode", "getList");
+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);
+f10.put("colspan", 1);
+Map<String, Object> f10Opt = new HashMap<>();
+f10Opt.put("vabSearchName", "supplierName");
+f10Opt.put("readonly", true);
+f10Opt.put("multipleChoices", false);
+Map<String, Object> f10Dialog = new HashMap<>();
+f10Dialog.put("formCode", "SUPPLIER_LIST");
+f10Dialog.put("valueSourceField", "supplierCode");
+f10Dialog.put("labelSourceField", "supplierName");
+f10Dialog.put("multipleChoices", false);
+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");
+f11.put("colspan", 1);
+Map<String, Object> f11Opt = new HashMap<>();
+f11Opt.put("formScriptEnabled", false);
+f11Opt.put("commonAttributeEnabled", false);
+f11Opt.put("optionItemValueType", 0);
+f11Opt.put("labelKey", "label");
+f11Opt.put("valueKey", "value");
+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"` 加载历史附件。
+
+```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> formData = (Map<String, Object>) data.get("formData");
+String billType = formData != null ? String.valueOf(formData.get("billType")) : "";
+
+// 所有单据都有合同编号
+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` | 搜索弹框表单编码 |
+| `PO_ORDER` | 凭证 entityTableCode |
+| 各字段 `keyName` | 与 formModel / 保存接口字段一致 |
+
+联调建议：先返回 `input` + `select`(静态 optionItems) 两列验证通路，再逐步放开其余类型。
+
+---
+
+## 6. 布局说明
+
+| 容器配置 | 说明 |
+|---------|------|
+| `dynamicSchemaColumns` | 每行列数，默认 4 |
+| `dynamicSchemaMode: append` | 追加到已有行之后 |
+| `dynamicSchemaMode: replace` | 清空已有行后替换 |
+| `dynamicSchemaMode: anchor` | 插入到占位锚点行 |
+| 字段 `colspan` | 占几列，超出自动换行 |
+
+---
+
+## 7. 注意事项
+
+1. **type 必须已注册**：未在设计器字段库中注册的 type 会被跳过。
+2. **keyName 唯一**：不要与表单已有字段重复。
+3. **动态规则分离**：运行时显隐/必填/只读等规则在「表单设置 → 动态字段规则」配置，不在本 JSON 中动态下发（初始 `hidden/required` 等仍可在定义里设置）。
+4. **formScriptParam / dialogQueryParam 等**：均为 JS 脚本字符串，不是 JSON 对象。
+5. **选项脚本与词汇互斥**：同一控件只能启用一种选项来源。
+6. **凭证仅编辑态加载**：无 `dataId` 时不请求历史附件。
+
+---
+
+## 8. 相关文件
+
+| 文件 | 说明 |
+|------|------|
+| `form-render/container-item/dynamicFieldMixin.js` | 运行时解析与生成 |
+| `form-designer/setting-panel/property-editor/container-table/table-dynamicField-editor.vue` | 设计器配置面板 |
+| `form-designer/widget-panel/widgetsConfig.js` | 各控件默认 schema |
+| `src/docs/表格动态列后台脚本示例.md` | 同平台 bd_api 脚本写法参考（列定义版） |