weaver-e10-builder 1.5.16 → 1.6.4

package/skill-docs/references/form/layout/code-block/recipes.md

@@ -0,0 +1,164 @@
+# 按效果查代码模式
+
+本页覆盖原案例中的独立做法。字段 Key、接口和字段对象均需替换为目标表单真实数据；示例中出现的模拟接口、固定附件对象和测试 ID 不能作为正式值。
+
+| 想要的效果 | 组合方法 | 关键检查 |
+|---|---|---|
+| 保存前汇总明细人员到主表并去重 | `registerCheckEvent(OPER_SAVE)` → `getDetailAllRowIndexStr` → 逐行 `getBrowserOptionEntity` → 按 id 去重 → `changeFieldValue(...,{specialObj})` → `successFn` | 空行、重复人员、失败回调；仅拦表单保存 |
+| 附件字段回填且可预览 | 从附件模块/现有字段取完整对象 → `changeFieldValue(...,{specialObj:[{id,name,data,type:'file'}]})` | 文件权限、预览/下载入口；不可只传 id/name |
+| 多级选项等复杂值赋值 | 先 `getFieldObj` 观察已有对象 → 按 `data.content` 或 `data.dataOptions` 等原结构写 `specialObj` | 选项模板、次级选项正确显示 |
+| 将明细富文本显示为按钮或链接 | `getDetailAllRowIndexStr` 遍历每行 → `proxyFieldComp` 替换该行内容；添加行事件补新行 | 点击跳转地址与作用范围 |
+| 按两个维度分类、累加到另一明细表 | `getDetailData` 建组合 Key → 对目标行更新/新增/删除 → 监听来源值变化和增删行 | 组合 Key 唯一、消失分组删除、重复事件 |
+| 全表单跨模块识别字段并回填外部数据 | 全局 ecode `onFormReady` 取当前实例并限制 module/formId → 字段事件 → 调受支持接口 → `changeMoreField` | 权限、数据范围、主表/明细位置、失败与清空逻辑 |
+| 明细数字合计并算各行占比 | 读取明细每行数值 → `reduce` 求和 → 主表回写 → 逐行占比赋值；监听值变化及增删行 | 空值、非数字、总额 0、精度 |
+| 联动带出后再汇总并触发后续联动 | 对带出字段监听联动 scope → 汇总 → 写主表 → 必要时 `triggerFieldAllLinkage` | 避免循环；确认事件是否实际触发 |
+| 合并多个主表浏览/选项字段 | 多字段 `getBrowserOptionEntity` → 合并或按 id 去重 → 主表 `specialObj` 赋值 | 是否保留重复项、空字段 |
+| 按同行条件选择明细人员合并到主表 | `getDetailData` → 判断同行选项值 → 取人员对象 → 去重 → `changeFieldValue` | 条件变化、增删行后重算 |
+| 子明细按父行汇总金额 | 父、子关系字段匹配 → 筛子表数据 → 合计 → 回写父表指定 `rowId` | 父标识唯一、子行归属、父行删除后的处理 |
+| 按显示序号生成明细值 | 明细行数组按显示顺序 `map((row,index)=>...)` → `changeDetailData`；监听增删行 | 排序后重新计算，避免把序号当 rowId |
+| 某字段为空时触发另一字段联动 | `getFieldValue` 判空 → `triggerFieldAllLinkage(target)`；载入与源字段变化均执行 | 空字符串、0 与未选择的判定 |
+| 自定义页面参数传递/组件换肤 | 全局 ecode `regOvProps` 或表单字段 `proxyFieldContentComp`，按生效范围选择 | 组件名/props 契约、编译入口 |
+
+上述模式涉及的完整 API、参数与风险分别见 [事件](events-validation.md)、[字段](foundations-fields.md)、[明细](details.md)、[控件](controls.md) 和 [组件交互](ui-global.md)。原案例存在重复与少量不完整代码：例如重复的“保存前汇总人员”，附件数据依赖文档模块，组件 props 示例有语法笔误，数字合计示例用 `eval`，全局回填示例包含模拟数据。这里保留其实现思路，代码应按专题中可运行的结构重新组装。
+
+## 保存前汇总明细人员并去重
+
+先定位明细、明细人员字段和主表目标字段；仅在表单数据保存前执行。需要流程“提交”时改用流程 SDK 的节点提交事件。
+
+```js
+const table = formSdk.convertFieldNameToId('people_detail', 'main');
+const detailPerson = formSdk.convertFieldNameToId('person', table);
+const mainPeople = formSdk.convertFieldNameToId('all_people', 'main');
+formSdk.registerCheckEvent(window.WeFormSDK.OPER_SAVE, (ok, stop) => {
+  try {
+    const rowIds = (formSdk.getDetailAllRowIndexStr(table) || '').split(',').filter(Boolean);
+    const unique = new Map();
+    for (const rowId of rowIds) {
+      for (const item of formSdk.getBrowserOptionEntity(`${detailPerson}_${rowId}`) || []) {
+        if (item?.id) unique.set(String(item.id), item);
+      }
+    }
+    formSdk.changeFieldValue(mainPeople, {specialObj: [...unique.values()]});
+    ok();
+  } catch (error) {
+    stop({msg: '人员汇总失败，请检查明细数据'});
+  }
+});
+```
+
+## 明细数值汇总并计算占比
+
+值变化、增行、删行和初次载入都要重新计算；`getDetailData` 的每行包含 `rowId`。示例以数值 0 处理空值，业务若要求空值报错，应另作校验。
+
+```js
+const table = formSdk.convertFieldNameToId('cost_detail', 'main');
+const detailAmount = formSdk.convertFieldNameToId('amount', table);
+const detailShare = formSdk.convertFieldNameToId('share', table);
+const mainTotal = formSdk.convertFieldNameToId('total', 'main');
+function recalculate() {
+  const rows = formSdk.getDetailData(table) || [];
+  const total = rows.reduce((sum, row) => sum + Number(row[detailAmount]?.value || 0), 0);
+  formSdk.changeFieldValue(mainTotal, {value: String(total)}, {jsApiChange: false});
+  for (const row of rows) {
+    const amount = Number(row[detailAmount]?.value || 0);
+    formSdk.changeFieldValue(`${detailShare}_${row.rowId}`, {value: String(total ? amount / total : 0)}, {jsApiChange: false});
+  }
+}
+formSdk.bindFieldChangeEvent(detailAmount, recalculate);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_ADDROW}${table}`, recalculate);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_DELROW}${table}`, recalculate);
+recalculate();
+```
+
+如汇总源值本身来自字段联动，普通字段变化事件可能不触发；依目标基线使用 `scope: window.WeFormSDK.CHANGE_EVENT_LINKAGE` 或监听 `ACTION_DATA_LINKAGE`。占比输出为 0～1 还是 0～100，须按目标字段的百分比显示方式确定。不要直接打开全局联动事件开关而不检查既有监听是否形成循环。
+
+## 父子明细按关系字段回写
+
+父、子明细的关系字段值相同才能归属同一父行。先配置真实二级明细关系，再对每个父行筛选对应子行。这里的业务主键与 `rowId` 分开。
+
+```js
+const parentTable = formSdk.convertFieldNameToId('parent_detail', 'main');
+const childTable = formSdk.convertFieldNameToId('child_detail', 'main');
+const parentKey = formSdk.convertFieldNameToId('parent_key', parentTable);
+const parentTotal = formSdk.convertFieldNameToId('parent_total', parentTable);
+const childKey = formSdk.convertFieldNameToId('child_parent_key', childTable);
+const childAmount = formSdk.convertFieldNameToId('child_amount', childTable);
+function recalculateParents() {
+  const children = formSdk.getDetailData(childTable) || [];
+  for (const parent of formSdk.getDetailData(parentTable) || []) {
+    const key = parent[parentKey]?.value;
+    const total = children.filter(row => row[childKey]?.value === key)
+      .reduce((sum, row) => sum + Number(row[childAmount]?.value || 0), 0);
+    formSdk.changeFieldValue(`${parentTotal}_${parent.rowId}`, {value: String(total)}, {jsApiChange: false});
+  }
+}
+formSdk.bindFieldChangeEvent(childAmount, recalculateParents);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_ADDROW}${childTable}`, recalculateParents);
+formSdk.registerAction(`${window.WeFormSDK.ACTION_DELROW}${childTable}`, recalculateParents);
+recalculateParents();
+```
+
+关系字段若为选项而非文本，按 `getFieldObj` 的 `specialObj` 比较 ID。父行标识必须唯一；删除父行后的子行处置应由业务规则明确。用 `getDetailData` 复制子行时不要复制旧 `rowId`。
+
+## 来源明细按两列分组，同步到目标明细
+
+来源中按“部门 ID + 类型 ID”分组求和；目标中已有分组更新、缺失分组新增、来源已消失的分组删除。监听来源的两列条件字段、数值字段与增删行事件。下面只展示同步函数，绑定方式同上方汇总案例。
+
+```js
+function syncGroups(sourceTable, targetTable, sourceDept, sourceType, sourceAmount,
+                    targetDept, targetType, targetAmount) {
+  const groups = new Map();
+  for (const row of formSdk.getDetailData(sourceTable) || []) {
+    const dept = row[sourceDept]?.specialObj?.[0];
+    const type = row[sourceType]?.specialObj?.[0];
+    if (!dept?.id || !type?.id) continue;
+    const key = `${dept.id}:${type.id}`;
+    const item = groups.get(key) || {dept, type, total: 0};
+    item.total += Number(row[sourceAmount]?.value || 0);
+    groups.set(key, item);
+  }
+  const existing = new Map();
+  for (const row of formSdk.getDetailData(targetTable) || []) {
+    const deptId = row[targetDept]?.specialObj?.[0]?.id;
+    const typeId = row[targetType]?.specialObj?.[0]?.id;
+    if (!deptId || !typeId || !groups.has(`${deptId}:${typeId}`)) {
+      formSdk.delDetailRow(targetTable, row.rowId);
+    } else {
+      existing.set(`${deptId}:${typeId}`, row.rowId);
+    }
+  }
+  for (const [key, item] of groups) {
+    const rowId = existing.get(key);
+    if (rowId) {
+      formSdk.changeFieldValue(`${targetAmount}_${rowId}`, {value: String(item.total)}, {jsApiChange: false});
+    } else {
+      formSdk.addDetailRow(targetTable, {
+        [targetDept]: {specialObj: [item.dept]},
+        [targetType]: {specialObj: [item.type]},
+        [targetAmount]: {value: String(item.total)}
+      });
+    }
+  }
+}
+```
+
+这种同步会删除目标中无来源的行，只有目标表完全由来源派生时才适用；若允许用户手工维护目标行，应改为保留手工行并有明确的来源标识。跨字段 `id` 类型与数值精度须按实际表单处理。
+
+## 根据明细同行条件筛人员，合并到主表
+
+对每行读取条件选项，按不同条件分别取对应人员字段，再按人员 ID 去重并写入主表。初次载入、条件/人员字段变化、明细增删行均重新执行。
+
+```js
+function syncPeople(table, conditionField, firstPeopleField, secondPeopleField, mainPeopleField) {
+  const people = new Map();
+  for (const row of formSdk.getDetailData(table) || []) {
+    const choice = row[conditionField]?.specialObj?.[0]?.id;
+    const selected = choice === '0' ? row[firstPeopleField]?.specialObj :
+      choice === '1' ? row[secondPeopleField]?.specialObj : [];
+    for (const person of selected || []) if (person?.id) people.set(String(person.id), person);
+  }
+  formSdk.changeFieldValue(mainPeopleField, {specialObj: [...people.values()]}, {jsApiChange: false});
+}
+```
+
+条件选项 ID `'0'/'1'` 是示例占位，须读取真实选项 ID。若人员字段由系统联动带出，还要按[事件指南](events-validation.md)监听联动完成事件。

package/skill-docs/references/form/layout/code-block/troubleshooting.md

@@ -0,0 +1,49 @@
+# JSSDK 排查、版本与边界
+
+## 代码不生效时
+
+1. 确认保存的是目标表单的目标布局及目标终端，或正确的表单级/全局 ecode；JS 编译通过且代码已启用，CSS 单独保存。浏览器打开的是最新布局而非另一设备布局。
+2. 确认 `formSdk` 取自当前表单实例；全局 ecode 用 `onFormReady` 的事件实例并限定 formId/module。较早基线的 `pageSdk.on('formReady')` 与新基线闭包方式不要混用到未支持的入口。
+3. 用 `getBaseInfo`、`convertFieldNameToId`、`getFieldInfo` 检查当前表单和字段；数据 Key 不是字段名或物理表名。明细字段要指定明细表位置，行操作要取得真实 `rowId`。
+4. 用 `getFieldObj` 对照目标类型的数据形状。文本/数字/日期常用 `{value}`；浏览/动态选项/附件常用 `{specialObj}`。附件预览还依赖完整 `data`。
+5. 检查事件是否属于“表单保存”“流程提交”“用户改变”“联动改变”中的哪一种；必要时分开绑定。拦截回调必须调用通过或阻断函数；异步超时约 25 秒。
+6. 检查权限和组件边界。流程节点默认只读或权限锁定的字段，不能仅靠 `changeFieldAttr(2)` 放开；JS 渲染也不改变后端权限。
+
+开发调试时可按环境入口临时屏蔽不同层级二开：ecode 平台、全局初始化代码、布局源码对应不同入口。调试开关仅用于定位，不作为正式配置。对含多表单、父子页面、明细新行的场景，还要检查实例、`postMessage` 来源与渲染时机。
+
+## 设计器源码面板为空 / ECode decode failed
+
+- **症状**：打开布局源码时控制台报 `ECode decode failed, SyntaxError: Expected ':' after property name in JSON at position 5`，源码面板为空，预览按钮失效。
+- **原因**：`sourceCode.ecode` 被 `encodeURIComponent` 写入。设计器用 `JSON.parse(decodeURI(ecode))` 读取，而 `decodeURI` 不还原 `%3A`（冒号），JSON 变成 `{"js"%3A...}`。
+- **处理**：用 `form code layout set` / `wf-form code layout set` 重新写入（CLI 已使用 `encodeURI`，并在写入前、回读后按设计器路径自检）。临时恢复可把 `sourceCode.ecode` 置为空字符串，再用空 JS/CSS 文件重写。
+- **手工调接口**：必须用 `encodeURI(JSON.stringify({js, css}))`，不要用 `encodeURIComponent`。
+
+## 基线速查
+
+| 功能 | 原技术资料标注的最低基线 |
+|---|---|
+| `changeFieldValue` 的联动控制参数 | 241001 |
+| `valueInfo.type/contentObj` 特殊字段 | 241201 |
+| 字段联动拦截及联动动作的 `runData` | 240601 |
+| 字段变化事件的联动 `scope` | 250401；明细专用事件的扩展参数 250901 |
+| 明细批量添加 `addDetailData` | 241201 |
+| 布局/表单代码直接取得当前 `formSdk` | 主体说明标注 250101；另有一处写 241201，稳妥按 250101 判断 |
+| 明细批量更新 `changeDetailData` | 250101 |
+| `changeTabItemAttr` | 20250501 |
+| `controlOptionDisable` | 20250501 |
+| `convertFieldNameToId` 用明细表数据 Key 定位明细字段 | 260601 |
+| `getDetailData` 按当前明细筛选条件取数 | 260401 |
+| `triggerFieldAllLinkage(...).then(...)` | 250901 |
+| 联动赋值导致的明细行变化事件扩展 | 251101 |
+| `pluginGet/pluginExecute` | 260201 |
+
+先确认目标环境版本和实际 API 可用性；未达到基线时不要假设同名功能可用。
+
+## 原案例中需纠正的写法
+
+- 字段赋值示例声明 `textFieldMark` 后却调用 `fieldMark`，日期示例声明 `dateFieldMark` 后调用 `selectFieldMark`；按真正声明的目标字段写。
+- 字段属性示例的明细行模板字符串缺少引号闭合；正确形式为 `` `${detailField}_${rowId}` ``。
+- `getFieldCom` 章节示例调用了 `getFieldInfo`；两者用途不同，前者为组件引用，后者为字段信息。
+- 明细“默认使用末行”章节的示例实际调用 `setDetailAddUseCopy`；先确认所需是复制末行，而非仅控制默认光标或位置。
+- 案例中的 `eval(numbers.join('+'))`、测试 URL、固定附件元数据、模拟外部查询结果不能直接用于业务配置。数值合计用显式转换与 `reduce`，外部接口须有真实契约。
+- 全局 ecode 的 `import`、JSX、`regOvProps` 示例不要直接粘入布局源码；按目标编辑器支持的语法重写。布局源码中的局部字段组件复写则按其 API 单独处理。

package/skill-docs/references/form/layout/code-block/ui-global.md

@@ -0,0 +1,47 @@
+# 组件渲染、全局交互与扩展
+
+## 当前表单与全局操作
+
+`formSdk.getBaseInfo()` 读取当前表单基本信息；`formSdk.isMobile()` 判断移动端。布局级代码优先使用当前作用域 `formSdk`；提示、弹窗由全局 `window.WeFormSDK` 提供。
+
+| 效果 | API 与要点 |
+|---|---|
+| 提示 | `window.WeFormSDK.showMessage(message, type?, duration?)`；type 为 `1` 警告、`2` 错误、`3` 成功；时长单位秒 |
+| 确认 | `window.WeFormSDK.showConfirm(content, onOk, onCancel?, {title,okText,cancelText}?)`；title 仅 PC 有效 |
+| 自定义弹窗 | `window.WeFormSDK.openCustomDialog({content,width,height,onOk,onCancel,footer?,...})`；返回对象可 `destroy()` |
+| 页面刷新 | `formSdk.reloadPage(params?)` |
+| 提交附加参数 | `formSdk.appendSubmitParam({customParam:{...}})`；接收端仍须能处理该参数 |
+| 主动做必填检查 | `formSdk.verifyFormRequired(mustAddDetail?,fieldRequired?)` |
+| 全局加载 | `window.WeFormSDK.getLoadingGlobal()` 取加载控件，调用 `start()`、`end()`、`destroy()` |
+| 关闭页面提示 | `formSdk.setFormTipCloseStatus(true/false)`；只控制提示状态，不执行保存 |
+
+自定义 footer 使用 `@weapp/ui` 的 import/JSX 是 ecode 构建环境示例；布局源码只允许其编辑器可编译的语法和已暴露对象，不能直接套用 ecode 依赖。
+
+## 字段区域事件和局部渲染
+
+`bindFieldAction(type, fields, handler)` 绑定失焦、聚焦、点击、双击、移入/移出；事件类型为 `onblur/onfocus/onclick/ondbclick/mouseover/mouseout`。
+
+| 需求 | API |
+|---|---|
+| 将当前字段内容替换为自定义内容 | `proxyFieldComp(fieldMark, reactNode或文本, range?)` |
+| 在字段后追加内容 | `afterFieldComp(fieldMark, reactNode或文本, range?)` |
+| 用函数包装原字段内容并利用 props 决定样式 | `proxyFieldContentComp(fieldMark, (props, componentFn) => React.createElement(..., componentFn()))` |
+
+`range` 省略时作用于全部读写状态；`'1'` 只读、`'2'` 可编辑、`'3'` 必填，多个值以逗号分隔。`proxyFieldContentComp` 的回调必须返回组件，第二参数 `componentFn` 可生成原字段内容。`React` 可用性和编译语法要以目标代码入口为准。明细字段不加行 ID 可作用于整列，指定行则加 `_rowId`；新添行的专门逻辑应在添加行事件后检查是否生效。此能力是当前表单字段的局部渲染，不等于发布平台级新组件，也不等于改写后端接口。
+
+```js
+const field = formSdk.convertFieldNameToId('status', 'main');
+formSdk.proxyFieldContentComp(field, (props, original) =>
+  React.createElement('div', {style: {backgroundColor: props?.widgetValue?.content === '1' ? '#e3f2fd' : ''}}, original())
+);
+```
+
+## 插件与页面间通信
+
+260201 及以后基线提供 `formSdk.pluginGet(fieldMark, property)` 和 `formSdk.pluginExecute(fieldMark, method, ...args)`；只能操作该插件实际公开的属性/方法。具体 WPS 或其他插件须取得该插件契约，不能从 JSSDK 通用接口推断方法名。
+
+`window.open` 打开的子页面可通过 `window.opener` 访问父窗口；同源时可操作父页面的表单实例。跨源时用 `postMessage`，接收方检查 `event.origin` 和 `event.data.type`，发送方指定目标 origin；只发送必要数据，不传鉴权信息。
+
+子表控件数据变化后，如需刷新相关显示，布局源码中可调用 `pageSdk.events.emit('field.change', '纯数字字段ID')`；ecode 中可调用 `window.ebuilderSDK.getPageSDK().events.emit('field.change', '纯数字字段ID')`。原资料还提到可附第三个字段数据参数：文本传文本，浏览型传以逗号分隔的 ID；按实际刷新需求决定是否传值。此处第二参数是纯数字字段 ID，不是带 `field` 前缀的标识。
+
+全局 ecode 的 `regOvProps` 可复写特定组件 props，但其包名与目标组件名是项目级契约；它和布局内 `proxyFieldContentComp` 是不同层级。采用哪一层，应以所需生效范围为准。

package/skill-docs/references/form/layout/document.md

@@ -0,0 +1,39 @@
+# 完整布局文档编辑
+
+大范围调整同一布局中的网格、组件、页面样式或代码块时，先导出完整布局文档，再编辑其 `formLayout`，预览完整差异后应用。局部修改行高、列宽、已有单元格样式或单个字段位置时，优先使用[布局规划与局部编辑](planning.md)中的 `layout diff/edit`。
+
+## 导出可编辑底稿
+
+```bash
+e10-cli form layout document export <objId> --out layout-document.json
+e10-cli form layout document export <objId> --view-id <布局ID> --out layout-document.json
+e10-cli form layout document export <流程表单formId> --module workflow --id-type form --out layout-document.json
+```
+
+文档外层记录 `schemaVersion`、目标、环境、布局快照指纹和字段指纹；`formLayout` 是原生布局完整内容，包含页面组件、workbook、`formStyle` 以及页面 `sourceCode`。只编辑 `formLayout` 内所需部分，保留文档外层身份信息。布局 ID、页面 ID、终端、布局类型、创建与版本元数据由平台管理，不应修改。长整数 ID 保持导出时的字符串形式。
+
+该文档只包含布局，不包含可编辑的业务字段或表单主数据。修改字段定义、权限或字段业务属性时使用各自的表单命令。代码块的内容结构见[布局代码块 CSS 指南](code-block/layout-css.md)；编辑 `sourceCode` 时保留其原生编码结构。
+
+## 只读预览完整差异
+
+保存编辑后的 JSON 为独立文件，再运行：
+
+```bash
+e10-cli form layout document diff <objId> --draft @layout-document-draft.json --out layout-document-diff.json
+```
+
+完整报告列出每项 `formLayout` 路径及 `before`、`after`，并检查环境、目标、字段和快照指纹。布局在导出后被他人修改时，重新导出并整理草稿。结构检查覆盖页面身份、组件 ID、字段引用、workbook 的行列范围、单元格与组件坐标、明细网格归属、合并区域和占用关系；修改 `sourceCode.ecode` 时还检查设计器能否解码。`baselineIssues` 是原布局已有问题；`introducedIssues` 是草稿新增问题。只有新增问题会阻断本次差异预览。`canApply` 表示当前静态检查通过，不代表已经保存或能替代具体组件的业务规则验证。
+
+## 应用完整布局文档
+
+核对差异报告后，使用同一份草稿和 `document diff --out` 保存的报告：
+
+```bash
+e10-cli form layout document apply <objId> --draft @layout-document-draft.json --preview @layout-document-diff.json --out layout-document-apply-report.json
+```
+
+命令重新读取布局，核对目标、环境、草稿哈希、字段指纹、布局快照和已审阅差异；任一项变化即停止，需重新导出或预览。无差异时直接返回，不发保存请求。通过校验后只提交一次完整 `formLayout`，保存结果不确定时独立回读，**不重复提交**。
+
+回读报告中，`verifiedChanges` 是逐项确认的草稿变更数；`fullLayoutVerified:true` 表示完整布局与草稿一致（平台自动更新的时间戳和页面版本字段除外）；`saved:true` 表示独立回读通过且业务字段及表单主数据未改变。若某项未持久化，报告会列出 `differences`，不能据保存接口的响应判断成功。恢复原布局也须基于最新快照重新导出、预览并应用。
+
+完整文档可集中修改 `formLayout`，但仍需保持平台管理的身份、版本字段及字段组件关系有效。业务字段的创建、删除和属性修改使用相应表单命令；代码块内容建议用专门的代码块命令生成原生编码，再放入文档。不要将完整文档传给局部调整命令 `layout edit`。

package/skill-docs/references/form/layout/incremental.md

@@ -0,0 +1,133 @@
+# 给已有表单改布局
+
+给已经建好的表单加字段、改字段的显示属性时读这篇。**不是自己建的表尤其要读**：改错了别人的版式，对方要一个个调回来。
+
+## 布局是两套数据
+
+| | 存在哪 | 一条是什么 |
+|---|---|---|
+| **字段定义** | 字段管理接口 | 一个字段一条（`fieldId` / `type` / `componentKey` / `title` / `dataKey` / `columnName` …） |
+| **布局组件** | 表单布局接口的 `pageLayouts[].comps` | **平铺一维数组**，每个字段占**两个**：一个标签组件、一个值组件 |
+
+**判断「这个组件属于哪个字段」只能看 `config.associatedId`。**
+标签组件的 `config.fieldId` 是布局自己另生成的一个 id，与字段定义没有对应关系 —— 拿它去找字段会找不到。
+
+明细字段也在同一个平铺数组里，靠 `config.subFormId` 归属；它的 `excel.parent` 指向明细表容器的 `nodeId`，普通字段的 `excel.parent` 是 `ROOT`。
+
+**EXCEL 布局还有第三份：网格。** `pageLayouts[].config.workbook.Sheet1.cells` 里每个组件占**一格**，靠 `style.cellType.comId` 认到自己的组件，位置也以格子自己的 `row` / `col` 为准 —— **设计器按网格渲染**。所以 EXCEL 表里「组件的 `config.excel.row` / `col`」和「格子的 `row` / `col`」是同一件事的两份副本，**改一份必须改两份**：只改组件层的话接口会回成功，但设计器里画不出来。
+
+FLOW 布局**没有** `config.workbook`（它靠 `config.flow.parent` / `nodes` 排布），这条对它不适用。
+
+> 这份同步由 CLI 负责，不用手工做。但**手工在页面上改过布局的老表**如果在 EXCEL 上有字段显示不出来，在设计器里保存一次即可 —— 设计器会按组件重算网格。
+
+## 字段属性分两类
+
+有些属性**只存在于布局组件里，字段定义没有这个键** —— 只写字段定义等于什么都没做：接口回成功、命令也报成功，表单上一点变化都没有。
+
+| 只存在于布局组件 | 字段定义里也有 |
+|---|---|
+| `required`（必填）、`readOnly`、`singleRow`（独占一行）、`display`、`isHideTitle`、`excel`（位置）、`layout` | `title`、`dataKey`、`columnName`、`maxLen`、`componentKey`、`type`、`format` … |
+
+必填是个典型：一张真实表 53 条字段记录里，**没有一条**带 `required`。设必填就是改布局组件。
+
+## 已有字段的布局级单项操作
+
+先用 `form layout describe <objId> --field <字段名或fieldId>` 定位实际字段与布局；以下写命令使用真实 `fieldId`。它们修改布局组件，不修改字段定义。需要对变更做差异预览和逐项回读时，使用[局部编辑](inspect-edit.md)或[完整布局文档编辑](document.md)中适合该变更的路径。
+
+| 需求 | 命令 | 范围与核对 |
+| --- | --- | --- |
+| 将字段设为只读／可编辑 | `form layout set-read-only <objId> <fieldId> --read-only\|--no-read-only [--view-id <布局ID>]` | 可指定一套视图布局；保存后重新读取目标布局，核对字段的 `readOnly`。不传开关时命令缺省设为只读。 |
+| 将字段设为必填／非必填 | `form layout set-required <objId> <fieldId> --required\|--no-required [--view-id <布局ID>]` | 可指定一套视图布局；保存后核对字段的 `required`。不传开关时命令缺省设为必填。 |
+| 移动已有字段 | `form layout move <objId> <fieldId> --row <行> --col <列>` | 旧的直接写入命令，仅操作默认布局且没有差异预览；表格式会同步字段组件与对应网格单元格。需要先核对标题、值、占用和合并关系时，优先使用 `layout diff/edit` 的 `placements`。 |
+| 从默认布局移除字段组件 | `form layout remove-field <objId> <fieldId>` | 移除布局中的值组件、对应标题组件及主网格关联格；字段定义本身仍在表单中。命令只定位默认布局，执行前导出底稿，执行后核对组件和字段清单。 |
+
+`set-read-only`、`set-required`、`move`、`remove-field` 是已有的直接保存命令，不使用 `init-reviewed` 或 `diff/edit` 的审阅报告。表格式字段位置若还涉及标题格、合并或多组件调换，应先看[局部编辑](inspect-edit.md)支持的范围；复杂调整使用[完整文档](document.md)。`remove-field` 只让字段不在该布局中显示；需要删除业务字段时应走字段管理能力。
+
+## 加字段：默认增量，别动不动重建
+
+`e10-cli form add-field` 默认**只往布局里加这一个字段**，不动其它组件、不动样式模板、不动位置。
+
+`--reinit` 才是整表重建，它会：
+
+- 把样式模板换成工具默认的那一个；
+- 按字段顺序**重算所有位置**（手工调过的行列全没了）；
+- 把标签组件**全部换成新 id**；
+- 布局层的自定义（合并格、列宽、配色）一并丢失。
+
+**不是自己建的表不要用 `--reinit`。** 字段越多越经不起 —— 真实的一张订单主表有 131 个组件。
+
+### 表里还没有这个类型时：用平台给的字段模板
+
+新组件的键集（`format`、`earlyDate`、`pointSize`、`switchType` …）各类型都不一样，**按类型名拼一个出来只会猜错，而猜错不报错、只是渲染异常**。所以增量插入一向是**照同类型的现成组件整套抄**。
+
+表里没有同类型字段时，模板改从平台取：命令会调 `getFormFieldExist`，拿**平台按这个字段生成的组件模板**（`configPC`）—— 顶层样式键（按类型）与类型专有键平台都给全了，结构尾键从同作用域的现成组件借，位置和身份键由命令自己写。**全程不重建布局。**
+
+两点要知道：
+
+- **明细表字段也有自己的模板**：`getFormFieldExist` 的明细分类里，FLOW 布局的字段在 `childs[].comps`、EXCEL 布局的在 `comps[].children`，命令都会解析。第一次在明细表里加某类型字段，同样不需要先垫一个同类型字段。
+- 拿模板只在**真的缺**时才多打一次接口；表里已有同类型字段时，路径与从前一字不差。
+
+### 明细表的字段是横着排的
+
+同一个「加字段」，**主表和明细表落的轴不一样**：主表是一行一个字段（新字段**往下加行**），明细表是一个字段占一列（新字段**往右加列**）。明细表还有自己的一张网格（`workbook` 的键就是 `DetailTable` 组件的 id），明细字段的格子在那张里，不在 `Sheet1`。
+
+FLOW 布局下，每个明细字段会**自动包一层独立的 `InternalContainer`**，并登记到明细表的 `flow.linkedNodes`，与设计器里的结构一致。
+
+正常不会再因「没有同类型模板」中止。万一平台没返回该字段的模板，两个选择：
+
+1. 确认这张表是自己建的、不在乎版式被重排 → 显式加 `--reinit`；
+2. 之后仍失败，再在设计器里手工加一次同类型字段作参照。
+
+## 追加明细表：默认增量放进布局
+
+给已有表单加明细子表用 `e10-cli form add-detail-table`。**默认会把这明细表放进现有布局**，和加字段一样不重建：
+
+```bash
+e10-cli form add-detail-table <objId> <appId> "费用明细" "费用类型"
+```
+
+- 子表必须是**有字段**的（命令会顺带建首字段）；空子表平台不返回，放不进布局。
+- 只想建表、布局自己排：加 `--no-place`。
+- `--init` 是另一条路：整表重建（换样式模板、重排位置），只在布局本来就是自己建的、不在乎版式时用。
+
+实现上不碰原布局的 initLayout：复制一套临时布局 → 在副本上让平台生成明细容器与子字段组件 → 摘出这一块 → 删除副本 → 合并进原布局。原布局里已有的行列、合并格、样式都保留，明细表落在主表字段下方。
+
+放好之后，往这张明细里加字段照常用：
+
+```bash
+e10-cli form add-field <objId> <appId> "金额" Number --sub-form-id <subFormId>
+```
+
+已经建好、但还没进布局的明细表（例如当时用了 `--no-place`），单独放进去：
+
+```bash
+e10-cli form layout add-detail-table <objId> <appId> <subFormId|明细表名>
+```
+
+命令幂等：已经在布局里时直接提示，不重复添加。FLOW 布局也支持（明细字段挂在容器内的 `InternalContainer` 画布下）。
+
+## 哪些 id 可以自己生成，哪些必须由平台发号
+
+这一条最容易踩：**编一个 id 不会报错**，而是在之后某个看不出来的环节静默失效。
+
+| 位置 | 能否自己生成 | 说明 |
+|---|---|---|
+| 布局组件的 `id` | ✅ | 布局内唯一即可，形如 32 位十六进制串 |
+| 布局组件的 `excel.nodeId` | ✅ | 布局内唯一即可，短随机串 |
+| 标签组件的 `config.fieldId` | ✅ | 只在布局内有意义，与字段定义无关 |
+| **`labelObj.title` / `titleLabelId`** | ❌ **必须平台发号** | 见下 |
+
+### 为什么标题的 id 必须平台发号
+
+平台把**字段标题存的是标签 id，不是文本本身**。这个 id 要调多语言标签接口（`i18n/multilangLabel/saveLabel`）由平台分配。
+
+自己拼一个（比如拿时间戳凑）的后果：接口**照样回成功**，之后任何要显示这个标题的地方都取不到文字 —— 字段名变成空的，看着就像这个字段不存在。
+
+判断一个标签 id 是否有效：用 `-1` 去查标签，拿到的是一行空值（模板行）。**查一个不存在的标签，返回的结果与查 `-1` 完全一致** —— 所以「查得回来」不等于「标签存在」，要看有没有值。
+
+现成命令：`e10-cli form field-lang set <objId> <appId> <fieldId> --zh <中文> --en <英文>` 会建标签并回写字段，写完还能回读校验。`form add-field` 建字段时也会自动建标签。
+
+## 相关
+
+- 建表时的布局规划见 [EB 表单布局规划](planning.md)。
+- 字段类型与属性码表见 [表单字段定义参考](../ref-form-fields.md)。

package/skill-docs/references/form/layout/initialization.md

@@ -0,0 +1,39 @@
+# 初始化或重建表单布局
+
+本篇用于按当前字段重新生成一套布局，并可应用对应类型的样式模板、设置字段显示属性。它会影响整套布局；布局管理、局部编辑和完整文档编辑见[布局总览](layout-overview.md)。
+
+## 初始化或重建布局
+
+原有 `form layout init` 命令保持可用。本节介绍独立的 `init-reviewed`，用于先预览、再执行并回读核验；两者当前并存。
+
+`form layout init-reviewed` 是独立的可选操作。它按当前表单字段配置重新生成布局，并可应用同布局类型的样式模板。重建会重新排版字段、分组和明细组件，也可能覆盖已有网格样式、页面样式与布局代码块；已有精细布局应先用 `form layout document export` 保存底稿。它不负责创建字段，也不用于调整几个已有单元格；局部调整使用下文的 `diff/edit`。
+
+选择模板时可先用 `form-engine layout-template catalog` 查询当前环境。`--style-template` 接受与目标布局类型相同、已启用的高级表格式或流式 PC 模板；PC 表格式简易模板使用 `--easy-template`。两个选项互斥。预览会记录所选模板的样式依据，执行前检查模板未变；执行结果中的 `templateEffectVerified` 表示模板的可核对样式已在布局回读中出现。具体核对范围见[模板总览](template/template-guide.md)。
+
+先生成计划，再用同一组选项执行。计划列出布局身份、模板、字段配置数量、当前组件数、覆盖项和影响范围；执行时会重新读取并核对布局、字段和配置是否仍与计划一致。初始化后独立回读布局身份、组件和显式指定的字段属性。
+
+```bash
+e10-cli form layout init-reviewed <objId> --style-template <名称或ID> --preview-only --out init-plan.json
+e10-cli form layout init-reviewed <objId> --style-template <名称或ID> --preview @init-plan.json --out init-result.json
+```
+
+不指定模板时，流式使用“标准版”，表格式使用“表格版”。`--view-id` 可限定一套布局。`--read-only/--no-read-only`、`--required/--no-required`、`--disable-edit/--no-disable-edit`、`--single-row/--no-single-row` 可成对设置所有业务字段；未传的属性沿用初始化配置。若需要覆盖字段属性，预览和执行必须带完全相同的选项。`--no-generate-collapse` 可关闭折叠分组生成。初始化不是精确的字段逐格摆放工具，也不会预先生成最终组件 ID；需核对完整结果时再使用 `layout describe` 或 `layout document export`。
+
+需要分别设置字段时，用 `--config @init-config.json` 传入字段 ID。该文件可只列需要覆盖的字段；每项可设置 `readOnly`、`required`、`disableEdit`、`singleRow`、`display`、`show`，均为布尔值。明确写 `false` 可关闭相应属性。字段级设置覆盖同次命令的全局开关；预览与执行使用同一文件。
+
+```json
+{
+  "schemaVersion": "e10.layout-init-config/v1",
+  "fields": [
+    { "fieldId": "<字段ID>", "required": true, "readOnly": false },
+    { "fieldId": "<另一个字段ID>", "singleRow": true }
+  ]
+}
+```
+
+```bash
+e10-cli form layout init-reviewed <objId> --config @init-config.json --preview-only --out init-plan.json
+e10-cli form layout init-reviewed <objId> --config @init-config.json --preview @init-plan.json --out init-result.json
+```
+
+初始化会重建整套布局，即使只覆盖一个字段也是如此。对已有布局的单字段属性调整，应先评估是否有更局部的字段属性命令；不要为了一个开关重建已精细设计的布局。`display/show` 会影响显示状态，执行后还应在实际表单预览中核对可见性。

package/skill-docs/references/form/layout/inspect-edit.md

@@ -0,0 +1,76 @@
+# 查询与局部编辑表单布局
+
+本篇用于读取已有布局，并在现有 EXCEL 网格内调整少量行高、列宽、单元格样式或字段位置。大范围原生结构改动见[完整布局文档编辑](document.md)。
+
+## 创建与局部调整
+
+```bash
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
+e10-cli form layout read <objId>
+```
+
+创建后需要调整表格式布局的字段位置或网格样式时，先用下文的 `layout describe` 定位，再用 `layout diff` 审阅、`layout edit` 应用。只读和必填等显示属性仍使用 `form layout` 对应设置命令；具体参数通过 `form layout --help` 查询。
+
+## 查询已有布局结构
+
+调整前先用 `layout describe` 只读查询目标。默认按 eBuilder 表单 objId 读取默认布局；指定其他布局、模块或终端时明确传入对应参数。
+
+```bash
+e10-cli form layout describe <objId> --terminal PC --out layout-description.json
+e10-cli form layout describe <objId> --view-id <布局ID> --field <字段名或fieldId> --out field-position.json
+e10-cli form layout describe <流程表单formId> --module workflow --id-type form --terminal PC
+```
+
+结果包含布局 ID、页面类型、终端、快照指纹、字段标题和值组件、分组与明细容器、各 workbook 的行列尺寸、合并格、单元格样式及代码块是否存在。表格式布局分别列出标题和值组件的位置；流式布局的标题可直接包含在字段组件内。`diagnostics` 提示缺少组件或组件位置与主网格不一致。`--out` 保存完整结构化结果；既有 `layout read --raw --out` 仍用于查看完整原生快照。查询不会保存或初始化布局。
+
+## 预览表格式布局调整差异
+
+先用 `layout describe` 确定终端、workbook 名称及零起始行列坐标，再写调整配置。`Sheet1` 是主网格；明细网格使用查询结果中的实际 sheet 名称。`sheets` 和 `placements` 可分别使用，也可在同一配置中组合。行高以 px 表示；列宽使用 `percent` 或 `fixed`；单元格可以设置背景色、文字色、字体、下划线、水平/垂直对齐、换行、缩进和四侧边框。单元格样式属性及取值与[高级模板网格样式](template/advanced.md)一致。样式调整只作用于已有原生单元格，不创建新单元格或修改合并区域。
+
+```json
+{
+  "schemaVersion": "e10.layout-edit/v1",
+  "sheets": {
+    "Sheet1": {
+      "rowHeights": [{ "row": 1, "px": 52 }],
+      "columns": [{ "col": 1, "unit": "percent", "value": 12 }, { "col": 2, "unit": "percent", "value": 34 }],
+      "cells": [{ "row": 1, "col": 1, "backgroundColor": "#EAF5EE", "horizontalAlign": "center",
+        "borders": { "bottom": { "line": "thin", "color": "#C8DCCD" } } }]
+    }
+  }
+}
+```
+
+按字段 ID 调整标题和值组件位置时，使用 `placements`。`sheet` 填 `describe` 返回的组件所在网格：主表为 `Sheet1`，明细字段为对应明细表组件 ID。可只设 `title` 或 `value`，也可同时设置；每个坐标均为零起始。下面仅展示配置形状，行列数字应按目标布局实际空位填写：
+
+```json
+{
+  "schemaVersion": "e10.layout-edit/v1",
+  "placements": [
+    { "fieldId": "<字段ID>", "sheet": "Sheet1", "title": { "row": 3, "col": 1 }, "value": { "row": 3, "col": 2 } }
+  ]
+}
+```
+
+位置预览同时列出组件 `config.excel` 和 workbook 单元格两份坐标差异。移动限于原网格，不跨主表／明细表，也不改变字段归属。目标必须在现有行列范围内；非本次移动的任何单元格记录都视为占用。多个组件可以在同一批次使用彼此腾出的原位置，但最终目标不能重叠。源格或目标格处于合并区域时会阻断；合并关系需作为后续独立能力调整。
+
+```bash
+e10-cli form layout diff <objId> --terminal PC --config @layout-edit.json --out layout-diff.json
+e10-cli form layout diff <objId> --view-id <布局ID> --terminal MOBILE --config @layout-edit.json
+```
+
+完整结果逐项给出原生配置路径、`before`、`after` 和关联字段组件；同时包含目标身份、布局 ID、快照指纹、`issues` 与 `canApply`。重复设置、越界、百分比列宽总和不为 100、合并区域占用、缺少原生单元格或移动目标被占用等会形成冲突。`canApply` 只表示这份配置通过当前静态检查，并不代表已应用。命令仅读取布局并计算差异，不保存；发生冲突时退出码为 2。
+
+## 应用已预览的布局调整
+
+确认差异报告中的目标、前后值和关联组件后，使用**原配置文件**和 `diff --out` 保存的**原差异报告**应用。命令再次读取布局，核对环境、目标、终端、配置哈希、字段指纹和快照指纹；布局或配置有变化时，重新执行 `diff`。通过后只改配置指定的行高、列宽、已有单元格样式和字段组件位置，并单次保存。无差异时直接返回，不发保存请求。
+
+```bash
+e10-cli form layout edit <objId> --terminal PC --config @layout-edit.json --preview @layout-diff.json --out layout-edit-report.json
+```
+
+`edit` 保存后独立回读每项实际值和字段指纹。报告中的 `saved:true` 表示这些值已验证；`verifiedChanges` 是核对通过的项目数。若保存结果不确定，命令仍只回读判断，**不会重复发送保存请求**。恢复原值也要重新 `diff`，再用新的差异报告执行 `edit`。目前此能力只处理 EXCEL 网格的行高、列宽、已有单元格样式和同网格字段组件位置，不改变合并关系和布局类型。
+
+需要同时修改多个布局区域、组件、合并关系、页面样式或代码块时，使用[完整布局文档编辑](document.md)导出底稿并预览差异。此工作流与上述局部 `layout diff/edit` 配置文件不同。
+
+只需修改布局代码块的 JS 或 CSS 时，使用 `form code layout preview/apply`；它按布局 ID 和终端保存，另一种代码保持原值。源码作用范围及写法见[代码块指南](code-block/code-block-guide.md)和[布局 CSS 指南](code-block/layout-css.md)。