weaver-e10-builder 1.5.16 → 1.6.4

package/skill-docs/references/coding/guide-edit-backfill.md

@@ -1,189 +1,141 @@
 # 编辑回显指南
 
-编辑已有数据时，需要将表单数据加载回表单控件中。`getSimpleData` 对特殊类型统一返回 ID，可直接用于表单回显，但选择器组件需要额外提取 name 信息。
+编辑已有数据时，`formClient` 返回的行已经把「写入值」「显示名」「选择器对象」分好了，不需要再同时拉 `getSimpleData` 和 `getAllData`。
 
 ---
 
-## 核心流程
-
-### 第一步：加载时同时获取两份数据
+## 一、行里有什么
 
 ```js
-// loadData 中用 Promise.all 同时获取两份数据
-function loadData() {
-  Promise.all([
-    getSimpleData(OBJ_ID, USER_ID),
-    getAllData(OBJ_ID, USER_ID),
-  ]).then(function ([simpleRows, allRows]) {
-    setData(withDisplayNames(simpleRows, statusMap));
-    setRawData(allRows);  // 保存原始数据用于编辑回显
-  });
+{
+  id: '数据ID',
+  values:  { 字段ID: '写入用的值/ID' },
+  display: { 字段ID: '展示用名称' },
+  items:   { 字段ID: [{ id, name }] },
+  details: { [DETAIL_SUB_FORM_ID]: [...] },
+  raw: 平台原始行
 }
 ```
 
-### 第二步：编辑按钮点击时回填表单
+| 回填目标 | 取哪里 |
+|---|---|
+| 文本框、数字、日期、下拉框 | `values` |
+| 只读展示、表格列 | `display` |
+| 人员 / 部门 Browser | `items` |
+| Upload 附件 | `items`（`id` 映射成 `fileid`） |
+| 明细表 | `detailRows[subFormId]` 的 `values` |
 
