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

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"

@@ -1,8 +1,14 @@
 # 后台字段（动态生成）JSON 说明
 
-> 适用场景：表格布局容器（`table`）启用 **后台字段（动态生成）**（`dynamicSchemaEnabled`）后，后台脚本返回字段定义，前端运行时生成并渲染表单控件。
+> 适用场景：
+> - 表格布局容器（`table`）启用 **后台字段（动态生成）**（`dynamicSchemaEnabled`）
+> - 数据表格（`data-table`）启用 **接口动态列**（`dynamicColumnSourceType: api`）
 >
-> 相关代码：`form-render/container-item/dynamicFieldMixin.js`
+> 二者共用同一套请求/响应与字段定义 JSON 格式（见 `utils/dynamicSchemaUtil.js`）。
+>
+> **文档分工：** 本文维护控件类型与 options（**唯一维护点**）；数据表格差异（width、formatS、操作列等）见 [`数据表格动态列 JSON 说明.md`](./数据表格动态列%20JSON%20说明.md)。
+>
+> 相关代码：`form-render/container-item/dynamicFieldMixin.js`、`data-table-mixin.js`
 
 ---
 
@@ -14,6 +20,7 @@
   → 解析响应为「字段定义数组」
   → 按生成模式(append/replace/anchor)插入行布局
   → 各字段控件初始化（下拉/状态等可能再次请求选项数据）
+  → （业务需要时）脚本调用 loadDynamicSchema() 重新加载，见 §1.5
 ```
 
 ### 1.1 请求参数（前端 → 后台字段脚本）
@@ -37,7 +44,7 @@
 
 ```json
 {
-  "success": true,
+  "type": "success",
   "message": "ok",
   "objx": []
 }
@@ -45,57 +52,121 @@
 
 ### 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` 时自动执行。主表数据或业务条件变化后，需在脚本里**手动**调用以重新请求后台并刷新字段。
+
+**任意字段 / 按钮脚本（写法相同）：**
+
+```javascript
+this.getWidgetRef("headerTable").loadDynamicSchema();
+```
+
+> 字段与容器共用表单级 `refList`，**无需** `getParentTarget().getWidgetRef(...)`。  
+> `getParentTarget()` 仅用于操作列等场景直接调用**父级 data-table** 的方法（如 `deleteRow`），见本文数据表格文档操作列示例。
+
+**等待加载完成：**
+
+```javascript
+this.getWidgetRef("headerTable").loadDynamicSchema().then(() => {
+  // 动态行已重新生成，formModel 已补全新字段默认值
+});
+```
+
+| 项目 | 说明 |
+|------|------|
+| 方法 | `loadDynamicSchema()` |
+| 挂载组件 | `table-item`（`dynamicFieldMixin.js`） |
+| 行为 | 删除上次动态生成的行 → 用当前 `formModel` +「脚本返回对应的参数值」重新请求 → 按 `dynamicSchemaMode` 插入 |
+| 默认 loading | 不显示全屏 loading |
+| 前提 | `dynamicSchemaEnabled: true` 且已配置 `dynamicSchemaScriptCode` |
 
-| 优先级 | 结构 |
-|--------|------|
-| 1 | `objx` 本身为数组 |
-| 2 | `objx.fields` 为数组 |
-| 3 | `objx.columns` 为数组 |
+典型场景：主表 `billType` 变更、保存/加载单据后、点击「刷新表头」按钮。
 
-配置了 **转换脚本** 时，入参为完整 `res`，需返回数组或 `{ fields: [...] }`。
+数据表格动态列重新加载见 [`数据表格动态列 JSON 说明.md`](./数据表格动态列%20JSON%20说明.md) **§1.4**。
 
 ---
 
 ## 2. 通用字段定义 Schema
 
-每条字段定义会被转成 xform 控件 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,
-  "readonly": false,
-  "disabled": false,
-  "hidden": false,
-  "defaultValue": "",
-  "placeholder": "请输入",
-  "colspan": 1,
-  "optionItems": [],
-  "options": {}
+  "required": true
 }
 ```
 
 ### 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` 至少提供一个，否则该条定义会被忽略。
+| 属性 | 说明 |
+|------|------|
+| `keyName` | 字段绑定名，**必填** |
+| `type` | 控件类型 |
+| `label` | 显示标签 |
+| `colspan` | 表头占列数，默认 `1` |
+| `optionItems` | 静态选项 |
+| `required` / `readonly` / `disabled` / `hidden` | 字段级属性（**顶层**） |
+| `defaultValue` / `placeholder` | 默认值 / 占位符（**顶层**） |
+| `options` | 控件扩展配置（**不含** `required` 等字段级属性） |
+
+> 未提供 `keyName` 的字段定义会被忽略（操作列除外，见数据表格文档）。
 
 ### 2.2 选项类控件三种数据来源
 
