weaver-e10-builder 1.6.8 → 1.6.9

package/skill-docs/references/form/guide-form-attachment-setting.md

@@ -2,15 +2,20 @@
 
 表单「附件设置」页控制附件文件存在哪里、能传什么、以及由附件创建文档时落在哪个目录。设置分**通用配置**和**字段级覆盖**两层：字段级未显式覆盖的项继承通用配置。
 
-## 三层对应关系
+## 两层对应关系
 
 | 界面 | 通用配置 | 字段级覆盖 |
 |---|---|---|
 | 附件/图片上传目录 | `folderId` + `folderIdBrowserValue` | 同名字段；`folderSelectType` 区分固定目录 / 选项关联 |
-| 关联文档 → 新建方式设置 | `addTypeConfig.types` | `docAddTypeConfig` |
-| 关联文档 → 新建文档存储位置 | `fixedDirectory.folderValue` | `docFixedDirectoryConfig` |
-| 上传格式 | `customLimitFormat` | 同名字段 |
-| 大小限制 / 启用 / 提示语 | `attmentSizeLimit` / `enableState` / `displayTip` | 同名字段 |
+| 关联文档 → 新建方式设置 | `addTypeConfig.types` | **无字段级**，只作用于通用层 |
+| 关联文档 → 新建文档存储位置 | `fixedDirectory.folderValue` | **无字段级**，只作用于通用层 |
+| 上传格式 | `customLimitFormat` | 同名字段；需同时标记 `limitType=1` |
+| 大小限制 | `attmentSizeLimit` | 同名字段；需同时标记 `sizeType=1` |
+| 附件显示（上传人/上传时间/文件大小等） | `displayTip` / `enableState` | `attachUploadUser` / `attachUploadTime` / `attachFileSize` / `forbinBatchDownload`；需同时标记 `otherType=1` |
+
+字段级覆盖只有**四类**：上传目录、上传格式、大小限制、附件显示。命令会按类型逐个保存，并把其余类型的既有覆盖一起带上，改一项不会把其他覆盖抹掉。
+
+**大小限制的取值**：`9` = 未选择（继承通用），`6` = 自定义（数值在 `customAttmentSize`），其余数字就是 MB 数。看到 `9` 不要当成 9MB。
 
 两个目录不要混：
 
@@ -63,20 +68,34 @@ e10-cli form attachment-setting set <appId> <objId> \
 e10-cli form attachment-setting set <appId> <objId> \
   --field <附件字段> --upload-mode option --option-field <选项字段>
 
-# 字段级的新建方式 / 存储位置 / 上传格式
+# 字段级上传格式 / 大小限制 / 附件显示
 e10-cli form attachment-setting set <appId> <objId> \
-  --field <附件字段> --doc-dir <目录ID> --doc-types WORD,markdown --formats @image
+  --field <附件字段> --formats @doc --max-size 15 \
+  --show-uploader on --show-upload-time on
+
+# 自定义大小、恢复继承
+e10-cli form attachment-setting set <appId> <objId> --field <附件字段> --max-size custom:20
+e10-cli form attachment-setting set <appId> <objId> --field <附件字段> --max-size none --formats none
 ```
 
 - `--field` 给了才是字段级覆盖；不给就是通用配置。
 - 固定目录必须同时给 `--upload-dir`；选项关联必须同时给 `--option-field`。
 - 字段级只写给出的项，未给出的项保持继承通用。
-- `--max-size` / `--enable` / `--display-tip` 当前只支持通用配置。
+- `--doc-dir` / `--doc-types` **只在通用层生效**；带 `--field` 会直接报错，不会静默丢弃。
+- `--enable` 只作用于通用层。
+
+| 字段级参数 | 说明 |
+|---|---|
+| `--formats` | 上传格式；`none` 恢复继承 |
+| `--max-size` | MB 数（如 `15`）、`custom:<MB>` 自定义、`none` 恢复继承 |
+| `--show-uploader` / `--show-upload-time` / `--show-file-size` | 附件区显示上传人 / 上传时间 / 文件大小 `on` / `off` |
+| `--forbid-batch-download` | 禁止批量下载 `on` / `off` |
+| `--display-tip` | 提示语 `on` / `off` |
 
 ## 查询目录与新建方式
 
 ```bash
-# 列出可用文档目录（系统知识库 + 公司/私有知识库）
+# 列出全部文档目录（系统知识库 + 公司/私有知识库，逐层遍历）
 e10-cli form attachment-setting folders
 e10-cli form attachment-setting folders --search 合同
 
