weaver-e10-builder 1.5.15 → 1.6.0

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

@@ -0,0 +1,153 @@
+# 表单代码块配置指南
+
+本指南用于把表单引擎 JSSDK 作为一项可规划、可实施的表单功能配置。适用于 EB 表单和原生工作流程表单的布局源码；表单级 ecode、流程级或应用级 ecode 须按实际入口和生效范围另行选择。先确定代码放置层级、布局与终端，再按专题读取写法。各专题包含必要参数和可改用的代码，不依赖原始技术文档。
+
+## 适用场景
+
+平台内置的字段联动、公式、查重、校验、视图和流程配置能表达需求时，优先用平台配置；以下情况适合使用表单代码块：
+
+- 内置配置无法表达的条件组合、跨字段计算、动态属性或状态流转；
+- 需要在用户输入、明细增删、保存等动作前后实时响应、校验、提示或阻断；
+- 需要对明细行做即时汇总、占比、分组、父子归属或按条件筛选；
+- 需要控制选项、日期范围、浏览参数、页签等控件行为；
+- 需要复写字段组件渲染、追加字段内容或处理字段区域事件；
+- 需要在表单载入时做初始化、补全、规范化或默认值处理。
+
+## 选择 JS、CSS 或两者结合
+
+| 需求 | 写入内容 | 后续阅读 |
+| --- | --- | --- |
+| 字段变化、计算、校验、明细操作、动态属性和交互反馈 | JS | 下文的 JSSDK 专题及[事件与校验](events-validation.md) |
+| 页面主题、字段控件、分组、明细表和悬停／聚焦等视觉状态 | CSS | [布局 CSS 编写指南](layout-css.md) |
+| 运行逻辑和外观都要变化 | 同一目标布局的 JS 与 CSS | 分别准备文件，预览并核对两部分差异 |
+
+只提供 `--js` 或 `--css` 时，已有的另一部分保持不变。JS 能改变运行时行为，CSS 只影响已存在元素的呈现；两者均不代替字段定义和布局结构配置。选好内容类型后，再选择代码的作用层级。
+
+## 代码放在哪一层
+
+| 需求范围 | 入口 | 特点 |
+|---|---|---|
+| 只对某个布局、某个终端生效 | 布局源码：`form code layout set` / `wf-form code layout set` | 随布局和终端加载；CSS 自动限定在 `#ebpage_<pageId>`；JS 带 `pageId` 生效条件 |
+| 同一表单的所有布局/终端都要生效 | 表单级 ecode：`form code ecode ...` | 不随布局切换；需要自己判断当前表单/数据上下文 |
+| 应用级或全局页面逻辑 | 全局 ecode / 页面入口 | 不在本指南的表单布局命令范围内；使用 `onFormReady` 等全局事件并按 formId/module 限定 |
+
+选择原则：能用布局源码完成的不要放大到表单级，能用表单级完成的不要放大到全局。
+
+## 能实现什么
+
+| 场景 | 可形成的效果 | 关键 API（示例） | 专题 |
+|---|---|---|---|
+| 加载初始化 | 默认值、状态初始化、数据补全/规范化 | 直接执行 + `getFieldValue` / `changeFieldValue` | [基础与字段](foundations-fields.md) |
+| 字段联动 | A 变化写 B；跨字段计算；空值/清空；防循环 | `bindFieldChangeEvent`、`getFieldValue`、`changeFieldValue`、`triggerFieldAllLinkage` | [基础与字段](foundations-fields.md)、[事件与校验](events-validation.md) |
+| 动态属性 | 按状态/角色/条件切换只读、可编辑、必填、隐藏、隐藏行 | `changeFieldAttr`、`changeSingleField`、`changeMoreField` | [基础与字段](foundations-fields.md) |
+| 保存前校验 | 阻断保存并提示；通过/失败回调；异步校验 | `registerCheckEvent(OPER_SAVE)`、`stop({msg})` | [事件与校验](events-validation.md) |
+| 明细计算 | 金额合计、占比、分组汇总、父子明细回写 | `getDetailData`、`getDetailAllRowIndexStr`、`addDetailRow` / `delDetailRow` | [明细操作](details.md) |
+| 明细事件 | 增行/删行/改值后重算；行显示、勾选、排序 | `ACTION_ADDROW` / `ACTION_DELROW`、`controlDetailRowDisplay`、`checkDetailRow` | [明细操作](details.md) |
+| 控件行为 | 日期范围、选项过滤/禁用、浏览参数、页签切换 | `controlDateRange`、`controlSelectOption`、`controlOptionDisable`、`appendBrowserDataUrlParam`、`switchTabItem` | [特定控件](controls.md) |
+| 交互反馈 | 消息、确认框、加载、必填检查、刷新、关闭提示 | `window.WeFormSDK.showMessage/showConfirm/getLoadingGlobal`、`verifyFormRequired`、`reloadPage` | [组件与全局操作](ui-global.md) |
+| 字段组件复写 | 替换/追加字段内容、局部渲染、字段区域事件 | `proxyFieldComp`、`afterFieldComp`、`proxyFieldContentComp`、`bindFieldAction` | [组件与全局操作](ui-global.md) |
+| 扩展通信 | 插件接口、父子页面 `postMessage`、跨组件协作 | `pluginGet` / `pluginExecute`、`window.opener`、`postMessage` | [组件与全局操作](ui-global.md) |
+| 现成业务模式 | 明细人员汇总去重、按条件合并、分组同步、占比 | 见案例组合 | [效果案例](recipes.md) |
+
+## 边界与不适用场景
+
+- 代码块不是后端逻辑：不能绕过字段/数据权限、流程节点只读或接口鉴权，也不能替代服务端校验。
+- `OPER_SAVE` 拦截的是**表单数据保存**，不是工作流节点提交；流程提交拦截应使用流程相应入口。
+- 布局源码只作用于当前布局和终端；跨布局、跨终端的逻辑用表单级 ecode，并明确作用范围。
+- 字段、表单、流程、视图、权限等资源本身用对应 CLI/设计器配置，不要用代码块临时改结构。
+- 附件、人员、浏览对象必须来自平台真实对象/接口；不能只拼 `id/name` 伪造可预览附件或可选项。
+- 布局源码只使用编辑器可编译的语法和平台暴露的 API；不要直接套用独立 `.ecode` 项目的 `import`、JSX 或 npm 依赖。
+
+## 最小示例
+
+字段联动 + 动态只读 + 保存前校验：
+
+```js
+const status = formSdk.convertFieldNameToId('status', 'main');
+const amount = formSdk.convertFieldNameToId('amount', 'main');
+
+function applyStatus() {
+  const submitted = String(formSdk.getFieldValue(status) || '').trim() === '已提交';
+  formSdk.changeFieldAttr(amount, submitted ? 1 : 2);
+}
+applyStatus();
+formSdk.bindFieldChangeEvent(status, applyStatus);
+
+formSdk.registerCheckEvent(window.WeFormSDK.OPER_SAVE, (ok, stop) => {
+  const value = Number(formSdk.getFieldValue(amount) || 0);
+  if (value > 0) ok();
+  else stop({ msg: '金额必须大于 0' });
+});
+```
+
+明细金额合计：
+
+```js
+const table = formSdk.convertFieldNameToId('cost_detail', 'main');
+const detailAmount = formSdk.convertFieldNameToId('amount', table);
+const total = formSdk.convertFieldNameToId('total', 'main');
+
+function recalculate() {
+  const rows = formSdk.getDetailData(table) || [];
+  const sum = rows.reduce((n, row) => n + Number(row[detailAmount]?.value || 0), 0);
+  formSdk.changeFieldValue(total, { value: String(sum) }, { jsApiChange: false });
+}
+
+formSdk.bindFieldChangeEvent(detailAmount, recalculate);
+formSdk.registerAction(window.WeFormSDK.ACTION_ADDROW + table, recalculate);
+formSdk.registerAction(window.WeFormSDK.ACTION_DELROW + table, recalculate);
+recalculate();
+```
+
+> 示例中的 `status` / `amount` / `cost_detail` 等是字段数据 Key 的占位，实施时必须换成目标表单真实 Key，并从已建资源读取。
+
+## 按效果查专题
+
+| 要实现的效果 | 必读文档 |
+|---|---|
+| 初始化、定位字段、值结构、环境基线 | [基础与字段](foundations-fields.md) |
+| 保存前校验、明细行拦截、字段变化与联动事件 | [事件与校验](events-validation.md) |
+| 明细行增删改查、批量处理、父子明细 | [明细操作](details.md) |
+| 浏览、选项、日期、附件、选项卡 | [特定控件](controls.md) |
+| 字段组件渲染、页面消息、弹窗、加载、插件、跨页面交互 | [组件与全局操作](ui-global.md) |
+| 从业务描述找现成实现模式 | [效果案例](recipes.md) |
+| 指定布局的页面、字段和明细表外观 | [表单布局 CSS 编写指南](layout-css.md) |
+| 代码不生效、版本与事件问题 | [排查与边界](troubleshooting.md) |
+
+## 配置顺序
+
+1. 在 plan 中记录目标表单、布局、终端、代码层级、触发时机、涉及字段/明细数据 Key、期望效果及检查方式。布局源码只作用于当前布局及终端；跨布局或全表单逻辑选择表单级 ecode，并明确范围判断。
+2. 从已建资源读取真实字段数据 Key、明细表 Key 和布局 ID。用 `convertFieldNameToId` 定位运行时字段；同名 Key 可能同时存在于主表和明细表，必须传位置。
+3. 根据效果组合专题中的 API。代码应处理初始化、空值、明细增删、重复注册与事件循环；不要从旧案例直接复制固定 ID、测试 URL 或示例数据。
+4. 在对应入口保存 JS/CSS 后读回，并以一个正常场景和一个边界场景验证运行结果。保存成功只能证明代码存储，不代表事件执行或业务效果正确。
+
+## CLI 写入入口
+
+先用下表中的 JSSDK 专题确定代码写法，再用对应命令写入。JS、CSS 分别读取文件；只提供其中一项时保留另一项。布局源码须指定实际布局 ID 与终端，表单级 ecode 使用独立配置，不随布局切换。
+
+| 范围 | 读取 | 写入 |
+|---|---|---|
+| EB 表单布局 | `form code layout read <objId> --app-id <appId> --layout-id <id> --terminal PC|MOBILE` | `form code layout set <objId> --app-id <appId> --layout-id <id> --terminal PC|MOBILE --js <文件> [--css <文件>]` |
+| 原生工作流程表单布局 | `wf-form code layout read <formId> --layout-id <id> --terminal PC|MOBILE` | `wf-form code layout set <formId> --layout-id <id> --terminal PC|MOBILE --js <文件> [--css <文件>]` |
+| EB 表单级 ecode | `form code ecode list <objId> --app-id <appId>`；`form code ecode read <objId> <ecodeId> --app-id <appId>` | `form code ecode add <objId> --app-id <appId> --name <名称> --js <文件> [--css <文件>]`；`form code ecode edit <objId> <ecodeId> --app-id <appId> --js <文件>`；`form code ecode status <objId> <ecodeId> --app-id <appId> --state on|off` |
+| 原生工作流程表单级 ecode | `wf-form code ecode list <formId>`；`wf-form code ecode read <formId> <ecodeId>` | `wf-form code ecode add <formId> --name <名称> --js <文件> [--css <文件>]`；`wf-form code ecode edit <formId> <ecodeId> --js <文件>`；`wf-form code ecode status <formId> <ecodeId> --state on|off` |
+
+`set`/`add`/`edit` 保存后会读回确认；`edit` 可单独提供 `--js` 或 `--css`，保留另一部分。先用 `read` 核对已有代码和作用范围。
+
+布局代码需要差异预览时，用独立的 `form code layout preview/apply` 或 `wf-form code layout preview/apply`。两步传相同的布局 ID、终端和 `--js`／`--css` 文件；预览使用 `--out <文件>` 保存完整报告，应用时传 `--preview @<文件>`。预览会编译候选代码并列出被替换的 JS/CSS 原文；应用会检查源文件和布局未变化，单次保存后独立回读。只传一种文件时另一种代码保持不变。无源码变化时不发送保存请求。表单级 ecode 仍使用上表的独立命令。
+
+布局源码写入时，CLI 按当前终端页面的 `pageId` 生成 JS 生效条件，并把 CSS 选择器限定在当前 `#ebpage_<pageId>` 内。需要由 JS 动态插入且使用布局 CSS 的元素，应挂在该页面容器内；挂到 `document.body` 的元素不受这份布局 CSS 修饰。写入后用 `layout read` 核对 JS/CSS 原文、页面条件和编译结果，再打开实际表单页面检查运行效果。
+
+布局 CSS 的可设置内容、表格式与流式布局的选择器边界及完整写入示例，见[表单布局 CSS 编写指南](layout-css.md)。
+
+布局源码的 JS 与 CSS 分别保存；重建布局时分别确认两者是否保留。表单级 ecode 是另一份配置，不会随布局源码同步。表单源码中的 `formSdk` 可直接使用；全局 ecode 监听 `onFormReady` 并从事件取得对应实例，避免多表单页面取错实例。涉及审批节点提交的校验，先区分表单数据保存与流程提交：`OPER_SAVE` 拦截的是前者。
+
+本指南及其 JSSDK 专题负责代码的编写与效果判断；上述 CLI 命令负责定位资源、保存和读回。独立 `.ecode` 项目、流程级和应用级 ecode 不使用这些表单布局命令。
+
+## 布局源码存储与编码（设计器同源）
+
+- **不要手改 `sourceCode.ecode`。** CLI 负责编码；如果绕过 CLI 直接调接口，必须使用 `encodeURI(JSON.stringify({js, css}))`。
+- 设计器读取路径是 `JSON.parse(decodeURI(ecode))`。`encodeURIComponent` 会把冒号编码成 `%3A`，而 `decodeURI` 不还原它，结果是 `{"js"%3A...}`，浏览器报 `ECode decode failed, SyntaxError: Expected ':' after property name in JSON`，源码面板为空、预览失效。`form code layout set` / `wf-form code layout set` 已内置写入前和回读后的同路径校验。
+- 布局源码保存走 `saveFormAndLayout` 的 `pageLayoutEncodes` / `formStyleEncodes`（LZW 压缩），不要用裸 `pageLayouts` 写源码。`js` 需带 `content`、`compiledContent`、`pageId`（`if (<pageId> == String(props.pageId))`）、`name: "index"`、`state: "n"`；`css` 需带 `content`、`compiledContent`、`name`、`state`；`cssCache.ebd_page` 缺失时由 CLI 补平台默认值。
+- 布局源码运行时由平台外壳提供 `pageId`、`ebSdk`、`pageSdk`、`formSdk`。250101 及以后基线可直接使用 `formSdk`；拿不到时用 `pageSdk.on('formReady')` 配合 `window.WeFormSDK.getWeFormInstance()`。实际可用性以目标环境为准。
+- 写入后 CLI 会回读并校验 JS/CSS 原文、`compiledContent`、`pageId` 和 CSS 作用域；设计器解码自检失败时命令会报错，不会静默成功。

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

