cloud-web-corejs 1.0.276 → 1.0.277

package/src/components/xform/docs//346/225/260/346/215/256/350/241/250/346/240/274/345/212/250/346/200/201/345/210/227 JSON /350/257/264/346/230/216.md"

@@ -0,0 +1,657 @@
+# 数据表格动态列 JSON 说明
+
+> **本文只描述数据表格与表头动态字段的差异。** 控件类型、options 配置、选项脚本等**统一维护**在 [`后台字段（动态生成）JSON 说明.md`](./后台字段（动态生成）JSON%20说明.md)。
+>
+> **完整 JSON / Java 综合示例见 §0。** 协议代码：`utils/dynamicSchemaUtil.js` · 运行时：`form-render/container-item/data-table-mixin.js`
+
+---
+
+## 0. 完整综合示例
+
+以下示例覆盖**控件列、展示列、多级表头、操作列**。控件 `options` 字段说明见主文档 **§3**；与表头的差异仅为 **`width` / `formatS` / `children`**，**不写 `colspan`**。列对齐（`align`）由前端默认，**后台无需设置**。
+
+### 0.1 响应 JSON
+
+`objx` 为数组，或 `objx.columns` 为数组，二者等价。配置了 `dynamicSchemaConvert` 时，转换脚本返回值须为数组或 `{ columns: [...] }`。
+
+```json
+{
+  "type": "success",
+  "message": "ok",
+  "objx": {
+    "columns": [
+      {
+        "type": "input",
+        "keyName": "lineNo",
+        "label": "行号",
+        "width": 80,
+        "required": true
+      },
+      {
+        "type": "number",
+        "keyName": "qty",
+        "label": "数量",
+        "width": 100,
+        "options": { "min": 0, "precision": 2 }
+      },
+      {
+        "type": "select",
+        "keyName": "unitCode",
+        "label": "单位",
+        "width": 90,
+        "optionItems": [
+          { "label": "件", "value": "PCS" },
+          { "label": "箱", "value": "BOX" }
+        ]
+      },
+      {
+        "type": "date",
+        "keyName": "deliveryDate",
+        "label": "交货日期",
+        "width": 120
+      },
+      {
+        "type": "vabsearch",
+        "keyName": "materialCode",
+        "label": "物料",
+        "width": 160,
+        "options": {
+          "vabSearchName": "materialName",
+          "searchDialogConfig": {
+            "formCode": "MATERIAL_LIST",
+            "valueSourceField": "materialCode",
+            "labelSourceField": "materialName"
+          }
+        }
+      },
+      {
+        "keyName": "lineAmount",
+        "formatS": "n5",
+        "label": "行金额",
+        "width": 120
+      },
+      {
+        "keyName": "qtyWarn",
+        "formatS": "render",
+        "label": "库存预警",
+        "width": 100,
+        "render": "let q = params.row.qty || 0;\nreturn q < (params.row.safeQty || 0) ? '不足' : '正常';"
+      },
+      {
+        "keyName": "_createBy",
+        "label": "创建人",
+        "width": 100
+      },
+      {
+        "label": "价格信息",
+        "children": [
+          {
+            "type": "number",
+            "keyName": "unitPrice",
+            "label": "单价",
+            "width": 100,
+            "options": { "precision": 4 }
+          },
+          {
+            "type": "number",
+            "keyName": "taxRate",
+            "label": "税率(%)",
+            "width": 90,
+            "options": { "min": 0, "max": 100, "precision": 2 }
+          }
+        ]
+      },
+      {
+        "type": "a-link",
+        "label": "查看",
+        "width": 80,
+        "options": {
+          "onClick": "let p = this.tableParam;\nthis.getParentTarget().openDetailDialog(p.row);"
+        }
+      },
+      {
+        "type": "button",
+        "label": "同步",
+        "width": 80,
+        "options": {
+          "type": "primary",
+          "onClick": "let p = this.tableParam;\nthis.getParentTarget().syncLine(p.row);"
+        }
+      },
+      {
+        "type": "dropdown",
+        "label": "操作",
+        "width": 90,
+        "dropdownItems": [
+          {
+            "label": "复制",
+            "onClick": "let p = this.tableParam;\nthis.getParentTarget().copyRow(p.row);"
+          },
+          {
+            "label": "删除",
+            "onClick": "let p = this.tableParam;\nthis.getParentTarget().deleteRow(p.row, p.rowIndex);"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 0.2 Java 脚本
+
+脚本编码建议：`getDynamicTableColumns`（配置在 data-table「接口动态列 → 脚本编码」）。  
+返回类型：`List<Map<String, Object>>`，平台自动包装为响应 `objx` 数组（与 `objx.columns` 等价）。
+
+**与表头脚本的差异：**
+
+| 表头 | 数据表格列 |
+|------|-----------|
+| `colspan` | `width` |
+| 无 | 展示列写 `formatS`（如 `n5`、`d1`、`render`） |
+| 无 | 操作列写 `type` + 顶层 `label` + `options.onClick`；dropdown 写顶层 `dropdownItems`（无 `keyName`） |
+| 无 | 多级表头写 `children` |
+
+**请求入参（api 模式）：** 前端 HTTP 请求体含 `formCode`、`taBm`、`dataId` 及内层 `data`（含 `formData` 与「脚本返回对应的参数值」）。**Java 脚本**通过 `this.getBinding().getVariables()` 读取绑定变量。
+
+```java
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+Map<String, Object> formData = this.getBinding().getVariables();
+String billType = ((Map<String, Object>) formData.get("data")).get("billType").toString();
+// 表单主表： ((Map<String, Object>) formData.get("data")).get("formData")
+
+List<Map<String, Object>> columns = new ArrayList<>();
+
+// ========== 1. 控件列 input ==========
+Map<String, Object> c1 = new HashMap<>();
+c1.put("type", "input");
+c1.put("keyName", "lineNo");
+c1.put("label", "行号");
+c1.put("width", 80);
+c1.put("required", true);
+columns.add(c1);
+
+// ========== 2. 控件列 number ==========
+Map<String, Object> c2 = new HashMap<>();
+c2.put("type", "number");
+c2.put("keyName", "qty");
+c2.put("label", "数量");
+c2.put("width", 100);
+Map<String, Object> c2Opt = new HashMap<>();
+c2Opt.put("min", 0);
+c2Opt.put("precision", 2);
+c2.put("options", c2Opt);
+columns.add(c2);
+
+// ========== 3. 控件列 select（静态 optionItems） ==========
+Map<String, Object> c3 = new HashMap<>();
+c3.put("type", "select");
+c3.put("keyName", "unitCode");
+c3.put("label", "单位");
+c3.put("width", 90);
+List<Map<String, Object>> c3Items = new ArrayList<>();
+Map<String, Object> c3Item1 = new HashMap<>();
+c3Item1.put("label", "件");
+c3Item1.put("value", "PCS");
+c3Items.add(c3Item1);
+Map<String, Object> c3Item2 = new HashMap<>();
+c3Item2.put("label", "箱");
+c3Item2.put("value", "BOX");
+c3Items.add(c3Item2);
+c3.put("optionItems", c3Items);
+columns.add(c3);
+
+// ========== 4. 控件列 date ==========
+Map<String, Object> c4 = new HashMap<>();
+c4.put("type", "date");
+c4.put("keyName", "deliveryDate");
+c4.put("label", "交货日期");
+c4.put("width", 120);
+columns.add(c4);
+
+// ========== 5. 控件列 vabsearch ==========
+Map<String, Object> c5 = new HashMap<>();
+c5.put("type", "vabsearch");
+c5.put("keyName", "materialCode");
+c5.put("label", "物料");
+c5.put("width", 160);
+Map<String, Object> c5Opt = new HashMap<>();
+c5Opt.put("vabSearchName", "materialName");
+Map<String, Object> c5Dialog = new HashMap<>();
+c5Dialog.put("formCode", "MATERIAL_LIST");
+c5Dialog.put("valueSourceField", "materialCode");
+c5Dialog.put("labelSourceField", "materialName");
+c5Opt.put("searchDialogConfig", c5Dialog);
+c5.put("options", c5Opt);
+columns.add(c5);
+
+// ========== 6. 展示列（formatS = n5） ==========
+Map<String, Object> c6 = new HashMap<>();
+c6.put("keyName", "lineAmount");
+c6.put("formatS", "n5");
+c6.put("label", "行金额");
+c6.put("width", 120);
+columns.add(c6);
+
+// ========== 7. 展示列（formatS = render） ==========
+Map<String, Object> c7 = new HashMap<>();
+c7.put("keyName", "qtyWarn");
+c7.put("formatS", "render");
+c7.put("label", "库存预警");
+c7.put("width", 100);
+c7.put("render", "let q = params.row.qty || 0;\nreturn q < (params.row.safeQty || 0) ? '不足' : '正常';");
+columns.add(c7);
+
+// ========== 8. 展示列（审计列，只写 keyName） ==========
+Map<String, Object> c8 = new HashMap<>();
+c8.put("keyName", "_createBy");
+c8.put("label", "创建人");
+c8.put("width", 100);
+columns.add(c8);
+
+// ========== 9. 多级表头 ==========
+Map<String, Object> c9Group = new HashMap<>();
+c9Group.put("label", "价格信息");
+List<Map<String, Object>> c9Children = new ArrayList<>();
+
+Map<String, Object> c9a = new HashMap<>();
+c9a.put("type", "number");
+c9a.put("keyName", "unitPrice");
+c9a.put("label", "单价");
+c9a.put("width", 100);
+Map<String, Object> c9aOpt = new HashMap<>();
+c9aOpt.put("precision", 4);
+c9a.put("options", c9aOpt);
+c9Children.add(c9a);
+
+Map<String, Object> c9b = new HashMap<>();
+c9b.put("type", "number");
+c9b.put("keyName", "taxRate");
+c9b.put("label", "税率(%)");
+c9b.put("width", 90);
+Map<String, Object> c9bOpt = new HashMap<>();
+c9bOpt.put("min", 0);
+c9bOpt.put("max", 100);
+c9bOpt.put("precision", 2);
+c9b.put("options", c9bOpt);
+c9Children.add(c9b);
+
+c9Group.put("children", c9Children);
+columns.add(c9Group);
+
+// ========== 10. 操作列 a-link（无 keyName，默认不可排序/筛选） ==========
+Map<String, Object> c10 = new HashMap<>();
+c10.put("type", "a-link");
+c10.put("label", "查看");
+c10.put("width", 80);
+Map<String, Object> c10Opt = new HashMap<>();
+c10Opt.put("onClick", "let p = this.tableParam;\nthis.getParentTarget().openDetailDialog(p.row);");
+c10.put("options", c10Opt);
+columns.add(c10);
+
+// ========== 11. 操作列 button ==========
+Map<String, Object> c11 = new HashMap<>();
+c11.put("type", "button");
+c11.put("label", "同步");
+c11.put("width", 80);
+Map<String, Object> c11Opt = new HashMap<>();
+c11Opt.put("type", "primary");
+c11Opt.put("onClick", "let p = this.tableParam;\nthis.getParentTarget().syncLine(p.row);");
+c11.put("options", c11Opt);
+columns.add(c11);
+
+// ========== 12. 操作列 dropdown（dropdownItems 写顶层） ==========
+Map<String, Object> c12 = new HashMap<>();
+c12.put("type", "dropdown");
+c12.put("label", "操作");
+c12.put("width", 90);
+List<Map<String, Object>> dropdownItems = new ArrayList<>();
+
+Map<String, Object> m1 = new HashMap<>();
+m1.put("label", "复制");
+m1.put("onClick", "let p = this.tableParam;\nthis.getParentTarget().copyRow(p.row);");
+dropdownItems.add(m1);
+
+Map<String, Object> m2 = new HashMap<>();
+m2.put("label", "删除");
+m2.put("onClick", "let p = this.tableParam;\nthis.getParentTarget().deleteRow(p.row, p.rowIndex);");
+dropdownItems.add(m2);
+
+c12.put("dropdownItems", dropdownItems);
+columns.add(c12);
+
+return columns;
+```
+
+下拉/搜索等控件若配置了 `formScriptCode`，须**单独维护**选项脚本，写法与主文档 **§5.3** 相同；列内 `onClick` / `render` 为前端 JS 字符串，表单数据用 `this.formModel`，行数据用 `this.tableParam.row`。
+
+---
+
+## 1. 调用流程
+
+```
+data-table mounted
+  → 加载条件脚本（可选）
+  → script：执行 dynamicColumnsScript
+  → api：请求 dynamicColumnScriptCode
+  → 解析 objx → 合并静态列 → 生成列控件
+  → （业务需要时）脚本调用 loadDynamicColumns() 重新加载，见 §1.4
+```
+
+| 设计器配置 | 属性名 |
+|-----------|--------|
+| 动态列来源 | `dynamicColumnSourceType`：`none` / `script` / `api` |
+| 脚本编码 | `dynamicColumnScriptCode` |
+| 额外参数 | `dynamicColumnScriptParam` |
+| 转换脚本 | `dynamicSchemaConvert` |
+| 加载条件 | `dynamicColumnLoadScript` |
+| 动态列模式 | `dynamicColumnMode`：`append` / `replace` |
+| 前端列脚本 | `dynamicColumnsScript` |
+
+### 1.1 请求参数
+
+与表头字段相同内层 `{ formData, ...extra }`，数据表格**额外**携带外层字段。Java 脚本读取方式：
+
+```java
+Map<String, Object> formData = this.getBinding().getVariables();
+String billType = ((Map<String, Object>) formData.get("data")).get("billType").toString();
+```
+
+| 字段 | 说明 |
+|------|------|
+| `formCode` / `formVersion` | 表单编码与版本 |
+| `taBm` | 表格绑定字段名 |
+| `dataId` | 单据 ID |
+| `data` | 内层载荷，含 `formData` 与额外参数 |
+
+```json
+{
+  "formCode": "PO_ORDER_FORM",
+  "taBm": "orderItems",
+  "dataId": "10001",
+  "data": {
+    "dataId": "10001",
+    "formData": { "id": "10001", "billType": "PO" },
+    "bizType": "PO"
+  }
+}
+```
+
+### 1.2 响应与 objx
+
+与表头字段相同，见主文档 §1.2、§1.3。列数组取 `objx` 或 `objx.columns`。
+
+### 1.3 前端列脚本（script 模式）
+
+```javascript
+return [
+  { type: "input", keyName: "lineNo", label: "行号", width: 80 },
+  {
+    type: "select",
+    keyName: "warehouseCode",
+    label: "仓库",
+    width: 120,
+    options: {
+      formScriptEnabled: true,
+      formScriptCode: "warehouseList",
+      formScriptParam: "return { orgId: this.formModel.orgId }",
+    },
+  },
+];
+```
+
+列内脚本：`this.tableParam.row` / `this.formModel`。
+
+### 1.4 脚本重新加载（数据表格动态列）
+
+首次加载在 `data-table` `mounted` 时自动执行（可通过 `dynamicColumnLoadScript` 控制是否加载）。列需随主表或业务条件变化而更新时，在脚本里**手动**调用：
+
+**任意字段 / 按钮脚本（写法相同）：**
+
+```javascript
+// dataTableName：设计器里 data-table 容器的 name
+this.getWidgetRef("orderItemsTable").loadDynamicColumns();
+```
+
+> 字段与容器共用表单级 `refList`，**无需** `getParentTarget().getWidgetRef(...)`。  
+> 脚本跑在**当前表格操作列**内时，也可写 `this.getParentTarget().loadDynamicColumns()`（父级即本表）。
+
+**带回调 / loading：**
+
+```javascript
+this.getWidgetRef("orderItemsTable").loadDynamicColumns({
+  isLoading: true,
+  success(res, columns) {
+    // api 模式：res 为接口响应；columns 为合并后的有效列
+  },
+  fail(err) {},
+});
+```
+
+| 项目 | 说明 |
+|------|------|
+| 方法 | `loadDynamicColumns(options?)` |
+| `api` 模式 | 重新请求 `dynamicColumnScriptCode`，解析 `objx` 后合并列并刷新表格 |
+| `script` 模式 | 重新执行 `dynamicColumnsScript` 并刷新列 |
+| 行为 | 按 `dynamicColumnMode` 合并静态列 → 重建列控件 → `reloadColumn` |
+| 前提 | `dynamicColumnSourceType` 为 `api` 或 `script`，且对应脚本已配置 |
+
+表头动态字段重新加载见主文档 **§1.5**（`loadDynamicSchema()`）。
+
+---
+
+## 2. 字段定义（在表头协议上的扩展）
+
+### 2.1 最小字段集
+
+**与表头相同的部分**（详见主文档 §2.0）：
+
+```
+keyName + type + label + optionItems? + required? + options?
+```
+
+字段级属性（`required`、`readonly`、`disabled`、`hidden`、`defaultValue`、`placeholder`）写**顶层**，不写 `options`（详见主文档 §2.1）。
+
+**数据表格额外顶层字段**（仅此几项，其余勿重复维护）。控件 `options` 默认值见主文档 **§2.0**，与默认值相同的不写：
+
+| 字段 | 说明 | 默认 |
+|------|------|------|
+| `width` | 列宽 | 150 |
+| `sortable` | 可排序 | true（操作列默认 false） |
+| `filterable` | 可筛选 | true（操作列默认 false） |
+| `formatS` | 展示列类型（见 §2.2） | 由 `type` 自动映射 |
+| `children` | 多级表头 | - |
+
+**三类列写法：**
+
+| 类别 | 写法 | 示例 |
+|------|------|------|
+| 控件列 | `type` + `keyName` + `label` + `width` | input / select / date |
+| 展示列 | `keyName` + `formatS` + `label` + `width` | d1 / n5 / render |
+| 审计列 | `keyName` + `label` + `width` | `_createBy` 等（不写 `formatS`） |
+| 操作列 | `type` + `label` + `width` + `options`（无 `keyName`） | a-link / button；多操作用 dropdown + 顶层 `dropdownItems`；**默认不可排序、不可筛选** |
+
+### 2.2 type → formatS 映射
+
+控件列**只写 `type`**，前端自动映射：
+
+| type | formatS |
+|------|---------|
+| `input` | `editInput` |
+| `number` | `editNumber` |
+| `date` | `editDate` |
+| `select` | `editSelect` |
+| `vabsearch` | `editSearch` |
+| `vabUpload` / `baseAttachment` | `editAttachment` |
+| `status` | `editStatus` |
+| `text` / `textarea` / `checkbox` / `radio` | 同名 |
+| `a-text` | `aText` |
+| `a-link` / `button` / `dropdown` | 同名 |
+
+**展示列**（不写 `type`，只写 `formatS`）：
+
+| formatS | 说明 |
+|---------|------|
+| `d1`~`d5` | 日期格式 |
+| `n1`~`n7` | 数字/百分比 |
+| `render` | 自定义渲染（配 `render` 脚本） |
+| `_createBy` / `_modifyBy` / `create_date` / `modify_date` | 审计列，只写 `keyName`（不写 `type` / `formatS`） |
+
+各控件 `options` 字段说明 → 主文档 **§3**（input / select / vabsearch 等，**勿在本文件重复维护**）。
+
+**附件列 `keyName`：** 须为 `attachments_<唯一后缀>`，与主文档 **§3.9** 一致；行数据 `formModel[taBm][i][keyName]` 存文件数组，`getList` 的 `taBm` 同此完整名。
+
+## 3. 数据表格专用示例
+
+以下类型**不在表头场景使用**，仅在本节维护示例。
+
+### 3.1 展示列
+
+```json
+{
+  "keyName": "deliveryDate",
+  "formatS": "d1",
+  "label": "交货日期",
+  "width": 120,
+  "utcTransformEnabled": true
+}
+```
+
+```json
+{
+  "keyName": "lineAmount",
+  "formatS": "n5",
+  "label": "行金额",
+  "width": 120
+}
+```
+
+```json
+{
+  "keyName": "qtyWarn",
+  "formatS": "render",
+  "label": "库存预警",
+  "width": 100,
+  "render": "let q = params.row.qty || 0;\nreturn q < (params.row.safeQty || 0) ? '不足' : '正常';"
+}
+```
+
+```json
+{
+  "keyName": "_createBy",
+  "label": "创建人",
+  "width": 100
+}
+```
+
+### 3.2 操作列
+
+操作列（`a-link` / `button` / `dropdown`）**默认 `sortable: false`、`filterable: false`**，无需在 JSON 中重复声明；若需开启，可显式写 `"sortable": true` 或 `"filterable": true`。
+
+```json
+{
+  "type": "a-link",
+  "label": "查看",
+  "width": 100,
+  "options": {
+    "onClick": "let p = this.tableParam;\nthis.getParentTarget().openDetailDialog(p.row);"
+  }
+}
+```
+
+```json
+{
+  "type": "button",
+  "label": "同步",
+  "width": 100,
+  "options": {
+    "type": "primary",
+    "onClick": "let p = this.tableParam;\nthis.getParentTarget().syncLine(p.row);"
+  }
+}
+```
+
+多个操作用 `dropdown`，`dropdownItems` 写列顶层：
+
+```json
+{
+  "type": "dropdown",
+  "label": "操作",
+  "width": 100,
+  "dropdownItems": [
+    {
+      "label": "复制",
+      "onClick": "let p = this.tableParam;\nthis.getParentTarget().copyRow(p.row);"
+    },
+    {
+      "label": "删除",
+      "onClick": "let p = this.tableParam;\nthis.getParentTarget().deleteRow(p.row, p.rowIndex);"
+    }
+  ]
+}
+```
+
+| 字段 | 位置 | 说明 |
+|------|------|------|
+| `label` | **顶层** | 按钮/链接/下拉触发文字 |
+| `onClick` | `options` | 点击脚本（a-link / button） |
+| `dropdownItems` | **顶层** | 下拉菜单项（必填） |
+| `dropdownType` / `dropdownTrigger` | `options` | 下拉样式，**可选**；不传 `options` 时默认 `dropdownType: link`、`dropdownTrigger: hover` |
+
+### 3.3 多级表头
+
+```json
+{
+  "label": "价格信息",
+  "children": [
+    {
+      "type": "number",
+      "keyName": "unitPrice",
+      "label": "单价",
+      "width": 100,
+      "options": { "precision": 4 }
+    }
+  ]
+}
+```
+
+---
+
+## 4. 完整综合示例
+
+完整 JSON 与 Java 示例见文档开头 **§0**（含控件列、展示列、多级表头、操作列）。
+
+---
+
+## 5. 动态列模式
+
+| dynamicColumnMode | 行为 |
+|-------------------|------|
+| `append` | 静态列 + 动态列 |
+| `replace` | 仅保留动态列 |
+
+---
+
+## 6. 注意事项
+
+1. **只维护一套控件 options**：改 select/vabsearch 等配置时，只改主文档 §3。
+2. **`keyName` 为唯一绑定名**。
+3. **行数据键名一致**：`keyName` 须与 `formModel[taBm][i][keyName]` 一致。
+4. **字段级属性写顶层**：`required`、`readonly`、`disabled`、`hidden`、`defaultValue`、`placeholder` 写在列/字段顶层；`options` 只放控件扩展（如 `min`、`onClick`、`searchDialogConfig`）。操作列 `label`、`dropdownItems` 也写顶层。
+5. **列对齐 / 排序 / 筛选**：`align`、操作列 `sortable`/`filterable` 等由前端默认，见主文档 **§2.0** 及本文 **§3.2**。
+6. **动态规则**：显隐/必填等走「表单设置 → 动态字段规则」。
+7. **脚本字符串**：`formScriptParam` 等为 JS 字符串，表单数据用 `this.formModel`，行数据用 `this.tableParam.row`。
+
+---
+
+## 7. 相关文件
+
+| 文件 | 说明 |
+|------|------|
+| [`后台字段（动态生成）JSON 说明.md`](./后台字段（动态生成）JSON%20说明.md) | **协议主文档**（控件类型、options、Java） |
+| `utils/dynamicSchemaUtil.js` | 协议常量与规范化 |
+| `form-render/container-item/data-table-mixin.js` | 动态列运行时 |