@@ -84,12 +103,12 @@ e10-cli form attachment-setting folders --search 合同
 e10-cli form attachment-setting doc-types
 ```
 
-`folders` 输出目录 ID、标题和类型；`--upload-dir` / `--doc-dir` 可以直接写 ID，也可以写唯一名称或路径。名称匹配到多个时命令会报错并要求改用 ID。
+`folders` 输出目录 ID、完整路径标题和类型；`--upload-dir` / `--doc-dir` 可以直接写 ID，也可以写唯一名称或完整路径。名称匹配到多个时命令会报错并要求改用 ID。
 
 ## 注意事项
 
 1. **目录 ID 是长数字**，按字符串处理，不要转成 Number。
-2. **读回形状与写入形状不同**：读回的上传目录只在 `folderIdBrowserValue[0]` 里，写报文才带顶层 `folderId`；命令内部会补齐，不要手工拼报文。
-3. **保存顺序**：先字段级列表，再通用配置；两条都成功后再回读校验。
+2. **读回形状与写入形状不同**：字段列表回读只给 `folderId`，标题在单字段回读的 `folderIdBrowserValue` 里；命令内部会补齐，不要手工拼报文。
+3. **字段级保存按类型分开**：上传目录、格式、大小、附件显示各是一次保存，每次都要带上当前完整状态与四类覆盖标记；只提交单项会把其他覆盖抹掉。命令已处理，不要用其它方式单独拼单类型报文。
 4. **字段级覆盖优先于通用配置**：字段级把上传目录设成固定目录但没选具体目录，会覆盖掉通用的有效目录。
 5. 命令在保存后会逐项回读；回读不一致会直接报错，不会静默成功。

package/skill-docs/references/form/guide-form-layout-planning.md

@@ -76,7 +76,7 @@ e10-cli form layout save-as-template <objId> --view-id <布局ID> --name <模板
 e10-cli form layout save-as-template <流程表单formId> --module workflow --view-id <布局ID> --name <模板名>
 ```
 
-此操作从指定布局读取 `formStyle` 并创建流式样式模板，默认禁用；需要立即可选用时加 `--enabled`。业务字段和布局组件不会一起保存。表格式布局不能用这条命令直接另存；模板的其他操作见[布局样式模板总览](form-template/style-templates.md)。
+此操作从指定布局读取 `formStyle` 并创建流式样式模板，默认禁用；需要立即可选用时加 `--enabled`。业务字段和布局组件不会一起保存。表格式布局不能用这条命令直接另存；模板的其他操作见[布局样式模板总览](layout/template/template-guide.md)。
 
 ## 图片与 Excel 源样式还原
 

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

@@ -27,7 +27,7 @@
 
 | 需求范围 | 入口 | 特点 |
 |---|---|---|
-| 只对某个布局、某个终端生效 | 布局源码：`form code layout set` / `wf-form code layout set` | 随布局和终端加载；CSS 自动限定在 `#ebpage_<pageId>`；JS 带 `pageId` 生效条件 |
+| 只对某个布局、某个终端生效 | 布局源码：`form code layout set` / `wf-form code layout set` | 随布局和终端加载；CSS 默认以 `#ebpage_<pageId>` 为作用域，需要覆盖表头等页面根外元素时可显式选 `--css-scope form` 并限定目标布局；JS 带 `pageId` 生效条件 |
 | 同一表单的所有布局/终端都要生效 | 表单级 ecode：`form code ecode ...` | 不随布局切换；需要自己判断当前表单/数据上下文 |
 | 应用级或全局页面逻辑 | 全局 ecode / 页面入口 | 不在本指南的表单布局命令范围内；使用 `onFormReady` 等全局事件并按 formId/module 限定 |
 
@@ -127,16 +127,16 @@ recalculate();
 
 | 范围 | 读取 | 写入 |
 |---|---|---|
-| 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 表单布局 | `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 <文件>) [--css-scope page\|form]` |
+| 原生工作流程表单布局 | `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 <文件>) [--css-scope page\|form]` |
 | 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 仍使用上表的独立命令。
+布局代码需要差异预览时，用独立的 `form code layout preview/apply` 或 `wf-form code layout preview/apply`。两步传相同的布局 ID、终端、`--js`／`--css` 文件及 `--css-scope page|form`；预览使用 `--out <文件>` 保存完整报告，应用时传 `--preview @<文件>`。预览会编译候选代码并列出被替换的 JS/CSS 原文；应用会检查源文件和布局未变化，单次保存后独立回读。只传一种文件时另一种代码保持不变。无源码变化时不发送保存请求。表单级 ecode 仍使用上表的独立命令。
 
-布局源码写入时，CLI 按当前终端页面的 `pageId` 生成 JS 生效条件，并把 CSS 选择器限定在当前 `#ebpage_<pageId>` 内。需要由 JS 动态插入且使用布局 CSS 的元素，应挂在该页面容器内；挂到 `document.body` 的元素不受这份布局 CSS 修饰。写入后用 `layout read` 核对 JS/CSS 原文、页面条件和编译结果，再打开实际表单页面检查运行效果。
+布局源码写入时，CLI 按当前终端页面的 `pageId` 生成 JS 生效条件。CSS 默认为 `--css-scope page`，普通规则编译到 `#ebpage_<pageId>` 内；当表头等目标位于页面根外、表单根内时，可用 `--css-scope form`，但源码选择器还须限定当前布局或页面，不能把表单根范围误当成布局隔离。挂到表单根外（例如 `document.body`）的弹层不受这两种作用域修饰。写入后用 `layout read` 核对 JS/CSS 原文、页面条件和编译结果，再打开实际表单页面检查运行效果；固定类名和盒模型处理见[布局 CSS 指南](layout-css.md)。
 
 布局 CSS 的可设置内容、表格式与流式布局的选择器边界及完整写入示例，见[表单布局 CSS 编写指南](layout-css.md)。
 

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

@@ -2,6 +2,8 @@
 
 本篇用于**已创建的表单布局**：给指定布局的 PC 或移动端页面写 CSS。适用于表单引擎表单与流程表单的表格式、流式布局。表格式高级**模板**的 CSS 属于另一份配置，模板的网格和重复标记也不会由这里的 CSS 生成。
 