@@ -0,0 +1,60 @@
+# 浏览、选项、日期、附件与容器控件
+
+## 浏览字段
+
+| 需求 | API 与处理方式 |
+|---|---|
+| 获取已选对象 ID/显示名 | `getBrowserOptionId(field, splitChar?)` / `getBrowserShowName(field, splitChar?)`；返回字符串，默认以逗号分隔 |
+| 获取完整选项对象 | `getBrowserOptionEntity(field)`；优先用它作为复制、合并和回填来源 |
+| 浏览弹窗取数增加请求参数 | `appendBrowserDataUrlParam(field, {参数名:值})`；只是向请求附加参数，数据源须识别这些参数 |
+| 回填浏览字段 | `changeFieldValue(field,{specialObj:[{id,name,data?}]})`；清空传空数组 |
+
+浏览对象中的 `data` 对自定义浏览、附件等特殊来源很重要。不要把显示名称当 ID，也不要把添加请求参数误认为已在服务端实现数据过滤。运行时打开浏览弹窗检查实际可选记录。
+
+## 选项字段
+
+`getSelectShowName(field, splitChar?)` 取显示名，默认以逗号分隔；`getBrowserOptionEntity(field)` 可取选项对象。固定选项可按 ID 用 `value` 回填，选项模板按 `specialObj` 回填。
+
+| 控制 | API |
+|---|---|
+| 从选项中移除 | `removeSelectOption(field, '选项ID1,选项ID2')` |
+| 控制可显示选项 | `controlSelectOption(field, '选项ID1,选项ID2')` |
+| 禁用/恢复选项 | `controlOptionDisable(field, '选项ID1,选项ID2', true/false)`；20250501 起，省略 flag 默认禁用 |
+
+在表单 ready 后操作选项。移除、隐藏和禁用不是同义：分别验证弹窗/下拉是否显示、能否选中及已有值如何呈现。
+
+## 日期
+
+`controlDateRange(field, start?, end?)` 限定可选择范围。边界可传日期字符串（如 `2023-08-20`）或相对今天的天数字符串；`'0'` 表示今天。在原 SDK 的示例中，开始端 `'5'` 表示当前日期前 5 天，结束端 `'3'` 表示当前日期后 3 天；省略一端表示不限制该端。明细字段不加行 ID 时作用于整列。根据需求同时核验边界日期和越界日期。
+
+```js
+formSdk.controlDateRange(dateField, '2023-08-20', '2023-08-25');
+formSdk.controlDateRange(dateField, '5', '3');
+formSdk.controlDateRange(dateField, '0');
+formSdk.controlDateRange(dateField, undefined, '0');
+```
+
+## 附件与复杂值
+
+附件回填需要 `specialObj` 中对象带实际附件 `data`，包括文件 ID、类型、预览/下载等权限与操作信息。最稳妥的来源是已有字段 `getFieldObj` 或附件模块正式返回；仅 `{id,name}` 不足以保证预览。多级选项、浏览对象的次级数据可在 `data.content` 或 `data.dataOptions`，应先读取同类字段实际对象后组装。
+
+```js
+// data 应来自附件模块或现有附件字段，不在代码中凭空生成。
+formSdk.changeFieldValue(attachmentField, {
+  specialObj: [{id: file.id, name: file.name, type: 'file', data: file}]
+});
+// 多级选项的第二级是文本时：
+formSdk.changeFieldValue(cascadeField, {
+  specialObj: [{id: firstId, name: firstName, data: {content: secondText}}]
+});
+// 第二级是选项/浏览时，按已有控件对象构造 dataOptions：
+formSdk.changeFieldValue(cascadeField, {
+  specialObj: [{id: firstId, name: firstName, data: {dataOptions: [{optionId: secondId, content: secondName}]}}]
+});
+```
+
+原附件案例中的 `data` 含 `fileid/name/size/extName/type/img/uploadUser/uploadUserName/uploadTime/doc/docId/loadlink/options/uploadType/ban/secretLevel/validity/folderId` 等字段。哪些必填、哪些操作可见由附件来源与权限决定；复制已有对象比手填这套结构可靠。
+
+## 选项卡容器
+
+`switchTabItem(tabField, '序号')` 按从 1 开始的序号切换，或 `switchTabItem(tabField, tabId, 'id')` 按页签 ID 切换。`getFieldInfo(tabField).tabOptionTitle` 可检查页签信息，其中 `uid` 为 ID。20250501 及以后基线的 `changeTabItemAttr(tabField, '页签ID或序号, ...', attr)` 控制页签属性：`'1'` 禁用、`'2'` 可编辑、`'3'` 隐藏；一组调用中不要混用 ID 与序号。页签是布局容器，不当作普通选项字段写值。

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