-```js
-function handleEdit(rowData) {
-  var dataId = rowData._raw.id;  // Table 回调的 rowData 有 _raw，不是 getSimpleData 返回的行
-
-  // 1. 从 rawData(原始接口数据) 中查找对应记录
-  var rawEntry = rawData.find(function (r) {
-    return r.mainTable && r.mainTable.id && r.mainTable.id.fieldValue === dataId;
-  });
+---
 
-  // 2. 用 getSimpleData 的值填充表单（所有特殊字段已是 ID，可直接用）
-  var editForm = {};
-  Object.keys(emptyForm).forEach(function (key) {
-    editForm[key] = rowData._raw[key] || '';
-  });
+## 二、打开编辑
 
-  // 3. 从 rawEntry.mainTable 中提取 name 信息（选择器组件需要 [{id, name}] 格式）
-  var newSelectedPerson = [];
-  var newSelectedDept = [];
-  var newUploadedFiles = [];
-
-  if (rawEntry && rawEntry.mainTable) {
-    Object.keys(rawEntry.mainTable).forEach(function (key) {
-      var val = rawEntry.mainTable[key];
-      if (!val) return;
-
-      if (Array.isArray(val) && val.length > 0) {
-        var fieldId = val[0].fieldId;
-        var fieldType = val[0].fieldType;
-
-        if (fieldId === F.person) {
-          newSelectedPerson = val.map(function (v) {
-            return { id: v.fieldOptionId, name: v.fieldOptionName };
-          });
-        } else if (fieldId === F.dept) {
-          newSelectedDept = val.map(function (v) {
-            return { id: v.fieldOptionId, name: v.fieldOptionName };
-          });
-        } else if (fieldId === F.attachment) {
-          newUploadedFiles = val.map(function (v) {
-            return { fileid: v.fieldOptionId, name: v.fieldOptionName };
-          });
-        } else if (fieldType === 'Select' || fieldType === 'RadioBox' || fieldType === 'CheckBox') {
-          // getSimpleData 已返回 ID，此处从 rawEntry 再次确认（多选时覆盖）
-          editForm[fieldId] = val.map(function (v) { return v.fieldOptionId; }).join(',');
-        }
-      }
-    });
-  }
-
-  // 4. 一次性设置所有状态
-  setForm(editForm);
-  setSelectedPerson(newSelectedPerson);
-  setSelectedDept(newSelectedDept);
-  setUploadedFiles(newUploadedFiles);
+```js
+function handleEdit(row) {
+  setEditingId(row.id);
+  setForm(Object.assign({}, row.values));
+  setSelectedPerson(row.items[F.owner] || []);
+  setSelectedDept(row.items[F.dept] || []);
+  setUploadedFiles((row.items[F.attachment] || []).map(function (item) {
+    return { fileid: item.id, name: item.name };
+  }));
   setModalVisible(true);
 }
 ```
 
----
+关键点：
+
+- `row.values` 直接作为表单初始值，特殊字段已经是 ID。
+- 人员 / 部门 Browser 的 `value` 需要 `[{ id, name }]`，直接用 `row.items[字段ID]`。
+- Upload 的 `data` 需要 `[{ fileid, name }]`，把 `items` 的 `id` 改名为 `fileid`。
+- 不要从 `row.raw.mainTable` 里自己找字段；`raw` 只用于平台原始报文排查。
+- 不要用 `display` 回填表单，否则保存时会把中文名写回 ID 字段。
 
-## 关键点总结
+明细回显：
+
+```js
+var detail = (row.detailRows && row.detailRows[DETAIL_SUB_FORM_ID]) || [];
+setDetailRows(detail.map(function (line) {
+  return Object.assign({}, line.values);
+}));
+```
 
-| 要点 | 说明 |
-|------|------|
-| `getAllData` 返回结构中 `id` 在 `mainTable` 内部 | 查找原始记录必须是 `r.mainTable.id.fieldValue`，**不能**写成 `r.id.fieldValue` |
-| `Browser`(人员/部门) 的 `value` | 需要 `[{id, name}]` 格式 |
-| `Upload`(附件) 的 `data` | 需要 `[{fileid, name}]` 格式 |
-| `Select` 下拉框的 `value` | 需要匹配 `fieldOptionId`（即 `opt.valueKey`），不能是显示名 |
-| Table 的 `onRowClick` 回调 | `rowData._raw` 引用了原始数据行，`rowData._raw.id` 是 dataId |
-| 表单字段值来源 | 从 `getSimpleData` 取值（已是 ID），选择器显示名从 `getAllData` 提取 |
+保存时把 `detailRows` 放回 `details[DETAIL_SUB_FORM_ID]`，编辑整表用 `detailMode: 'cover'`。
 
 ---
 
-## getSimpleData vs getAllData 结构对比
+## 三、新增
 
-### getSimpleData 返回（扁平，纯 ID，用于写入）
+新增时构造空表单：
 
-```json
-[
-  {
-    "1290462231772995585": "张三",                   // Text：直接就是值
-    "1290462231772995586": "1290462231772995612",    // Select：选项 ID
-    "1290462231772995589": "2765550234448235905",    // Employee：用户 ID
-    "id": "1290469928435908609"
-  }
-]
+```js
+var EMPTY = {};
+Object.keys(F).forEach(function (key) {
+  EMPTY[F[key]] = '';
+});
+
+setEditingId('');
+setForm(Object.assign({}, EMPTY));
+setSelectedPerson([]);
+setSelectedDept([]);
+setUploadedFiles([]);
 ```
 
-所有特殊字段统一返回 `fieldOptionId`（纯 ID），直接用于 `formToSave`。
+---
 
-### getAllData 返回（含名称，用于展示/回显）
+## 四、只有 dataId 时怎么回显
 