+按需求查阅：页面背景、表头或作用域见[作用范围和写入](#作用范围和写入)；已知组件类名见[固定类名索引](#固定类名索引)；填色不满、越框或层叠问题见[盒模型与背景层](#盒模型与背景层)；明细表见[流式 PC 明细表](#流式-pc-明细表标题格与单元格)和[表格式布局的明细表](#表格式布局的明细表)；不生效时按[检查顺序](#检查顺序)排查。
+
 ## 能设置什么
 
 | 目标 | CSS 可处理的内容 | 先确认的配置或结构 |
@@ -16,7 +18,9 @@ CSS 只改变已有元素的呈现。字段顺序、主表与明细表的迭代
 
 ## 作用范围和写入
 
-布局 CSS 按**布局 ID + 终端**保存。CSS 文件中写普通选择器，例如 `.ebpage`；CLI 会给普通规则加当前页面的 `#ebpage_<pageId>` 前缀。不要自己写这个页面 ID，也不要复制模板编译后的 `#widget_…`、`.cell_…` 等生成标识。`@media`、`@supports` 中的普通选择器同样会加作用域；`@keyframes` 保持原样。需要被这份 CSS 修饰的动态元素应放在布局页面容器内，挂在 `document.body` 下的弹层不在此作用域内。
+布局 CSS 按**布局 ID + 终端**保存。`--css-scope page` 为默认值：CLI 将普通规则编译为 `#ebpage_<pageId> <选择器>`，适合页面容器**内部**的元素。表头等元素若位于 `#ebpage_<pageId>` 的外部或与其同级，默认作用域无法选中；此时可明确使用 `--css-scope form`，编译为 `#form_<formId> <选择器>`。代码仍保存在指定布局和终端，但 `form` 根范围较宽，源码选择器必须再限定目标布局或页面，避免影响同一表单的其他布局。若 CSS 同时包含表头和内容区规则，切换作用域时应检查**整份文件**，不能只改一条规则。
+
+作用域前缀是祖先选择器，不会使后代规则反向选中祖先或兄弟元素，也不会命中挂到布局根之外的弹层。默认 `page` 模式下，源码应写页面根**内部**的普通选择器；不要把 `.ebpage`、`#ebpage_<pageId>` 作为后代选择器原样写入，因为编译后会形成 `#ebpage_<pageId> .ebpage` 或重复根 ID，无法匹配根元素本身。`form` 模式需要定位当前布局时，可以在这份专属 CSS 中使用从 `layout read` 和 DOM 获取的实际布局类或页面根 ID；这些动态标识不能写进可复用模板。`@media`、`@supports` 内的普通规则也会加前缀，`@keyframes` 保持原样。
 
 ```bash
 # 先读取当前 PC 布局代码，保存现有 CSS 供修改
@@ -25,29 +29,79 @@ e10-cli form code layout read <表单objId> --app-id <应用ID> --layout-id <布
 # 将 CSS 文件写入该 PC 布局；JS 保持原状
 e10-cli form code layout set <表单objId> --app-id <应用ID> --layout-id <布局ID> --terminal PC --css <CSS文件>
 
+# 当目标位于页面根之外、但仍在表单根内时，显式改用 form 作用域
+e10-cli form code layout set <表单objId> --app-id <应用ID> --layout-id <布局ID> --terminal PC --css <CSS文件> --css-scope form
+
 # 写入后回读
 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 保留。回读会核对源码和编译结果，随后仍需打开实际表单检查视觉效果。
+流程表单对应 `e10-cli wf-form code layout read/set <formId> --layout-id <布局ID> --terminal PC|MOBILE [--css <CSS文件>] [--css-scope page|form]`，不需要 `--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
+e10-cli form code layout preview <表单objId> --layout-id <布局ID> --terminal PC --css layout.css --css-scope page --out code-preview.json
+e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal PC --css layout.css --css-scope page --preview @code-preview.json --out code-result.json
+```
+
+两步必须使用相同的 `--css-scope`；若选 `form`，两步都改为 `--css-scope form`。流程表单把命令前缀换为 `wf-form code layout`，目标传 `formId`。两种方式都适用于表格式和流式布局；移动端改用 `--terminal MOBILE` 并单独预览。`read/set` 旧命令保持可用。
+
+`form` 模式的源码可以同时修饰表头和内容区，但每条规则需明确落点。下例的 `PAGE_ID` 必须替换成目标终端页面的真实 `pageId`，不是布局 ID；表头类的拼写以目标运行页为准：
+
+```css
+/* 表头在页面根外：用表头自带的布局类限定。 */
+.weapp-form-header.weapp-form-layout__PAGE_ID { background-color: #f3f7ff; }
+
+/* 内容区仍限定到该页面根，避免碰到同表单其他布局。 */
+#ebpage_PAGE_ID .weapp-form-widget__Collapse { border-radius: 6px; }
 ```
 
-流程表单把命令前缀换为 `wf-form code layout`，目标传 `formId`。两种方式都适用于表格式和流式布局；移动端改用 `--terminal MOBILE` 并单独预览。`read/set` 旧命令保持可用。
+## 固定类名索引
+
+以下是 PC 表单布局常见的运行页类名。同一字段在编辑、只读、必填和不同布局中可能增减内层节点；通常先用“组件类型外壳 + 内部类”限定目标。`#widget_<字段ID>`、`#ebpage_<pageId>`、`.weapp-form-layout__<pageId>` 中的数字由资源生成，不是固定类名。`--` 与 `__` 不可互换，例如字段列外壳是 `.weapp-form-widget--column`。
+
+| 想修改的区域 | 可直接查找的类名/层级 | 应修改的层与注意点 |
+| --- | --- | --- |
+| 页面与布局 | `.weapp-form`、`.weapp-form-header`、`.weapp-form-content`、`.weapp-de-flow-render`、`.ebdpage-content`、`.weapp-ebpv-styled-flow` | 表头可能在 `#ebpage` 外；页面底色先找实际绘制背景的层。`.ebdpage-content` 含字母 `d`。 |
+| 通用字段 | `.weapp-form-widget`、`.weapp-form-field`、`.weapp-form-widget--column`、`.weapp-form-has-custom-style` | 字段外壳可能自带不透明背景，覆盖上层分组底色；不要把列外壳写成 `__column`。 |
+| 字段标题与内容 | `.weapp-form-widget-title`、`.weapp-form-widget-content`、`.weapp-form-widget-content--FLOW`、`.weapp-form-widget-content-container` | 内容层可有左右 padding，内部容器还可能有上下 padding、边框；要填满可见框，应分别判断边框和内边距所在层。 |
+| 折叠分组 | `.weapp-form-widget__Collapse`、`.weapp-form-collapse-wrapper`、`.weapp-form-collapse`、`.ui-collapse-panel`、`.ui-collapse-panel__title`、`.ui-collapse-panel__content-box`、`.ui-collapse-panel__content` | 整卡片、标题和内容为不同盒子；若字段外壳有白底，还需单独处理字段外壳。 |
+| 单行文本／数值／金额 | `.weapp-form-widget__Text`、`.weapp-form-widget__Number`、`.weapp-form-widget__Money` 下的 `.weapp-form-input-wrapper` 与 `input` | 背景可被内部 input 覆盖；数字右对齐需作用到实际输入节点。 |
+| 多行文本 | `.weapp-form-widget__TextArea .weapp-form-textarea-wrapper textarea` | 内部 textarea 的背景、padding、高度与外层内容盒分别处理。 |
+| 日期／下拉 | `.weapp-form-widget__Date .weapp-form-date-wrapper`、`.weapp-form-widget__Select .weapp-form-select-wrapper`、`.ui-select-input` | 日期输入节点可能遮住 wrapper 底色；下拉可见边框也可能在 `.weapp-form-widget-content-container`。保留日历图标、下拉箭头。 |
+| 单选／复选 | `.weapp-form-widget__RadioBox`、`.weapp-form-widget__CheckBox`、`.weapp-form-option-wrapper` | 选项 wrapper 不一定撑满内容盒；要让整框填色，检查 wrapper 宽度和 `box-sizing`，不能只给单个选项上色。 |
+| 人员等浏览 | `.weapp-form-widget__Employee`、`.weapp-form-widget-content-container`、`.ui-browser` | 字段本体和弹窗可能不在同一作用域；不以字段底色规则改弹窗。 |
+| 附件／图片 | `.weapp-form-file-upload-wrapper`、`.weapp-form-image-upload`、`.weapp-form-image-upload-wrapper` | 文件区与图片缩略图是不同结构；图片上传可直接在页面作用域下定位 `.weapp-form-image-upload`，先检查图像字段是否真有该节点。 |
+| 流式明细 | `.weapp-form-detail-table--FLOW`、`.weapp-form-detail-table-title`、`.ui-table-grid-thead th.weapp-form-detail-table-column`、`.weapp-form-detail-table-field-header` | 整列表头背景在 `th`，文字在内层；滚动表头、数据行另核对。 |
+| 表格式明细 | `.weapp-form-detail-table-wrapper`、`.excelTableView-content-excel-table`、`.excelTableView-content-excel-table-fixed-first-row` | 普通内容表和固定表头可能分开；行色写到 `td`，同时看列宽与悬停。 |
+
+先按索引使用固定类名；只有目标页面不具备该节点、出现不同终端结构，或样式仍被其他盒子覆盖时，才沿 Elements 树定位新层。设计器的 `.weapp-formbuilder-*` 不直接当作运行页类名。更多组件类型的源码线索见[表格式高级模板 CSS 指南](../template/advanced-css.md)，但模板与布局源码不是同一配置。
+
+## 盒模型与背景层
+
+一个字段通常经过“分组卡片 → 字段外壳 → 内容层 → 内部容器 → 控件 wrapper → `input`/`textarea`”多层。`margin` 在边框外，`padding` 在元素边框内，元素的背景会绘制到自身 padding 区；子元素若有不透明背景，又会盖住父元素。想让颜色填满**可见框**，先确定画边框的元素，再检查它的 padding 和内部控件，而不是直接给整张字段外壳或内容层铺色。
+
+流式字段的 `.weapp-form-widget-content` 可带左右间距，`.weapp-form-widget-content-container` 可另有上下 padding 与边框。若目标布局确需取消框内留白，可只对目标字段类型调整对应层，不对所有字段一刀切。单选／复选的选项 wrapper 若只包裹文字，设 `width:100%; box-sizing:border-box` 才能让其底色覆盖整框；日期等控件则需核对内部 `input` 是否另有白底。修改 padding 后检查必填标记、图标、焦点边框、下拉与弹层的点击区域及控件高度。
+
+```css
+/* 下面只示范按组件类型限定层级；按目标页面的盒模型决定是否需要这些调整。 */
+.weapp-form-widget__Select .weapp-form-widget-content--FLOW { padding-inline: 0; }
+.weapp-form-widget__Select .weapp-form-widget-content-container { padding: 0; }
+.weapp-form-widget__RadioBox .weapp-form-option-wrapper,
+.weapp-form-widget__CheckBox .weapp-form-option-wrapper { width: 100%; box-sizing: border-box; }
+```
+
+若改色超出边框，通常是选中了比画边框的盒子更外侧的容器；撤回那层背景，改定位实际边框及其内部。若颜色只在底边露出，检查内部输入节点是否覆盖了 wrapper。若分组仅标题变色，沿 `.ui-collapse-panel` 到字段外壳逐层查不透明背景。不要靠不断追加 `!important` 猜测层级。
 
 ## 通用写法
 
 ### 主题与选择状态
 
-页面根节点存在 `.ebpage` 时，可集中设置主题变量；变量只对读取它的组件起作用。颜色和变量名称可参考表格式高级模板的 [CSS 指南](../template/advanced-css.md)，但应在目标布局验证实际状态。
+主题变量应设置在能包含目标控件的实际元素上，且只对读取它的组件起作用。默认 `page` 作用域不能用 `.ebpage` 去选中 `#ebpage_<pageId>` 本身；可将变量放在页面根**内部**的容器，或在 `form` 作用域下精确选中页面根。颜色和变量名称可参考表格式高级模板的 [CSS 指南](../template/advanced-css.md)，但应在目标布局核对变量是否被组件读取。
 
 ```css
-.ebpage {
+.ebdpage-content {
   --primary: #347fcb;
   --btn-primary-hover-bg: #286daf;
   --checkbox-active-border-color: var(--primary);
@@ -60,7 +114,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 ### 字段输入区域
 
-先看实际元素是输入框自身画线，还是其外层包裹层画线。以下是**表格式 PC 页面已识别的组件路径**，仅在目标布局存在相同 DOM 时复用；流式布局先检查对应组件结构再写选择器。
+先看实际元素是输入框自身画线，还是其外层包裹层画线。以下是**表格式 PC 常用的组件路径**，仅在目标布局存在相同 DOM 时复用；流式布局优先查上面的固定类名索引。
 
 ```css
 /* 文字输入：只清除控件边框，保留表格单元格边线。 */
@@ -79,7 +133,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 ### 流式 PC 布局：分组与下拉框
 
-已确认的流式 PC 页面以 `.weapp-ebpv-styled-flow` 标识布局容器。分组使用 `.weapp-form-widget__Collapse`；标题下方的蓝线是 `.weapp-form-collapse .ui-collapse-panel__title` 的 `border-bottom`，已观察到 `1px solid #1C69DB`。这条线也可由分组标题的布局样式设置产生；需要统一外观时优先检查分组标题配置，不要把设计器选中时的蓝色虚线框当成运行时边框。
+流式 PC 布局可从 `.weapp-ebpv-styled-flow` 定位内容容器。分组使用 `.weapp-form-widget__Collapse`；标题下方的线可由 `.weapp-form-collapse .ui-collapse-panel__title` 的 `border-bottom` 或分组标题的布局样式生成。需要统一外观时先检查内置分组标题设置，不要把设计器选中时的虚线框当成运行时边框。若要改变**整张分组卡片**，需区分外壳、面板、标题、内容和字段外壳；给标题着色不会自动改变卡片内容背景。
 
 下拉字段外层带 `.weapp-form-widget__Select`。实际画出灰色外框的是其 `.weapp-form-widget-content-container`：四侧计算样式均为 `1px solid #E2E2E2`。内部的 `.ui-select-input` 和 `.ui-input-wrap.ui-select-input` 四侧边框为 `none`；只修改内部节点的 `border` 无法替换可见外框。若目标布局需要给下拉外框单独配色，可在布局 CSS 中限定字段类型：
 
@@ -89,11 +143,37 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 }
 ```
 
-此选择器依据页面 DOM 和计算样式确定，写入后的覆盖效果仍需在目标布局检查。不要把具体 `#widget_…` 或 `.weapp-form-layout_…` 的生成 ID 写进可复用规则。流式明细表已观察到 `.weapp-form-detail-table--FLOW`、`.weapp-form-detail-table-field-header` 和 `td.weapp-form-detail-table-column`；表头和格线的绘制节点尚需分别核对，不能直接套用表格式的 `.excelTableView-content-excel-table` 规则。
+下拉外框可能由该层绘制，写入后仍需检查实际计算样式。不要把具体 `#widget_…` 或 `.weapp-form-layout_…` 的生成 ID 写进可复用规则。流式明细表应按运行页的表头结构选择 `th`，不要照搬设计器中的结构。
+
+### 流式 PC 明细表：标题格与单元格
+
+在流式明细的运行页，`.weapp-form-detail-table--FLOW` 限定明细表，`.weapp-form-detail-table-title` 是明细标题。表头整格通常由 `.ui-table-grid-thead` 中的 `th.weapp-form-detail-table-column` 绘制，标题文字位于其子元素 `.weapp-form-detail-table-field-header`。要设置整格背景和下沿色带，应改 `th`，不要只改内部文字层：
+
+```css
+.weapp-form-detail-table--FLOW .weapp-form-detail-table-title {
+  color: #154a78;
+  font-weight: 700;
+}
+
+.weapp-form-detail-table--FLOW .ui-table-grid-thead th.weapp-form-detail-table-column {
+  background-color: #dff3ea !important;
+  color: #145c43;
+  box-shadow: inset 0 -3px #168a61 !important;
+  border-left: 1px solid #8dcbb0;
+}
+
+.weapp-form-detail-table--FLOW .ui-table-grid-thead th.weapp-form-detail-table-column .weapp-form-detail-table-field-header {
+  background-color: transparent;
+  color: inherit;
+  border: 0;
+}
+```
+
+该规则针对字段表头，不改变左侧勾选列。使用到其他表单时，检查目标页面是否采用相同运行时结构；保存后检查表头和滚动区域。默认 `page` 模式会自动加 `#ebpage_<pageId>` 作用域；若已选 `form`，则在源码中自行限定页面根。
 
 ### 表格式布局的明细表
 
-以下规则针对已识别的表格式 PC 明细表结构。流式明细表只有在实际存在这些类和表格元素时才可复用。
+以下规则针对表格式 PC 明细表结构。流式明细表只有在实际存在这些类和表格元素时才可复用。
 
 ```css
 .weapp-form-detail-table-wrapper .excelTableView-content-excel-table tbody tr[data-id]:nth-child(even) > td {
@@ -113,7 +193,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 ## 常见样式场景
 
-以下按视觉目标选择写法。除了前文已识别的表格式组件路径，`.wea-form-*`、`.wea-detail-*` 等类名只作结构示意；使用前要从目标布局的实际 DOM 中取得选择器。优先用布局样式、排版、网格和字段属性完成平台已有的设置，CSS 负责其余视觉细节。
+以下按视觉目标选择写法。除了前文列出的固定组件路径，`.wea-form-*`、`.wea-detail-*` 等类名只作结构示意，不能直接作为 E10 表单运行页选择器。优先用布局样式、排版、网格和字段属性完成平台已有的设置，CSS 负责其余视觉细节。
 
 | 场景 | 写法与检查点 |
 | --- | --- |
@@ -125,7 +205,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 | 必填与错误提示 | 可强化已有必填标记和错误状态的颜色、边框；先确认平台是否已经绘制星号，避免用 `::before` 重复生成。CSS 不代替必填和校验规则。 |
 | 打印 | 用 `@media print` 隐藏实际页面的工具栏与操作按钮，并检查表头对比度、分页、固定表头及打印预览；不要假定屏幕上的按钮类名适用于打印页面。 |
 
-例如，已确认目标布局存在 `.wea-url > span > p` 时，可在该布局的 CSS 文件中加入：
+例如，目标布局确实存在 `.wea-url > span > p` 时，可在该布局的 CSS 文件中加入：
 
 ```css
 .wea-url > span > p {
@@ -142,7 +222,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 | 对象 | 表格式布局 | 流式布局 |
 | --- | --- | --- |
-| 页面主题变量 | 可从 `.ebpage` 开始，检查组件是否读取变量 | 同样从实际页面根节点检查 |
+| 页面主题变量 | 默认 `page` 作用域下从页面根内部容器设置；改页面根本体则使用 `form` 模式 | 同样先定位实际根及变量读取范围 |
 | 字段控件 | 核对 `.weapp-form-widget__…` 与内部包裹层 | 核对实际组件路径；相同 DOM 才复用 |
 | 字段与分组位置 | 改网格、标记和单元格配置 | 改流式布局配置 |
 | `table`、`td`、明细表规则 | 仅用于真实存在的表格与明细表 | 不把表格式选择器直接套到流式区域 |
@@ -151,7 +231,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 1. 读取目标布局和终端的原 CSS，确认页面上确有要修改的元素及类名。
 2. 明确样式应落在页面、区域、网格单元格、组件包裹层还是输入元素；优先使用对应的布局配置，再写需要补充的 CSS。
-3. 写入完整 CSS 文件，回读源码与编译结果；不要把编译后的页面 ID 写回源码。
+3. 写入完整 CSS 文件，回读源码与编译结果；默认 `page` 模式不要复制编译前缀，`form` 模式需要的页面标识须从目标布局获取并仅用于该布局专属文件。
 4. 在实际表单中检查普通、只读、悬停、聚焦、选中及明细表滚动状态；移动端单独检查。
 
 模板 CSS 指南提供更多 **PC 表格式**组件路径与状态写法；它们是选择器参考，并非流式布局的 DOM 保证。布局源码的其他规则见[表单代码块配置指南](code-block-guide.md)。

package/skill-docs/references/form/layout/template/advanced.md

@@ -320,6 +320,8 @@ e10-cli form-engine layout-template advanced style update <模板ID> --config @l
 
 更新命令只修改写出的设置，保留其他设置与组件关联；系统模板不可编辑。新建和更新都会保存后回读，并生成一次**不落库**的应用预览。输出中的 `id` 是已保存的模板 ID，`preview.persisted=false` 仅表示预览未保存。要将模板用于实际表单，按[总览中的应用步骤](template-guide.md)操作。
 
+同一视觉位置可能由网格单元格样式、`formStyle.styleConfig` 和 CSS 分别绘制；它们作用的 DOM 层不同，不能仅按属性名推断冲突。出现重复边线或背景时，分别读取 `advanced grid show <模板ID>`、`advanced style show <模板ID>`、`advanced css show <模板ID>`，确认目标元素与生效范围后只保留所需绘制层。`advanced export` 中的 `formStyle.styleConfig` 是 JSON 字符串，检查时需解析其内容；不要把字符串未展开误认为未配置。
+
 需要拆分已有合并区域时，在网格配置中写入 `"split":[{"row":8,"col":0}]`，坐标是该合并区域的左上角。`merge` 则写入 `row`、`col`、`rowCount`、`colCount`；两者都可以与 `cells`、`rowHeights`、`columns` 一起提交。
 
 ### 启用、禁用与删除

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

@@ -13,6 +13,10 @@ e10-cli wf-form layout init <formId> --layout-id <布局ID>
 
 `wf-form layout init` 按目标布局类型重建排版；不传 `--layout-id` 则处理默认布局。需要覆盖字段只读、必填或独占一行时，可按该命令的选项设置；只调整运行时字段属性可查看 `wf-form field-prop`，它同样会经初始化保存，应先核对当前分组、排版和目标布局。
 
+字段分组由 `wf-form group <formId> --groups @groups.json` 创建。EXCEL 向平台提交平铺字段和分组 ID，由平台生成 Collapse 与子网格；FLOW 按该表单全部已分配分组组装 Fold 容器，新增一组时保留其他分组。`wf-form group` 与 `wf-form field-prop` 都会重建默认布局。若当前布局不是系统默认模板效果，必须显式传 `--style-template <当前模板名称或ID>`；未传时命令会在写入前中止，避免静默覆盖样式。指定模板后仍要回读排版与样式，已有手工微调可能被重建覆盖。普通字段的 `required/readOnly/singleRow` 通过 `form layout inspect <formId> --module workflow --id-type form` 查看布局组件配置；`wf-form permission get` 查询的是另一层表单级权限，不能用它验证布局字段属性。
+
+`wf-form add-field`、`add-fields` 默认也会自动重建布局，`add-detail-table --init` 同理；已有自定义模板时需传 `--style-template <当前模板名称或ID>`，否则会在创建字段或明细表之前停止。建字段时可用 `--no-init` 只保存字段，再单独审阅并初始化；在此之前新增字段不会自动进入布局。自动重建失败时命令会以失败状态退出，并说明字段可能已创建、布局尚未确认。
+
 应用样式模板时，优先使用审阅式命令。它按目标 PC 布局的 `FLOW`／`EXCEL` 类型解析已启用的流式或高级表格式模板；表格式简易模板使用 `--easy-template`。预览不保存，执行前会重新核对布局、字段配置及模板样式，执行后独立回读组件和可核对的模板效果：
 
 ```bash
@@ -68,6 +72,12 @@ e10-cli wf-form layout add-system-field <formId> --all          # 目录里的
 
 原生流程表单与 eb 表关联流程的表单都适用：传 `--workflow-id`，命令按工作流自动判定走哪套接口。
 
+应用预览时须重复预览所用的布局、模板和字段选项；CLI 会指出不一致的选项名，避免执行与预览不同的重建。已有 EXCEL 折叠分组时不要传 `--no-generate-collapse`：它会使分组字段失去承载子网格，CLI 会在写入前阻断。表格式布局回读还会检查重复分组与字段父容器的 workbook 子网格；`saved:true` 说明这些可静态检查的结构通过，不等同浏览器视觉验收。
+
+读取原生流程表单布局使用 `form layout inspect <formId> --module workflow --id-type form`；`form layout read` 的参数是 EB 表单 `objId`，不能直接传流程 `formId`。
+
+`wf-form edit-field` 仅适用于普通字段 ID。明细表的 `subFormId` 是容器 ID，不能交给它修改标题；当前 CLI 尚无已验证的明细表标题修改命令，不要改写普通字段接口报文来猜测保存方式。
+
 删除指定流程表单布局使用：
 
 ```bash

package/skill-docs/references/menu/system-menus.md

@@ -5,6 +5,27 @@
 > **移动端菜单是另一套记录**：同一个 `savePublishMenu` 接口，只把 `terminalType` 换成 `H5`；页面绑定与 `menuUrl` 与 PC 相同。菜单命令统一用 `--terminal mobile` 指定移动端（缺省 PC），两端互不影响。
 > 移动端**内置系统页**的 URL 尚未整理，不要自行编造。
 
+## 别把对象页面加成外链
+
+`menu add` 写的是 LINK 菜单。平台自己的页面地址（`/sp/ebdfpage/viewport/<viewId>` 台账、`/sp/ebdfpage/card/1/<objId>/0` 表单新建页）当外链写进去只会存成一串 URL：设计器「链接地址」显示文本而不是「数据列表: 表单名」标签，移动端拿不到视图绑定，打开是空列表。
+
+- 台账（数据列表）入口 → `menu add-table <appId> <表单 objId>`
+- 表单发起入口 → `menu add-start <appId> <表单 objId>`
+
+`menu add` 遇到这两类地址会直接拒绝；确实要当外链才加 `--as-link`。
+
+## 把 PC 菜单同步到移动端
+
+```bash
+e10-cli menu sync <appId>
+```
+
+- 平台原生能力：「是否确认将PC端菜单同步至移动端？（此同步操作会覆盖已添加的菜单配置）」。
+- 同步会**整体覆盖**移动端菜单：移动端单独加过、PC 上没有的菜单会被清掉。
+- 同步范围是 PC 端的**业务菜单**（目录、外链、嵌套都带过去，顺序与层级照搬）；「设置」「回收站」这类系统菜单两端各管各的，不参与同步。
+- 命令保存后会回读移动端，与 PC 端逐条比对路径、层级与顺序；对不上会报错并点名缺失/多余项，不会把「没同步」说成成功。
+- PC 端一条业务菜单都没有时命令会拒跑（否则等于清空移动端）；确认要清空加 `--force`。
+
 ---
 
 ## PC 端菜单

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

@@ -1,141 +0,0 @@
-# 表单代码块配置指南
-
-本指南用于把表单引擎 JSSDK 作为一项可规划、可实施的表单功能配置。适用于 EB 表单和原生工作流程表单的布局源码；表单级 ecode、流程级或应用级 ecode 须按实际入口和生效范围另行选择。先确定代码放置层级、布局与终端，再按专题读取写法。各专题包含必要参数和可改用的代码，不依赖原始技术文档。
-
-## 适用场景
-
-平台内置的字段联动、公式、查重、校验、视图和流程配置能表达需求时，优先用平台配置；以下情况适合使用表单代码块：
-
-- 内置配置无法表达的条件组合、跨字段计算、动态属性或状态流转；
-- 需要在用户输入、明细增删、保存等动作前后实时响应、校验、提示或阻断；
-- 需要对明细行做即时汇总、占比、分组、父子归属或按条件筛选；
-- 需要控制选项、日期范围、浏览参数、页签等控件行为；
-- 需要复写字段组件渲染、追加字段内容或处理字段区域事件；
-- 需要在表单载入时做初始化、补全、规范化或默认值处理。
-
-## 代码放在哪一层
-
-| 需求范围 | 入口 | 特点 |
-|---|---|---|
-| 只对某个布局、某个终端生效 | 布局源码：`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` | [基础与字段](ref-foundations-fields.md) |
-| 字段联动 | A 变化写 B；跨字段计算；空值/清空；防循环 | `bindFieldChangeEvent`、`getFieldValue`、`changeFieldValue`、`triggerFieldAllLinkage` | [基础与字段](ref-foundations-fields.md)、[事件与校验](ref-events-validation.md) |
-| 动态属性 | 按状态/角色/条件切换只读、可编辑、必填、隐藏、隐藏行 | `changeFieldAttr`、`changeSingleField`、`changeMoreField` | [基础与字段](ref-foundations-fields.md) |
-| 保存前校验 | 阻断保存并提示；通过/失败回调；异步校验 | `registerCheckEvent(OPER_SAVE)`、`stop({msg})` | [事件与校验](ref-events-validation.md) |
-| 明细计算 | 金额合计、占比、分组汇总、父子明细回写 | `getDetailData`、`getDetailAllRowIndexStr`、`addDetailRow` / `delDetailRow` | [明细操作](ref-details.md) |
-| 明细事件 | 增行/删行/改值后重算；行显示、勾选、排序 | `ACTION_ADDROW` / `ACTION_DELROW`、`controlDetailRowDisplay`、`checkDetailRow` | [明细操作](ref-details.md) |
-| 控件行为 | 日期范围、选项过滤/禁用、浏览参数、页签切换 | `controlDateRange`、`controlSelectOption`、`controlOptionDisable`、`appendBrowserDataUrlParam`、`switchTabItem` | [特定控件](ref-controls.md) |
-| 交互反馈 | 消息、确认框、加载、必填检查、刷新、关闭提示 | `window.WeFormSDK.showMessage/showConfirm/getLoadingGlobal`、`verifyFormRequired`、`reloadPage` | [组件与全局操作](ref-ui-global.md) |
-| 字段组件复写 | 替换/追加字段内容、局部渲染、字段区域事件 | `proxyFieldComp`、`afterFieldComp`、`proxyFieldContentComp`、`bindFieldAction` | [组件与全局操作](ref-ui-global.md) |
-| 扩展通信 | 插件接口、父子页面 `postMessage`、跨组件协作 | `pluginGet` / `pluginExecute`、`window.opener`、`postMessage` | [组件与全局操作](ref-ui-global.md) |
-| 现成业务模式 | 明细人员汇总去重、按条件合并、分组同步、占比 | 见案例组合 | [效果案例](ref-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，并从已建资源读取。
-
-## 按效果查专题
-
-| 要实现的效果 | 必读文档 |
-|---|---|
-| 初始化、定位字段、值结构、环境基线 | [基础与字段](ref-foundations-fields.md) |
-| 保存前校验、明细行拦截、字段变化与联动事件 | [事件与校验](ref-events-validation.md) |
-| 明细行增删改查、批量处理、父子明细 | [明细操作](ref-details.md) |
-| 浏览、选项、日期、附件、选项卡 | [特定控件](ref-controls.md) |
-| 字段组件渲染、页面消息、弹窗、加载、插件、跨页面交互 | [组件与全局操作](ref-ui-global.md) |
-| 从业务描述找现成实现模式 | [效果案例](ref-recipes.md) |
-| 指定布局的页面、字段和明细表外观 | [表单布局 CSS 编写指南](guide-layout-css.md) |
-| 代码不生效、版本与事件问题 | [排查与边界](ref-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` 核对已有代码和作用范围。
-
-布局源码写入时，CLI 按当前终端页面的 `pageId` 生成 JS 生效条件，并把 CSS 选择器限定在当前 `#ebpage_<pageId>` 内。需要由 JS 动态插入且使用布局 CSS 的元素，应挂在该页面容器内；挂到 `document.body` 的元素不受这份布局 CSS 修饰。写入后用 `layout read` 核对 JS/CSS 原文、页面条件和编译结果，再打开实际表单页面检查运行效果。
-
-布局 CSS 的可设置内容、表格式与流式布局的选择器边界及完整写入示例，见[表单布局 CSS 编写指南](guide-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 作用域；设计器解码自检失败时命令会报错，不会静默成功。