@@ -109,29 +180,15 @@
 
 **互斥规则：** `formScriptEnabled` 与 `commonAttributeEnabled` 不能同时为 `true`。
 
-**词汇下拉/状态 labelKey/valueKey：**
-
-```json
-{
-  "labelKey": "value",
-  "valueKey": "sn"
-}
-```
-
-**脚本下拉 labelKey/valueKey（默认）：**
+**系统词汇：** 只需 `commonAttributeEnabled` + `commonAttributeCode`，**无需**配置 `labelKey` / `valueKey`（前端固定：显示字段 `value`，关联字段 `sn`）。
 
-```json
-{
-  "labelKey": "label",
-  "valueKey": "value"
-}
-```
+**脚本选项：** 返回字段默认为 `label` / `value`，一般无需配置 `labelKey` / `valueKey`（脚本返回自定义字段名时除外）。
 
 **选项脚本返回格式：**
 
 ```json
 {
-  "success": true,
+  "type": "success",
   "objx": {
     "records": [
       { "label": "选项A", "value": "A" }
@@ -144,7 +201,7 @@
 
 ```json
 {
-  "success": true,
+  "type": "success",
   "objx": [
     { "label": "选项A", "value": "A" }
   ]
@@ -171,25 +228,12 @@
   "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": ""
-  }
+  "required": true
 }
 ```
 
+> `maxLength` 默认 `null`（不限制）；需限长或字数统计时再设 `maxLength` / `showWordLimit`。
+
 | options 字段 | 类型 | 默认值 | 说明 |
 |-------------|------|--------|------|
 | `type` | string | `text` | 输入类型：`text` / `password` 等 |
@@ -212,18 +256,12 @@
   "type": "textarea",
   "keyName": "remark",
   "label": "备注",
-  "placeholder": "请输入备注",
-  "defaultValue": "",
-  "colspan": 2,
-  "options": {
-    "rows": 3,
-    "minLength": null,
-    "maxLength": 500,
-    "showWordLimit": true
-  }
+  "colspan": 2
 }
 ```
 
+> `rows` 默认 `3`；`maxLength` 默认不限制。
+
 | options 字段 | 类型 | 默认值 | 说明 |
 |-------------|------|--------|------|
 | `rows` | number | 3 | 可见行数 |
@@ -242,15 +280,10 @@
   "label": "数量",
   "required": true,
   "defaultValue": 0,
-  "colspan": 1,
   "options": {
     "min": 0,
     "max": 999999,
-    "precision": 0,
-    "step": 1,
-    "controlsPosition": "right",
-    "formulaEnabled": false,
-    "formula": ""
+    "precision": 0
   }
 }
 ```
@@ -277,18 +310,10 @@
   "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
-  }
+    { "label": "否", "value": "0" },
+    { "label": "是", "value": "1" }
+  ]
 }
 ```
 
@@ -301,12 +326,8 @@
   "label": "付款方式",
   "options": {
     "formScriptEnabled": true,
-    "commonAttributeEnabled": false,
     "formScriptCode": "payTypeList",
-    "labelKey": "label",
-    "valueKey": "value",
-    "formScriptParam": "return { parentCode: this.formModel.billType }",
-    "displayStyle": "inline"
+    "formScriptParam": "return { parentCode: this.formModel.billType }"
   }
 }
 ```
@@ -320,11 +341,8 @@
   "label": "是否",
   "defaultValue": "1",
   "options": {
-    "formScriptEnabled": false,
     "commonAttributeEnabled": true,
-    "commonAttributeCode": "YES_NO",
-    "labelKey": "value",
-    "valueKey": "sn"
+    "commonAttributeCode": "YES_NO"
   }
 }
 ```
@@ -352,18 +370,13 @@
     { "label": "短信", "value": "SMS" },
     { "label": "邮件", "value": "EMAIL" },
     { "label": "站内信", "value": "MSG" }