@@ -0,0 +1,32 @@
+# JSSDK 原资料覆盖对照
+
+本表用于维护指南的完整性；执行配置时按 [入口](code-block-guide.md) 路由，不需要再打开原始合并文档。核对范围是导出的 91 篇正文；同一原章的不同方法已按实际用途拆到专题。所谓“覆盖”指功能、必要调用契约和关键边界进入指南，不表示逐字保留原文全部示例数据或截图。
+
+| 原资料章节及篇数 | 在本目录中的落点 | 包含的功能 |
+|---|---|---|
+| 1 说明（3） | [基础与字段](foundations-fields.md)、[排查](troubleshooting.md) | SDK 实例、表单 ready、全局初始化 |
+| 2 表单事件注册（2） | [事件与校验](events-validation.md) | 动作前拦截、动作后钩子 |
+| 3 字段基础操作（12） | [基础与字段](foundations-fields.md) | Key 转标识、读值/对象/信息/属性、单个与批量赋值、属性、联动触发、组件引用 |
+| 4 字段事件与组件复写（7） | [事件与校验](events-validation.md)、[组件与全局操作](ui-global.md) | 主/明细字段事件、字段交互、属性事件、组件替换/追加/包装 |
+| 5 明细表操作（21） | [明细操作](details.md) | 行增删查改、行 ID/序号转换、选中/禁选/显隐/排序、顶部操作、筛选、批量、复制末行 |
+| 6 表单全局操作（10） | [组件与全局操作](ui-global.md) | 基本信息、移动端、消息、确认、自定义弹窗、刷新、提交参数、必填、加载、关闭提示 |
+| 7 特定字段类型（9） | [特定控件](controls.md) | 浏览请求与值、选项显示/移除/禁用、日期范围 |
+| 8 容器字段（2） | [特定控件](controls.md) | 页签切换、页签状态 |
+| 9 插件类型（3） | [组件与全局操作](ui-global.md)、[排查](troubleshooting.md) | 插件前提、读取、执行 |
+| 10 开发必看（1） | [基础与字段](foundations-fields.md)、[排查](troubleshooting.md) | 基线、实例获取和相关外部 SDK 边界 |
+| 11 常见问题（1） | [排查](troubleshooting.md) | 时机、权限、超时、保存与提交区别 |
+| 12 案例分享（15） | [效果案例](recipes.md)、各 API 专题 | 14 组业务效果；保存前汇总人员原文两篇重复，均已覆盖 |
+| 13 扩展说明（5） | [明细操作](details.md)、[组件与全局操作](ui-global.md)、[排查](troubleshooting.md) | 嵌套明细、父子页面、调试屏蔽、事件刷新、不生效排查 |
+
+## 核对后保留的边界与资料冲突
+
+| 项目 | 指南处理 |
+|---|---|
+| `formSdk` 闭包实例的最低基线 | 说明与开发必看主体写 250101；常见问题和开发必看一处又写 241201。指南按 250101 作为稳妥门槛，较早环境须实际检查。 |
+| 明细新增时使用末行数据 | 原文 5.17 列 `setDetailAddDefLast`，示例却调用 `setDetailAddUseCopy`；5.6 又单独列后者。两种 API 均保留，前者行为在目标环境核对。 |
+| `getFieldCom`、字段赋值及明细属性的示例笔误 | 在[排查文档](troubleshooting.md)列出，专题示例采用修正后的调用形状。 |
+| 附件 `data`、插件具体方法、外部查询接口 | JSSDK 资料未给出完整提供方契约。指南说明如何接入和从现有数据读取，但不编造文件对象、插件方法或接口。 |
+| 审批节点提交拦截 | 表单 JSSDK `OPER_SAVE` 只覆盖表单数据保存；流程提交属于流程 SDK，本目录不宣称覆盖。 |
+| 页面组件 props 全局复写 | 原案例使用 `regOvProps`，是 ecode 层功能；与布局源码的字段局部渲染分别路由。 |
+
+资料中所提工作流程 SDK、EB SDK、UI 组件和具体插件文档并不属于这 91 篇 JSSDK 资料；本目录只描述已给出的跨界入口，不臆造其完整方法。涉及这些外部契约时读取对应专题或说明尚缺契约。

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