-```json
-{
-  "mainTable": {
-    "sjhfa391": {                                     // ← key 是随机哈希，不是 fieldId！
-      "fieldId": "1290462231772995590",
-      "fieldType": "Text",
-      "fieldValue": "13800138000"
-    },
-    "zssj98f9d": [{                                   // ← Employee 是数组！
-      "fieldId": "1290462231772995589",
-      "fieldType": "Employee",
-      "fieldOptionId": "2765550234448235905",
-      "fieldOptionName": "张三"
-    }],
-    "bm1d630": [{                                     // ← Select 也是数组！
-      "fieldId": "1290462231772995586",
-      "fieldType": "Select",
-      "fieldOptionId": "1290462231772995612",
-      "fieldOptionName": "技术部"
-    }],
-    "id": {                                           // ← 只有 id 的 key 是 "id"
-      "fieldId": "5",
-      "fieldType": "Text",
-      "fieldValue": "1290469928435908609"
-    }
-  }
-}
+如果页面是从 URL / 路由拿到 `dataId`，不要先拉全表再找：
+
+```js
+useEffect(function () {
+  if (!dataId) return;
+  items.get(dataId, { withDetail: true }).then(function (row) {
+    if (!row) return;
+    handleEdit(row);
+  }).catch(function (err) {
+    setError(err.message);
+  });
+}, [dataId]);
 ```
 
-### 三个关键规则
+列表页已经有行对象时，直接把 `row` 传给 `handleEdit`，不要重复请求。
 
-| 规则 | 说明 |
-|------|------|
-| **key 是随机哈希** | `mainTable` 的 key（如 `sjhfa391`）是随机字符串，**不能**用 `mainTable[fieldId]` 直接取值 |
-| **只能用 fieldId 匹配** | 必须遍历 `Object.values(mainTable)`，通过 `val.fieldId` 或 `val[0].fieldId` 匹配目标字段 |
-| **数组 vs 对象** | Employee / Select / FileComponent / RadioBox / CheckBox → **数组** `[{...}]`；Text / Number / DateComponent → **对象** `{...}` |
-| **只有 id 是 deterministic** | 数据行 ID 的 key 固定为 `"id"`，可直接用 `mainTable.id.fieldValue` |
+---
 
-### 字段值 → 组件 props 映射表
+## 五、字段类型映射
 
-> 这是整个编辑回显最容易出错的一步。getAllData 中的字段形状各不相同，映射到组件 props 的方式也不同。
+| 字段类型 | `values` | 回填组件 | 组件需要的值 |
+|---|---|---|---|
+| Text / TextArea / Number / Date | 字符串/数字 | 原生 input / textarea | 直接用 |
+| Select / RadioBox / CheckBox | 选项 ID；多选逗号串 | 原生 select 或多选控件 | 单选取 ID；多选按逗号拆或使用对应组件 |
+| Employee / Department | ID；多值逗号串 | `Browser` | `row.items[fieldId]` → `[{id,name}]` |
+| FileComponent | 文件 ID 串 | `Upload` | `row.items[fieldId]` → `[{fileid,id 改名,name}]` |
+| Ebuilder / Browser / RelateBrowser | 关联数据 ID | 关联浏览组件 | `row.items[fieldId]` → `[{id,name}]` |
 
-| 字段类型 | getAllData 中的形状 | 目标组件 | 需要的 props 格式 | 映射方式 |
-|---------|-------------------|---------|-----------------|---------|
-| Employee | `[{fieldOptionId, fieldOptionName}]` | `Browser` | `value={[{id, name}]}` | `v.fieldOptionId → id`，`v.fieldOptionName → name` |
-| Department | `[{fieldOptionId, fieldOptionName}]` | `Browser` | `value={[{id, name}]}` | 同上 |
-| FileComponent | `[{fieldOptionId, fieldOptionName}]` | `Upload` | `data={[{fileid, name}]}` | `v.fieldOptionId → fileid`，`v.fieldOptionName → name` |
-| Select（单选） | `[{fieldOptionId}]` | `<select>` | `value="fieldOptionId"` | 取 `val[0].fieldOptionId` |
-| Select（多选） | `[{...}, {...}]` → 多个 | `<select multiple>` | 逗号分隔串 | `val.map(...).join(',')` |
-| Text / Number | `{fieldValue}` | `<input>` | `value="fieldValue"` | 直接用 `getSimpleData` 的值 |
+---
 
-### 正确的字段提取方式
+## 六、保存
 
 ```js
-// 查找 mainTable 中 fieldId 匹配的字段值
-function findField(mainTable, targetFieldId) {
-  var keys = Object.keys(mainTable);
-  for (var i = 0; i < keys.length; i++) {
-    var val = mainTable[keys[i]];
-    if (!val) continue;
-    // 数组类型（Employee/Select 等）取 val[0].fieldId
-    if (Array.isArray(val) && val.length > 0 && val[0].fieldId === targetFieldId) {
-      return val;
-    }
-    // 普通类型（Text/DateComponent 等）取 val.fieldId
-    if (!Array.isArray(val) && val.fieldId === targetFieldId) {
-      return val;
-    }
-  }
-  return null;
+if (editingId) {
+  await items.update(editingId, form);
+} else {
+  var newId = await items.save(form);
 }
 ```
+
+- 只传需要修改的字段；字段联动依赖完整值时传整行 `row.values`。
+- 保存成功后重新 `items.list()` 刷新列表。
+- 保存失败要展示 `err.message`。
+
+---
+
+## 七、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|---|---|---|
+| 用 `row.display[字段]` 回填 form | 保存时把中文名写进 ID 字段 | 用 `row.values[字段]` |
+| 从 `row.raw.mainTable` 自己找字段 | 随机 key、数组/对象形状判断错 | 用 `values` / `display` / `items` |
+| 人员选择器传字符串 ID | 组件显示数字或不显示 | 传 `[{id,name}]` |
+| Upload 直接传 `items` | 组件读不到 `fileid` | 映射成 `{fileid:id,name}` |
+| 列表已有行还调 `items.get` | 多一次请求 | 直接复用 `row` |