-  ],
-  "options": {
-    "formScriptEnabled": false,
-    "commonAttributeEnabled": false,
-    "displayStyle": "inline"
-  }
+  ]
 }
 ```
 
 #### 后台脚本 / 系统词汇
 
-配置方式与 `radio`、`select` 相同，将 `formScriptEnabled` 或 `commonAttributeEnabled` 放入 `options` 即可。
+配置方式与 `radio`、`select` 相同：脚本模式写 `formScriptEnabled` + `formScriptCode`；词汇模式写 `commonAttributeEnabled` + `commonAttributeCode`。
 
 ---
 
@@ -376,21 +389,14 @@
   "type": "select",
   "keyName": "payType",
   "label": "付款方式",
-  "required": true,
   "defaultValue": "CASH",
-  "placeholder": "请选择",
-  "colspan": 1,
   "optionItems": [
-    { "label": "现金", "value": "CASH", "disabled": false },
-    { "label": "转账", "value": "TRANSFER", "disabled": false }
+    { "label": "现金", "value": "CASH" },
+    { "label": "转账", "value": "TRANSFER" }
   ],
+  "required": true,
   "options": {
-    "formScriptEnabled": false,
-    "commonAttributeEnabled": false,
-    "clearable": true,
-    "filterable": true,
-    "multiple": false,
-    "multipleLimit": 0
+    "filterable": true
   }
 }
 ```
@@ -404,12 +410,8 @@
   "label": "子付款方式",
   "options": {
     "formScriptEnabled": true,
-    "commonAttributeEnabled": false,
     "formScriptCode": "subPayTypeList",
-    "labelKey": "label",
-    "valueKey": "value",
     "formScriptParam": "return { parentPayType: this.formModel.payType }",
-    "clearable": true,
     "filterable": true
   }
 }
@@ -437,12 +439,8 @@
   "label": "订单状态",
   "defaultValue": "1",
   "options": {
-    "formScriptEnabled": false,
     "commonAttributeEnabled": true,
     "commonAttributeCode": "ORDER_STATUS",
-    "labelKey": "value",
-    "valueKey": "sn",
-    "clearable": true,
     "filterable": true
   }
 }
@@ -468,7 +466,7 @@
 
 ```json
 {
-  "success": true,
+  "type": "success",
   "objx": {
     "records": [
       { "deptName": "采购部", "deptCode": "D001" },
@@ -497,24 +495,12 @@
   "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
-  }
+  "required": true
 }
 ```
 
+> `format` / `valueFormat` 默认均为 `yyyy-MM-dd`，非特殊格式无需配置。
+
 | options.type | 说明 |
 |-------------|------|
 | `date` | 日期 |
@@ -539,17 +525,7 @@
 {
   "type": "text",
   "keyName": "createByName",
-  "label": "创建人",
-  "defaultValue": "",
-  "colspan": 1,
-  "options": {
-    "colorClass": "",
-    "formatType": null,
-    "renderHandle": null,
-    "autoValueEnabled": false,
-    "autoValueHanlde": null,
-    "utcTransformEnabled": false
-  }
+  "label": "创建人"
 }
 ```
 
@@ -563,41 +539,44 @@
 
 ---
 
-### 3.9 凭证（type: `vabUpload`）
+### 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",
+  "keyName": "attachments_a1b2c3d4e5f6789012345678abcdef",
   "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 }"
+    "limit": 10
   }
 }
 ```
 
+> `formScriptCode` 加载历史附件默认 `getList`，一般无需配置。  
+> **无需**维护 `entityTableCode` / `entityTableDesc`（设计器「实体表」配置已废弃；凭证按 `formCode` + 字段 `keyName`（`taBm`）+ 单据 `dataId` 加载）。
+
 | options 字段 | 类型 | 说明 |
 |-------------|------|------|
 | `limit` | number | 最大文件数，`1` 为单文件 |
 | `hideRemoveButton` | boolean | 隐藏删除按钮 |
-| `entityTableCode` | string | 业务表编码（附件关联） |
-| `entityTableDesc` | string | 业务表描述 |
 | `hiddenFileInfo` | boolean | 隐藏文件信息区 |
 | `hiddenFileName` | boolean | 隐藏文件名 |
 | `showFileSize` | boolean | 显示文件大小 |