@@ -0,0 +1,57 @@
+# 明细表与嵌套明细 JSSDK
+
+先用 `convertFieldNameToId(明细表数据Key,'main')` 取明细标识，再以其为位置取得明细字段标识。`rowId` 是一行的运行时身份，不等于序号，也不是普通业务字段。`getDetailData(table)` 返回的每行含 `rowId` 以及以字段标识为键的 `{value}` 或 `{specialObj}` 对象；复制到另一明细表时去掉原 `rowId`，否则可能写错行。
+
+## 行与数据操作
+
+| 目标 | API、关键参数 |
+|---|---|
+| 添加一行 | `addDetailRow(table, {[field]:{value:'文本'}, [browser]:{specialObj:[{id,name}]}})` |
+| 批量添加 | `addDetailData(table, [{[field]:{value:'A'}}, ...], config?)` |
+| 删除指定行/全部行 | `delDetailRow(table, rowId)` / `delDetailRow(table, 'all')` |
+| 更新多行 | `changeDetailData(table, [{rowId, [field]: {value:'新值'}}, ...], config?)`；250101 起，无 rowId 的项会新增行 |
+| 取全部行数据/某行 | `getDetailData(table, options?)` / `getDetailRowData(table, rowId)`；均至少 240601 基线 |
+| 取行 ID 串/行数 | `getDetailAllRowIndexStr(table)` 返回逗号分隔的 rowId；`getDetailRowCount(table)` 返回行数（原资料类型声明写 string、示例结果写 number，使用时以实际返回为准） |
+| 序号转行 ID/反向 | `getDetailRowIdByIndex(table, index)` / `getDetailIndexByRowId(table, rowId)`；index 从 1 起 |
+| 按行 ID 取显示序号 | `getDetailRowSerailNum(table, rowId)`（接口拼写为 Serail） |
+| 取明细字段 ID | `getDetailFieldIds(table, prefix?)`；240701 起，`prefix` 默认 `false`（不带 `field` 前缀），需要前缀时传 `true`；原示例以逗号分隔结果使用 |
+
+```js
+const rows = formSdk.getDetailData(table) || [];
+const total = rows.reduce((n, row) => n + Number(row[detailAmount]?.value || 0), 0);
+formSdk.changeFieldValue(mainTotal, {value: String(total)});
+```
+
+上述汇总应在页面载入、金额变化、添加行、删除行后分别触发。金额换算用 `Number` 与明确的空值处理，不用拼接表达式再 `eval`。百分比要处理总额为 0 的情况。
+
+## 行显示、选择与菜单
+
+| 目标 | API |
+|---|---|
+| 获取勾选行 | `getDetailCheckedRowIndexStr(table)`；返回行 ID 串 |
+| 勾选指定行/全部 | `checkDetailRow(table, 逗号分隔的rowId或'all', needClearBeforeChecked?)`；`checkDetailRow(table, '', true)` 清空已选 |
+| 禁止勾选 | `controlDetailRowDisableCheck(table, rowId或'all', true)`；`false` 恢复 |
+| 隐藏/显示行 | `controlDetailRowDisplay(table, 逗号分隔的rowId或'all', needHide)`；`true` 隐藏、`false` 显示 |
+| 排序显示行 | `setDetailSortRows(table, 逗号分隔的rowId, 'before'或'after')` |
+| 新增时复制末行 | `setDetailAddUseCopy(table, true/false)` |
+| 新增时默认使用末行数据 | `setDetailAddDefLast(table, true/false)`；至少 240701 基线，原文示例误写成 `setDetailAddUseCopy`，须区分两种设置的实际效果 |
+| 顶部自定义操作 | `setDetailTopAction(table, actions)`；每项有 `id/type/title/mode` 等，按目标组件允许的动作填写 |
+| 当前明细筛选条件 | `getDetailSearchCfg(table)`；可用于 `getDetailData(table,{searchValue: cfg})` |
+
+`addDetailData` 至少 241201 基线，传入数组每项以字段标识为键、值为 `{value}` 或 `{specialObj}`；第三参数可控制 `dataLinkage/viewLinkage/optionLinkage/jsApiChange`。`changeDetailData` 至少 250101 基线，结构相同但更新项需附 `rowId`；若传入项的 `rowId` 不存在，原资料说明会生成新行，配置时不要误用。动态行使用 `registerAction(ACTION_ADDROW + table, ...)` 与删除事件更新汇总或渲染；回调首参数是从 0 开始的行下标集合，不是 rowId。原资料同时列出 `setDetailAddDefLast` 与 `setDetailAddUseCopy`，但前者的示例错误调用了后者；保留两者各自契约，目标版本行为以实测为准。
+
+顶部操作示例：`setDetailTopAction(table,[{id:'refresh',type:'refresh',title:'刷新',mode:'text'}])`；自定义渲染项可用 `{id:'custom',type:'custom',customRender:()=>React.createElement('div',{},'操作')}`，需保证当前代码入口有 React。`setDetailSortRows(table,'rowId1,rowId2','before'|'after')` 至少 241101 基线，默认 `before`。260401 及以后，`getDetailData(table,{searchValue:formSdk.getDetailSearchCfg(table)})` 可按当前明细筛选条件取行；不传第二参数则读取整表行。
+
+## 父子明细
+
+给某父行增加子行时，先确保父行已存在，再把子级行标识字段写为该父行的标识值；它是父子关系字段，不是新子行的 `rowId`。通常流程：取父 `rowId` → 读取父级行标识字段的值 → `addDetailRow(childTable,{[childRelationField]:{value: parentKey}, ...})`。按父行汇总时，筛选子表关系字段等于当前父行标识的行，再汇总回该父行字段。
+
+```js
+const parentKey = formSdk.getFieldValue(`${parentRelation}_${parentRowId}`);
+formSdk.addDetailRow(childTable, {
+  [childRelation]: {value: parentKey},
+  [childAmount]: {value: '0'}
+});
+```
+
+不要把父表行 ID 直接当作子表行 ID。父子关系字段的实际值若为选项对象，先用 `getFieldObj` 检查结构，再按同类结构赋值。

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