@@ -612,7 +591,7 @@
 {
   "formCode": "PO_ORDER_FORM",
   "formVersion": "1.0",
-  "taBm": "attachments",
+  "taBm": "attachments_a1b2c3d4e5f6789012345678abcdef",
   "data": {
     "id": "10001"
   }
@@ -623,7 +602,7 @@
 
 ```json
 {
-  "success": true,
+  "type": "success",
   "objx": [
     {
       "id": "file001",
@@ -651,18 +630,27 @@
   "keyName": "supplierCode",
   "label": "供应商",
   "required": true,
-  "colspan": 1,
   "options": {
     "vabSearchName": "supplierName",
-    "readonly": true,
-    "multipleChoices": false,
-    "dialogModel": "1",
+    "searchDialogConfig": {
+      "formCode": "SUPPLIER_LIST",
+      "valueSourceField": "supplierCode",
+      "labelSourceField": "supplierName"
+    }
+  }
+}
+```
+
+扩展配置（按需）示例：
+
+```json
+{
+  "options": {
     "searchDialogConfig": {
       "formCode": "SUPPLIER_LIST",
       "formName": "供应商列表",
       "valueSourceField": "supplierCode",
       "labelSourceField": "supplierName",
-      "multipleChoices": false,
       "tableEnabled": true,
       "dialogQueryParam": "return { status: '1' }",
       "dialogCustomParam": "return { title: '选择供应商' }"
@@ -736,13 +724,7 @@
   "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" },
@@ -797,10 +779,7 @@
   "label": "流程状态",
   "options": {
     "formScriptEnabled": true,
-    "commonAttributeEnabled": false,
     "formScriptCode": "wfStatusList",
-    "labelKey": "label",
-    "valueKey": "value",
     "formScriptParam": "return { processId: this.formModel.processId }"
   }
 }
@@ -816,11 +795,8 @@
   "keyName": "billStatus",
   "label": "单据状态",
   "options": {
-    "formScriptEnabled": false,
     "commonAttributeEnabled": true,
-    "commonAttributeCode": "BILL_STATUS",
-    "labelKey": "value",
-    "valueKey": "sn"
+    "commonAttributeCode": "BILL_STATUS"
   }
 }
 ```
@@ -833,29 +809,26 @@
 
 ```json
 {
-  "success": true,
+  "type": "success",
   "message": "ok",
   "objx": [
     {
       "type": "input",
       "keyName": "contractNo",
       "label": "合同编号",
-      "required": true,
-      "colspan": 1
+      "required": true
     },
     {
       "type": "textarea",
       "keyName": "remark",
       "label": "备注",
-      "colspan": 2,
-      "options": { "rows": 3, "maxLength": 500, "showWordLimit": true }
+      "colspan": 2
     },
     {
       "type": "number",
       "keyName": "totalQty",
       "label": "数量",
       "defaultValue": 1,
-      "colspan": 1,
       "options": { "min": 0, "precision": 0 }
     },
     {
@@ -866,19 +839,18 @@
       "optionItems": [
         { "label": "否", "value": "0" },
         { "label": "是", "value": "1" }
-      ],
-      "colspan": 1
+      ]
     },
     {
       "type": "checkbox",
       "keyName": "notifyTypes",
       "label": "通知方式",
       "defaultValue": [],
+      "colspan": 2,
       "optionItems": [
         { "label": "短信", "value": "SMS" },
         { "label": "邮件", "value": "EMAIL" }
-      ],
-      "colspan": 2
+      ]
     },
     {
       "type": "select",
@@ -886,37 +858,26 @@
       "label": "付款方式",
       "options": {
         "formScriptEnabled": true,
-        "formScriptCode": "payTypeList",
-        "labelKey": "label",
-        "valueKey": "value"
-      },
-      "colspan": 1
+        "formScriptCode": "payTypeList"
+      }
     },
     {
       "type": "date",
       "keyName": "orderDate",
-      "label": "订单日期",
-      "colspan": 1,
-      "options": {
-        "format": "yyyy-MM-dd",
-        "valueFormat": "yyyy-MM-dd"
-      }
+      "label": "订单日期"
     },
     {
       "type": "text",
       "keyName": "createByName",
-      "label": "创建人",
-      "colspan": 1
+      "label": "创建人"
     },
     {
       "type": "vabUpload",
-      "keyName": "attachments",
+      "keyName": "attachments_a1b2c3d4e5f6789012345678abcdef",
       "label": "附件",
       "colspan": 2,
       "options": {
-        "limit": 10,
-        "entityTableCode": "PO_ORDER",
-        "formScriptCode": "getList"
+        "limit": 10
       }
     },
     {
@@ -924,14 +885,12 @@
       "keyName": "supplierCode",
       "label": "供应商",
       "required": true,
-      "colspan": 1,
       "options": {
         "vabSearchName": "supplierName",
         "searchDialogConfig": {
           "formCode": "SUPPLIER_LIST",
           "valueSourceField": "supplierCode",
-          "labelSourceField": "supplierName",
-          "multipleChoices": false
+          "labelSourceField": "supplierName"
         }
       }
     },
@@ -940,7 +899,6 @@
       "keyName": "orderStatus",
       "label": "订单状态",
       "defaultValue": "1",
-      "colspan": 1,
       "options": {
         "statusParam": [
           { "label": "草稿", "value": "1", "type": "info" },
@@ -966,18 +924,21 @@
 |------|------|
 | 返回类型 | `List<Map<String, Object>>`，每个 Map 为一条字段定义 |
 | 嵌套配置 | 控件扩展属性放在 `options`（`Map`）中 |
+| 默认值 | 与控件设计器默认相同的属性**无需写入**，见 **§2.0** |
 | 静态选项 | `select` / `radio` / `checkbox` 可直接 `put("optionItems", list)` |
-| 请求入参 | 前端请求体含 `formData`（当前表单数据）及容器「脚本返回对应的参数值」 |
+| 请求入参 | Java 脚本通过 `this.getBinding().getVariables()` 获取；表头脚本直接读 `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;
+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
@@ -994,14 +955,6 @@ 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 ==========
@@ -1010,11 +963,6 @@ 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 ==========
@@ -1023,12 +971,9 @@ 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);
 