@@ -0,0 +1,42 @@
+# 事件、校验与联动
+
+## 动作前拦截与动作后钩子
+
+`registerCheckEvent(action, (successFn, failFn, data) => {...})` 在动作前执行。校验通过调用 `successFn()`；不通过调用 `failFn({msg:'原因'})` 由系统提示，或自行提示后调用 `failFn()`。异步逻辑必须在所有路径调用其中之一；超过约 25 秒未回调会超时。可多次注册，按注册顺序执行。`window.WeFormSDK` 提供动作常量：`OPER_SAVE`、`OPER_ADDROW`、`OPER_DELROW`、`OPER_BEFOREVERIFY`、`OPER_EDITDETAILROW`、`OPER_FD_LINKAGE`（240601 起）。针对某明细表的添加/删除动作在常量后拼接明细表标识。
+
+```js
+formSdk.registerCheckEvent(window.WeFormSDK.OPER_SAVE, (ok, stop) => {
+  const v = Number(formSdk.getFieldValue(amount) || 0);
+  if (v > 0) ok();
+  else stop({msg: '金额必须大于 0'});
+});
+```
+
+`OPER_SAVE` 是表单数据保存动作，不等于工作流程节点的提交按钮校验。若需求是流程提交拦截，应选择流程相应能力及入口，不应把本例当作已覆盖。
+
+`OPER_EDITDETAILROW` 是移动端编辑明细的拦截事件。`OPER_FD_LINKAGE` 拦截字段联动执行，回调 `data` 可含 `actionType/triggerFields/triggerRowIds`；过滤指定触发字段后调用 `successFn` 或 `failFn`，字段 ID 要与真实返回类型一致。`OPER_BEFOREVERIFY` 在必填校验前触发。
+
+`registerAction(action, callback)` 是动作完成后的通知，可注册多个回调，按注册顺序执行。常量包括 `ACTION_ADDROW`、`ACTION_DELROW`（后拼明细标识）、`ACTION_FORM_SAVE`、`ACTION_DATA_LINKAGE`、`ACTION_DATA_RELATE`、`ACTION_VIEW_LINKAGE`。新增/删除明细行后的回调接收行下标集合和 `data`，下标从 0 开始，不可直接当 `rowId`；需要行身份时再查询。明细导入也可能触发添加行事件，`data.type` 可帮助区分。`ACTION_DATA_LINKAGE` 表示顶部字段联动/函数公式执行后，`data.runData` 可含 `actionType/resultFields/triggerFields/triggerRowIds`（240601 起）；`ACTION_DATA_RELATE` 表示关联字段钻取、字段右侧函数或运算控件后，回调可含 `fieldIds/rowIds/tableId`。
+
+## 字段变化与交互
+
+| API | 触发与用途 |
+|---|---|
+| `bindFieldChangeEvent('字段标识,字段标识', callback, options?)` | 主表或明细字段值变化；`data` 中可取 `rowId` |
+| `bindDetailFieldChangeEvent('明细字段标识', callback)` | 专门处理明细字段值变化 |
+| `bindFieldAttrChangeEvent('字段标识', callback)` | 字段读写属性变化 |
+| `bindFieldAction(type, '字段标识', callback)` | 字段区域交互；`onblur/onfocus/onclick/ondbclick/mouseover/mouseout` |
+
+字段事件可指定 `scope` 区分用户修改与联动带出，常量为 `window.WeFormSDK.CHANGE_EVENT_SCOPE`（主表事件至少 250401；明细专用事件至少 250901）及 `window.WeFormSDK.CHANGE_EVENT_LINKAGE`。回调 `data` 可含 `id/value/rowId`；值变化不包括明细增删行，因此仍须注册行事件。联动修改不一定自动触发 JS 值变化事件，必要时通过赋值配置的 `jsApiChange` 或 `triggerFieldAllLinkage` 明确触发。251101 起可设置全局 `window.__FORM_JS_LINKAGE_EVENT_CHANGE__ = true` 扩展联动事件触发范围，可能使既有监听再次运行；只在确有需要时使用。
+
+```js
+formSdk.bindFieldChangeEvent(detailAmount, ({rowId}) => {
+  if (!rowId) return;
+  const value = Number(formSdk.getFieldValue(`${detailAmount}_${rowId}`) || 0);
+  formSdk.changeFieldValue(`${detailTax}_${rowId}`, {value: String(value * 0.13)});
+});
+formSdk.registerAction(`${window.WeFormSDK.ACTION_ADDROW}${table}`, () => recalculate());
+formSdk.registerAction(`${window.WeFormSDK.ACTION_DELROW}${table}`, () => recalculate());
+```
+
+编写校验时先定触发动作、允许/阻断条件、提示内容及异步失败路径；编写联动时同时覆盖载入、字段变化、明细增删，并防止监听目标再触发自身。保存后分别验证通过与不通过两条路径。

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