@@ -1038,7 +983,6 @@ 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", "否");
@@ -1049,11 +993,6 @@ 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） ==========
@@ -1081,17 +1020,11 @@ 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);
 
@@ -1101,13 +1034,9 @@ 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);
 
@@ -1116,13 +1045,6 @@ 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（只读展示） ==========
@@ -1130,26 +1052,16 @@ 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("keyName", "attachments_a1b2c3d4e5f6789012345678abcdef");
 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);
 
@@ -1159,16 +1071,12 @@ 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);
@@ -1179,13 +1087,7 @@ 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", "草稿");
@@ -1242,7 +1144,7 @@ return list;
 
 ### 5.4 附属脚本：凭证 getList
 
-字段 `attachments` 在编辑态（有 dataId）时，通过 `formScriptCode: "getList"` 加载历史附件。
+字段 `attachments_<唯一后缀>` 在编辑态（有 dataId）时，通过 `formScriptCode: "getList"` 加载历史附件；`taBm` 与 `keyName` 一致。
 
 ```java
 import java.util.ArrayList;
@@ -1275,8 +1177,9 @@ 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> 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<>();
@@ -1316,7 +1219,6 @@ return fields;
 | `payTypeList` | 下拉选项二次请求脚本 |
 | `ORDER_STATUS` | 系统词汇编码 |
 | `SUPPLIER_LIST` | 搜索弹框表单编码 |
-| `PO_ORDER` | 凭证 entityTableCode |
 | 各字段 `keyName` | 与 formModel / 保存接口字段一致 |
 
 联调建议：先返回 `input` + `select`(静态 optionItems) 两列验证通路，再逐步放开其余类型。
@@ -1339,10 +1241,11 @@ return fields;
 
 1. **type 必须已注册**：未在设计器字段库中注册的 type 会被跳过。
 2. **keyName 唯一**：不要与表单已有字段重复。
-3. **动态规则分离**：运行时显隐/必填/只读等规则在「表单设置 → 动态字段规则」配置，不在本 JSON 中动态下发（初始 `hidden/required` 等仍可在定义里设置）。
-4. **formScriptParam / dialogQueryParam 等**：均为 JS 脚本字符串，不是 JSON 对象。
-5. **选项脚本与词汇互斥**：同一控件只能启用一种选项来源。
-6. **凭证仅编辑态加载**：无 `dataId` 时不请求历史附件。
+3. **只写差异属性**：与控件设计器默认值相同的属性无需维护，见 **§2.0 默认值**。
+4. **动态规则分离**：运行时显隐/必填/只读等规则在「表单设置 → 动态字段规则」配置，不在本 JSON 中动态下发（初始 `hidden/required` 等仍可在定义里设置）。
+5. **formScriptParam / dialogQueryParam 等**：均为 JS 脚本字符串，不是 JSON 对象。
+6. **选项脚本与词汇互斥**：同一控件只能启用一种选项来源。
+7. **凭证仅编辑态加载**：无 `dataId` 时不请求历史附件。
 
 ---
 
@@ -1350,7 +1253,9 @@ return fields;
 
 | 文件 | 说明 |
 |------|------|
-| `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 脚本写法参考（列定义版） |
+| `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) | 数据表格差异说明 |