@@ -0,0 +1,56 @@
+# JSSDK 基础、字段定位与赋值
+
+## 实例与时机
+
+- 布局源码和表单级 ecode（250101 及以后基线）使用当前作用域的 `formSdk`。旧方式 `window.WeFormSDK.getWeFormInstance()` 可能在多表单页面取错实例。
+- 早期基线可通过 `pageSdk.on('formReady', callback)` 等待表单加载，再调用 `window.WeFormSDK.getWeFormInstance(moduleKey?, formId?, dataId?)`；条件允许时传入更细的模块、表单、数据 ID，避免页面同时打开多份表单时取错。全局 ecode 用 `window.addEventListener('onFormReady', e => { const {formSdk, formId, module}=e.detail; ... })`，按 `formId/module` 限定作用范围；这个全局事件每打开一份表单都会触发，不放在单布局源码中重复监听。
+- 字段和明细行尚未渲染时不要操作其组件。注册事件通常在表单 ready 后进行，动态新增明细行须在添加行事件后处理。
+
+## 字段标识与读取
+
+`formSdk.convertFieldNameToId(dataKey, location?, prefix?)` 将数据 Key 转为字段标识，`prefix` 默认 `true`，即返回带 `field` 前缀的标识；传 `false` 时返回纯数字 ID。主表用 `location='main'`；明细字段用明细表标识作为 location。260601 及以后也可用明细表数据 Key 作 location。字段数据 Key 在字段管理“数据 Key”列或设计器选中字段后的右侧查看；明细表 Key 在设计器选中明细表后查看，高级版可能要双击明细表。明细某行标识为 `${detailField}_${rowId}`，`rowId` 是运行时行 ID，不是显示序号。
+
+```js
+const amount = formSdk.convertFieldNameToId('amount', 'main');
+const table = formSdk.convertFieldNameToId('payment_detail', 'main');
+const rate = formSdk.convertFieldNameToId('rate', table);
+const firstRowId = formSdk.getDetailRowIdByIndex(table, 1);
+const value = firstRowId ? formSdk.getFieldValue(`${rate}_${firstRowId}`) : undefined;
+```
+
+| 读取 API | 用途 |
+|---|---|
+| `getFieldValue(fieldMark)` | 取单个字段简化值；文本返回内容，选项/浏览一般返回 ID，取显示名用控件专题方法 |
+| `getFieldObj(fieldMark)` | 取原始数据对象，可含 `value/specialObj/longitude/latitude/type/contentObj`；不确定控件结构时先看它；240701 起 |
+| `getFieldInfo(fieldMark)` | 字段元数据，可含 `fieldId/dataKey/name/componentKey/isSingle`；实际对象还可能有其他属性 |
+| `listFieldInfo()` | 当前表单所有字段信息，含 `readOnly/required` 等 |
+| `getFieldAttr(fieldMark)` | 当前读写属性，返回 1～5 的属性码 |
+| `getFieldCom(fieldMark)` | 字段组件信息，含 `id/type/config`；240701 起。原文示例误调用 `getFieldInfo` |
+
+## 赋值结构
+
+`changeFieldValue(fieldMark, valueInfo, config?)` 修改字段值。普通文本、数字、日期传 `{value: '...'}`；浏览和动态选项传 `{specialObj:[{id,name,data?}]}`，清空浏览传 `{specialObj:[]}`。固定选项可传 `{value: optionId}`；选项模板使用 `specialObj`。日期区间的值可为 `开始日期,结束日期`。人员范围对象可带 `type`，如 `user/dept/subcompany/organization/group/role/position/all`。附件除 id/name 外还需要来自附件模块的完整 `data` 对象，不能凭文件名伪造可预览附件。地理位置可附 `latitude/longitude`；某些特殊字段还用 `type/contentObj`。
+
+```js
+formSdk.changeFieldValue(amount, {value: '120.00'});
+formSdk.changeFieldValue(customer, {specialObj: [{id: customerId, name: customerName}]});
+formSdk.changeFieldValue(customer, {specialObj: []});
+formSdk.changeFieldValue(`${rate}_${firstRowId}`, {value: '0.13'});
+```
+
+第三参数可控制随赋值触发的处理：`dataLinkage`（字段联动、公式、钻取）、`viewLinkage`（显示联动）、`optionLinkage`、`dataValidate`、`jsApiChange`；对应值 `false` 表示不执行，默认按系统行为。该参数在 241001 及以后基线适用。需要在赋值后明确再次运行联动时，用 `triggerFieldAllLinkage(fieldMark)`，它会触发字段联动、函数公式、显示属性联动、数据钻取、选项联动等；明细字段须指定某行。250901 及以后可等待其 Promise。避免监听 A 又写 A 形成循环。
+
+## 显示属性与批量修改
+
+`changeFieldAttr(fieldMark, viewAttr)` 的属性码：`1` 只读、`2` 可编辑、`3` 必填、`4` 隐藏、`5` 隐藏行。明细字段标识作用于整列，`${field}_${rowId}` 作用于指定行。流程节点或权限锁定的只读状态，不能依靠此 API 强行变为可编辑。EXCEL 布局隐藏明细列时还要留意冻结标题/列。
+
+`changeSingleField(fieldMark, valueInfo, {viewAttr})` 同时改值和属性。`changeMoreField(changeDatas, changeVariable?)` 批量修改，两参数都是以字段标识为键的对象：
+
+```js
+formSdk.changeMoreField(
+  {[amount]: {value: '120.00'}, [customer]: {specialObj: [{id: customerId, name: customerName}]}},
+  {[amount]: {viewAttr: 1}}
+);
+```
+
+运行前检查标识非空、字段在当前布局可用、数据 Key 所在主/明细位置正确。读取 `getFieldObj` 对照实际值结构，再决定使用 `value` 还是 `specialObj`。

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

@@ -0,0 +1,116 @@
+# 表单布局 CSS 编写指南
+
+本篇用于**已创建的表单布局**：给指定布局的 PC 或移动端页面写 CSS。适用于表单引擎表单与流程表单的表格式、流式布局。表格式高级**模板**的 CSS 属于另一份配置，模板的网格和重复标记也不会由这里的 CSS 生成。
+
+## 能设置什么
+
+| 目标 | CSS 可处理的内容 | 先确认的配置或结构 |
+| --- | --- | --- |
+| 页面主题 | 页面区域的背景与文字颜色、主题变量、按钮和选中状态颜色 | 页面根容器及变量是否被当前组件读取 |
+| 标题与分组 | 标题颜色、字重、底线，分组标题装饰、背景、内外间距 | 表格式的单元格样式或流式的分组结构 |
+| 字段组件 | 输入框、文本域、下拉、日期、浏览框的背景、边框、字体、内边距；提示语和焦点状态 | 各组件实际画边框的包裹层；保留图标和操作标记 |
+| 明细表 | 表头色、标题对齐、边框、隔行色、悬停与聚焦行色 | 是否存在相应明细表 DOM；固定表头是否另有一张表 |
+| 响应状态 | `:hover`、`:focus-within`、`:checked` 等状态，以及 `@media` 下的样式 | PC 与移动端分别检查，不能假定结构一致 |
+
+CSS 只改变已有元素的呈现。字段顺序、主表与明细表的迭代、合并单元格、字段组件类型和表单数据仍在布局或表单配置中处理。表格式布局的列宽、行高、单元格边框优先在网格中设置；流式布局的区域排列优先在布局设置中完成。
+
+## 作用范围和写入
+
+布局 CSS 按**布局 ID + 终端**保存。CSS 文件中写普通选择器，例如 `.ebpage`；CLI 会给普通规则加当前页面的 `#ebpage_<pageId>` 前缀。不要自己写这个页面 ID，也不要复制模板编译后的 `#widget_…`、`.cell_…` 等生成标识。`@media`、`@supports` 中的普通选择器同样会加作用域；`@keyframes` 保持原样。需要被这份 CSS 修饰的动态元素应放在布局页面容器内，挂在 `document.body` 下的弹层不在此作用域内。
+
+```bash
+# 先读取当前 PC 布局代码，保存现有 CSS 供修改
+e10-cli form code layout read <表单objId> --app-id <应用ID> --layout-id <布局ID> --terminal PC
+
+# 将 CSS 文件写入该 PC 布局；JS 保持原状
+e10-cli form code layout set <表单objId> --app-id <应用ID> --layout-id <布局ID> --terminal PC --css <CSS文件>
+
+# 写入后回读
+e10-cli form code layout read <表单objId> --app-id <应用ID> --layout-id <布局ID> --terminal PC
+```
+
+流程表单对应 `e10-cli wf-form code layout read/set <formId> --layout-id <布局ID> --terminal PC|MOBILE [--css <CSS文件>]`，不需要 `--app-id`。移动端把 `--terminal` 改为 `MOBILE`，并针对该终端另写一份 CSS。`set --css` **整份替换**该布局、该终端原有 CSS；写入前先读出现有内容并合并到文件中。只传 `--css` 时已有 JS 保留。回读会核对源码和编译结果，随后仍需打开实际表单检查视觉效果。
+
+需要先审阅差异时，使用独立的 `preview/apply` 命令。先读出现有 CSS 并合并到候选文件，再生成预览；预览文件包含原文与候选全文、源码指纹及编译结果指纹。执行时沿用同一个 CSS 文件，布局或文件发生变化会阻断写入。只传 CSS 时 JS 保持原值；保存后独立回读源码与编译结果。
+
+```bash
+e10-cli form code layout preview <表单objId> --layout-id <布局ID> --terminal PC --css layout.css --out code-preview.json
+e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal PC --css layout.css --preview @code-preview.json --out code-result.json
+```
+
+流程表单把命令前缀换为 `wf-form code layout`，目标传 `formId`。两种方式都适用于表格式和流式布局；移动端改用 `--terminal MOBILE` 并单独预览。`read/set` 旧命令保持可用。
+
+## 通用写法
+
+### 主题与选择状态
+
+页面根节点存在 `.ebpage` 时，可集中设置主题变量；变量只对读取它的组件起作用。颜色和变量名称可参考表格式高级模板的 [CSS 指南](../template/advanced-css.md)，但应在目标布局验证实际状态。
+
+```css
+.ebpage {
+  --primary: #347fcb;
+  --btn-primary-hover-bg: #286daf;
+  --checkbox-active-border-color: var(--primary);
+  --checkbox-active-background-color: var(--primary);
+  --radio-active-border-color: var(--primary);
+  --radio-active-inner-background-color: var(--primary);
+  --input-focus-border-color: var(--primary);
+}
+```
+
+### 字段输入区域
+
+先看实际元素是输入框自身画线，还是其外层包裹层画线。以下是**表格式 PC 页面已识别的组件路径**，仅在目标布局存在相同 DOM 时复用；流式布局先检查对应组件结构再写选择器。
+
+```css
+/* 文字输入：只清除控件边框，保留表格单元格边线。 */
+.weapp-form-widget__Text .weapp-form-input-style {
+  border: none;
+  background: transparent;
+}
+
+/* 浏览框的额外包裹层：目标页面确有此层时使用。 */
+.weapp-form-widget-content-container .ui-browser-types-select-wrap .ui-input-suffix-wrap {
+  border: none;
+}
+```
+
+多行文本、日期、下拉、浏览框可能由 `textarea`、`.ui-input-wrap`、`.ui-select-input`、`.ui-browser` 或更外层绘制边框；逐个定位实际画线元素。避免对 `.ebpage input` 或 `.ebpage *` 一次性去边框，这会误伤选择标记、上传区和表格线。
+
+### 表格式布局的明细表
+
+以下规则针对已识别的表格式 PC 明细表结构。流式明细表只有在实际存在这些类和表格元素时才可复用。
+
+```css
+.weapp-form-detail-table-wrapper .excelTableView-content-excel-table tbody tr[data-id]:nth-child(even) > td {
+  background: #f7f9fc;
+}
+
+.weapp-form-detail-table-wrapper .excelTableView-content-excel-table tbody tr[data-id]:hover > td {
+  background: #e9f2fc;
+}
+
+.weapp-form-detail-table-wrapper .excelTableView-content-excel-table tbody tr[data-id]:focus-within > td {
+  background: #daebfa;
+}
+```
+
+明细表标题对齐与基础边框先用布局网格设置。需要 CSS 补充表头配色时，同时检查内容表与固定表头 `.excelTableView-content-excel-table-fixed-first-row`。把背景写到 `td` 上，是为了避免单元格自带背景遮住整行状态色。
+
+## 表格式与流式如何选规则
+
+| 对象 | 表格式布局 | 流式布局 |
+| --- | --- | --- |
+| 页面主题变量 | 可从 `.ebpage` 开始，检查组件是否读取变量 | 同样从实际页面根节点检查 |
+| 字段控件 | 核对 `.weapp-form-widget__…` 与内部包裹层 | 核对实际组件路径；相同 DOM 才复用 |
+| 字段与分组位置 | 改网格、标记和单元格配置 | 改流式布局配置 |
+| `table`、`td`、明细表规则 | 仅用于真实存在的表格与明细表 | 不把表格式选择器直接套到流式区域 |
+
+## 检查顺序
+
+1. 读取目标布局和终端的原 CSS，确认页面上确有要修改的元素及类名。
+2. 明确样式应落在页面、区域、网格单元格、组件包裹层还是输入元素；优先使用对应的布局配置，再写需要补充的 CSS。
+3. 写入完整 CSS 文件，回读源码与编译结果；不要把编译后的页面 ID 写回源码。
+4. 在实际表单中检查普通、只读、悬停、聚焦、选中及明细表滚动状态；移动端单独检查。
+
+模板 CSS 指南提供更多 **PC 表格式**组件路径与状态写法；它们是选择器参考，并非流式布局的 DOM 保证。布局源码的其他规则见[表单代码块配置指南](code-block-guide.md)。