weaver-e10-builder 1.6.15 → 1.7.0

package/skill-docs/references/ebuilder-designer/events/actions-interaction.md

@@ -1,108 +1,132 @@
-# 页面事件交互动作
-
-以下 config 放在 `{ "type":"动作类型", "enabled":true, "config":... }` 中。查询当前定义用 `designer event schema`；先读 [事件指南](guide-events.md) 理解单事件单动作和终端规则。
-
-## 打开页面 NewPage
-
-设置目标页面、打开形式、参数以及窗口外观。config 对应平台 linkInfo，目标信息通过 `designer event lookup --kind page --id <页面ID>` 获取。目标页面名称、所属应用等使用真实元数据。
-
-| openMode | 本事件入口的含义 |
-|---|---|
-| `"4"` | 当前页面 |
-| `"0"` | 新窗口 |
-| `"5"` | 弹出窗口 |
-| `"1"` | 右侧滑出 |
-| `"7"` | 右侧推出 |
-
-本码表不等于组合页面 openMode 或 ebSdk.openPage 的 openType。实际打开方式在 linkInfo.openMode；目标 page 中可能也保留 openMode 元数据，不能拿它覆盖本动作设置。
-
-```json
-{
-  "type":"NewPage",
-  "config":{
-    "page":{"pageId":"目标页面ID","pageName":"目标名称","pageType":"PAGE","parentId":"pages","appid":"目标应用ID","terminalScopes":"PC,MOBILE"},
-    "openMode":"5",
-    "name":"打开详情",
-    "params":[{"name":"source","value":"workbench","type":"fixed"}],
-    "modalWidth":"70%","modalHeight":"70%",
-    "pageTitle":{"nameAlias":"详情"},
-    "isBlankClose":false
-  }
-}
-```
-
-附加设置有 `icon` 图标描述、`flatToBottom`、`isRelationCustomPage`、`winSize`/`winSizeNew` 等。它们是否生效与窗口形式有关，读取对应设置后保留，不把所有尺寸字段当成同义字段。参数数组支持多个命名参数，本轮结构化参数为 name/value/type:fixed，值可包含平台表达式；不将其等同普通字符串替换。
-
-`paramsMode` 可保留本入口的 `"1"`/`"2"`。两值与界面传参模式的逐项含义尚需独立核清，命令不按其他入口的码表转换；未指定时不自动补值。存在此字段不意味着可以宣称“隐式传参无限长”。
-
-## 刷新组件 RefreshComp
-
-设置 `selectedCom` 目标组件数组；`filterIsNull`、`isOverrideFilter` 为本动作过滤选项布尔值；有过滤时携带完整 `dataset` 和 `conditionSet`。目标必须属于配置终端，both 会映射组件 ID。
-
-```json
-{"type":"RefreshComp","config":{"selectedCom":["列表组件ID"],"filterIsNull":true,"isOverrideFilter":true}}
-```
-
-SQL WHERE 条件独立存储，不能把条件文本直接放进 condition ID：
-
-```bash
-e10-cli designer event condition-create <pageId> --comp <触发组件ID> --where-file where.txt --apply
-```
-
-where.txt 是条件文本，例如 `1=1`。命令将文本 LZW 压缩，以 multipart 的 compId、conditionValue 创建条件并返回 ID；它不执行查询，也不替代数据库字段、表达式有效性及权限检查。创建是独立写入，之后保存事件失败时可能留下未引用条件，先记录 ID 再检查，不反复创建。
-
-引用形式：
-
-```json
-{"type":"sql_where","isNewFilter":true,"version":1,"data":{"condition":"返回条件ID","formDw":false,"sourceId":"目标数据源ID"}}
-```
-
-该对象放在 config.conditionSet 中，同时提供与目标组件一致的 dataset。条件创建接口没有在本命令中定义删除能力。
-
-## 关闭页面 ClosePage / 复制链接 CopyLink
-
-这两种动作不需要 config：`{"type":"ClosePage"}`、`{"type":"CopyLink"}`。关闭效果取决于页面宿主，复制效果取决于浏览器剪贴板能力，不用数据保存成功替代运行检查。
-
-## 条件控制 IF
-
-有规则判断和确认框两种模式，控制本次事件的条件结果；本入口不能在其后追加多个动作作为流程。
-
-```json
-{"type":"IF","config":{"mode":"dialog","title":"确认","content":"是否继续？","confirmText":"是","cancelText":"否"}}
-```
-
-规则使用明确的逻辑组和条件，不写平台机器 key：
-
-```json
-{"type":"IF","config":{"mode":"rule","condition":{"logic":"and","rules":[{"left":"{userid}","operator":"eq","right":"人员ID"},{"logic":"or","rules":[{"left":"20","operator":"gt","right":"15"}]}]}}}
-```
-
-本事件规则保存 `relationship:"1"` 为 AND、`"0"` 为 OR。CLI 同时生成条件树和条件显示文字；不沿用其他范围条件的逻辑码。当前可结构化编译 eq 等于、gt 大于；right 使用字符串。left 按平台表达式或输入文字原样写入，不把字段标题擅自转换为组件引用。规则模式保存 Rule；确认框保存 Dialog，切换模式移除原规则遗留字段。树最多 12 层、500 节点。
-
-## JavaScript JsCode
-
-```json
-{"type":"JsCode","config":{"code":"ebSdk.msg('操作完成');"}}
-```
-
-命令生成 compiledCode；编译失败不保存。脚本只影响当前事件环境，不在这里写页面 load 外壳或 import/export。可调用页面源码导出的函数：`pageSdk.getExports().方法名()`，前提是源码中存在对应 export。
-
-## 显示/隐藏组件 ShowHideComponent
-
-config 为数组，每项 id 是目标组件 ID，display 为 show 显示、hide 隐藏、switchover 切换：
-
-```json
-{"type":"ShowHideComponent","config":[{"id":"列表组件ID","display":"switchover"},{"id":"导航组件ID","display":"show","children":[{"id":"导航项ID","display":"hide"}]}]}
-```
-
-children 用于组件内部真实子项，并非任意 DOM 节点；不把显示隐藏当成权限控制。
-
-## 显示菜单 ShowMenu
-
-`menuType`：dropDownMenu 下拉菜单、footerMenu 底部菜单；`displayMode`：vertical 纵向、horizontal 横向；本次可用位置字段 menuPosition 包括 bottom、right，其他位置需读取本入口设置后再用。
-
-```json
-{"type":"ShowMenu","config":{"menuType":"dropDownMenu","menuPosition":"bottom","displayMode":"vertical","menuItems":[{"menuName":"显示提示","menuIcon":"","action":{"type":"JsCode","config":{"code":"ebSdk.msg('菜单执行');"}}}]}}
-```
-
-每项可配置独立 id、menuName、menuIcon。新增时省略 id 由 CLI 生成；action 编译为该菜单项的 CLICK 事件，仍只有一个动作。读取原有菜单时可见原生 menuEvent；action 与 menuEvent 二选一，不同时填。嵌套菜单事件最多 8 层，不能利用嵌套数组绕过单事件单动作限制。
+# 页面事件交互动作
+
+以下 config 放在 `{ "type":"动作类型", "enabled":true, "config":... }` 中。查询当前定义用 `designer event schema`；先读 [事件指南](guide-events.md) 理解顺序动作、递归分支和终端规则。
+
+## 打开页面 NewPage
+
+设置目标页面、打开形式、参数以及窗口外观。config 对应平台 linkInfo，目标信息通过 `designer event lookup --kind page --id <页面ID>` 获取。目标页面名称、所属应用等使用真实元数据。
+
+| openMode | 本事件入口的含义 |
+|---|---|
+| `"4"` | 当前页面 |
+| `"0"` | 新窗口 |
+| `"5"` | 弹出窗口 |
+| `"1"` | 右侧滑出 |
+| `"7"` | 右侧推出 |
+
+本码表不等于组合页面 openMode 或 ebSdk.openPage 的 openType。实际打开方式在 linkInfo.openMode；目标 page 中可能也保留 openMode 元数据，不能拿它覆盖本动作设置。
+
+```json
+{
+  "type":"NewPage",
+  "config":{
+    "page":{"pageId":"目标页面ID","pageName":"目标名称","pageType":"PAGE","parentId":"pages","appid":"目标应用ID","terminalScopes":"PC,MOBILE"},
+    "openMode":"5",
+    "name":"打开详情",
+    "params":[{"name":"source","value":"workbench","type":"fixed"}],
+    "modalWidth":"70%","modalHeight":"70%",
+    "pageTitle":{"nameAlias":"详情"},
+    "isBlankClose":false
+  }
+}
+```
+
+附加设置有 `icon` 图标描述、`flatToBottom`、`isRelationCustomPage`、`winSize`/`winSizeNew` 等。它们是否生效与窗口形式有关，读取对应设置后保留，不把所有尺寸字段当成同义字段。参数数组支持多个命名参数，本轮结构化参数为 name/value/type:fixed，值可包含平台表达式；不将其等同普通字符串替换。
+
+`paramsMode` 可保留本入口的 `"1"`/`"2"`。两值与界面传参模式的逐项含义尚需独立核清，命令不按其他入口的码表转换；未指定时不自动补值。存在此字段不意味着可以宣称“隐式传参无限长”。
+
+## 刷新组件 RefreshComp
+
+设置 `selectedCom` 目标组件数组；`filterIsNull`、`isOverrideFilter` 为本动作过滤选项布尔值；有过滤时携带完整 `dataset` 和 `conditionSet`。目标必须属于配置终端，both 会映射组件 ID。
+
+```json
+{"type":"RefreshComp","config":{"selectedCom":["列表组件ID"],"filterIsNull":true,"isOverrideFilter":true}}
+```
+
+SQL WHERE 条件独立存储，不能把条件文本直接放进 condition ID：
+
+```bash
+e10-cli designer event condition-create <pageId> --comp <触发组件ID> --where-file where.txt --apply
+```
+
+where.txt 是条件文本，例如 `1=1`。命令将文本 LZW 压缩，以 multipart 的 compId、conditionValue 创建条件并返回 ID；它不执行查询，也不替代数据库字段、表达式有效性及权限检查。创建是独立写入，之后保存事件失败时可能留下未引用条件，先记录 ID 再检查，不反复创建。
+
+引用形式：
+
+```json
+{"type":"sql_where","isNewFilter":true,"version":1,"data":{"condition":"返回条件ID","formDw":false,"sourceId":"目标数据源ID"}}
+```
+
+该对象放在 config.conditionSet 中，同时提供与目标组件一致的 dataset。条件创建接口没有在本命令中定义删除能力。
+
+## 关闭页面 ClosePage / 复制链接 CopyLink
+
+这两种动作不需要 config：`{"type":"ClosePage"}`、`{"type":"CopyLink"}`。关闭效果取决于页面宿主，复制效果取决于浏览器剪贴板能力，不用数据保存成功替代运行检查。
+
+## 条件控制 IF / ELSEIF / ELSE
+
+条件控制组织分支的执行内容；每个分支有自己的 actions，可包含多个动作以及进一步的条件控制，内部与外层共用同一套动作类型和配置方法。
+
+一般性示例：
+
+```json
+{
+  "actions":[
+    {"type":"JsCode","config":{"code":"console.info('开始');"}},
+    {"type":"IF","config":{"branches":[
+      {"mode":"rule","condition":{"left":"1","operator":"eq","right":"1"},"actions":[
+        {"type":"JsCode","config":{"code":"console.info('首分支');"}},
+        {"type":"IF","config":{"branches":[
+          {"mode":"dialog","title":"确认","content":"是否继续？","confirmText":"是","cancelText":"否","actions":[{"type":"CopyLink"}]},
+          {"mode":"else","actions":[{"type":"JsCode","config":{"code":"console.info('内层否则');"}}]}
+        ]}}
+      ]},
+      {"mode":"rule","condition":{"left":"2","operator":"gt","right":"1"},"actions":[]},
+      {"mode":"else","actions":[{"type":"JsCode","config":{"code":"console.info('否则');"}}]}
+    ]}},
+    {"type":"JsCode","config":{"code":"console.info('后续动作');"}}
+  ]
+}
+```
+
+原生保存中 IF/ELSEIF/ELSE 为同级节点，子列表为各自 events，CLI 负责把 branches 转换为该形状。也可直接使用 type:IF/ELSEIF/ELSE 与 actions 表达原生层次。首分支不能为 else，同组只有一个末尾 ELSE；多个独立 IF 组可在动作列表中先后出现。
+
+mode:rule 保存 Rule 条件；mode:dialog 保存 Dialog 的标题、内容和确认/取消文字；ELSE 无需 conditionData。切换条件模式清理旧条件字段。空 actions 表示空分支，和删除分支不同。
+
+条件表达式支持三种输入：
+
+1. 自定义文字或表达式：`{"left":"{userid}","operator":"eq","right":"人员ID"}`。
+2. 真实字段：`{"field":完整字段元数据,"operator":"本入口保存码","right":右值,"valueType":"需要时的来源类型","text":"需要时的回显文字"}`，保留字段 id/name/compType、formInfo/refObjId 等。
+3. 完整原生条件树：直接提供 isParent/relationship/datas/conditions，保留字段专属值结构，支持数字和字符串节点 key。
+
+条件组使用 `{"logic":"and","rules":[条件或嵌套组]}` 或 logic:or。保存 relationship:"1" 为 AND、"0" 为 OR。CLI 生成条件显示文字，也可在分支 config 中提供完整 conditionsText。自定义条件值支持标量；浏览对象数组等使用字段输入或原生树。字段操作符和值来源按该入口真实配置，不套用其他范围配置的码表；没有右值的操作符不要伪造选择值。
+
+条件表达式的 AND/OR 嵌套决定分支是否命中，动作树的嵌套决定命中后执行什么，两者分别维护。后续节点如何衔接异步操作和确认取消，需要遵循平台动作运行语义，不能只靠保存结构推定。
+
+## JavaScript JsCode
+
+```json
+{"type":"JsCode","config":{"code":"ebSdk.msg('操作完成');"}}
+```
+
+命令生成 compiledCode；编译失败不保存。脚本只影响当前事件环境，不在这里写页面 load 外壳或 import/export。可调用页面源码导出的函数：`pageSdk.getExports().方法名()`，前提是源码中存在对应 export。
+
+## 显示/隐藏组件 ShowHideComponent
+
+config 为数组，每项 id 是目标组件 ID，display 为 show 显示、hide 隐藏、switchover 切换：
+
+```json
+{"type":"ShowHideComponent","config":[{"id":"列表组件ID","display":"switchover"},{"id":"导航组件ID","display":"show","children":[{"id":"导航项ID","display":"hide"}]}]}
+```
+
+children 用于组件内部真实子项，并非任意 DOM 节点；不把显示隐藏当成权限控制。
+
+## 显示菜单 ShowMenu
+
+`menuType`：dropDownMenu 下拉菜单、footerMenu 底部菜单；`displayMode`：vertical 纵向、horizontal 横向；本次可用位置字段 menuPosition 包括 bottom、right，其他位置需读取本入口设置后再用。
+
+```json
+{"type":"ShowMenu","config":{"menuType":"dropDownMenu","menuPosition":"bottom","displayMode":"vertical","menuItems":[{"menuName":"显示提示","menuIcon":"","action":{"type":"JsCode","config":{"code":"ebSdk.msg('菜单执行');"}}}]}}
+```
+
+每项可配置独立 id、menuName、menuIcon。新增时省略 id 由 CLI 生成；action 编译为该菜单项的 CLICK 事件；可传单动作，或 {actions:[...]} 配置多个动作及递归条件。读取原有菜单时可见原生 menuEvent；action 与 menuEvent 二选一，不同时填。菜单项动作与普通触发共用动作列表模型，可在节点编辑时按动作 ID 递归定位。

package/skill-docs/references/ebuilder-designer/events/guide-events.md

@@ -1,57 +1,112 @@
-# 页面与组件事件配置
-
-## 整体功能介绍
-
-事件配置把页面或组件的触发时机与一个动作绑定，可实现打开/关闭页面、刷新、条件判断、JavaScript、组件显隐、菜单、集成及其他交互。它保存于页面布局的事件设置中，与页面源码 JS/CSS 分别维护。
-
-**同一配置对象的单击 CLICK 和加载完成 DIDMOUNT 各最多一条，每条最多一个动作。两种事件可以同时存在。** 修改事件是替换该动作，不追加动作列表；没有动作的事件不承担业务行为。条件控制不是包含多个动作的流程编排，需要复杂步骤时绑定已经配置好的逻辑流或使用相应事件脚本。
-
-配置对象可为页面、组件，或组件中的导航/按钮子项。每个对象独立维护事件；显示菜单的菜单项也可有自己的单击事件。页面事件位于 `layout.config.eventGroup`，组件事件位于 `comp.config.eventGroup`，子项事件位于对应子项。它们采用双层 `eventGroup`，条目内 `events` 只包含一个动作，不把平台数组形式理解为支持多个动作。
-
-## 查询与命令
-
-```bash
-e10-cli designer event schema
-e10-cli designer event get <pageId> --comp <compId> --terminal pc
-e10-cli designer event get <pageId> --terminal pc
-e10-cli designer event set <pageId> --comp <compId> --trigger CLICK --config @action.json
-e10-cli designer event set <pageId> --comp <compId> --trigger CLICK --config @action.json --apply
-e10-cli designer event enable <pageId> --comp <compId> --trigger CLICK --value false --apply
-e10-cli designer event remove <pageId> --comp <compId> --trigger DIDMOUNT --apply
-```
-
-默认预览，`--apply` 保存。`set` 在没有该事件时新增，在已有该事件时替换唯一动作，保留另一种事件。`enable` 只改动作启用标记；`remove` 删除指定触发事件。不存在事件时删除会报错，不将其当成成功。
-
-省略 `--comp` 操作页面事件。操作直接子项时传 `--comp`、`--collection menuConfig|btnGroup|navMenus|newButtons`、`--item <子项ID>`，按真实 ID 定位，不按显示名称或数组下标猜测。
-
-配置统一为：
-
-```json
-{"type":"JsCode","enabled":true,"config":{"code":"ebSdk.msg('操作完成');"}}
-```
-
-`type` 为本入口动作类型，`enabled` 默认为 true，`config` 为该动作的设置。普通动作配置见 [交互动作](actions-interaction.md)，外部资源和宿主相关动作见 [集成动作](actions-integration.md)。
-
-## 终端与保存
-
-`--terminal pc|mobile|both`，默认 pc。单端修改保留另一端；both 以 PC 组件为源，通过双向 `refCompId` 定位 MOBILE 组件。刷新目标、显隐目标会转换为对应终端的组件 ID，缺少配对则拒绝。子项必须在对应终端存在相同真实子项 ID；不按名称猜测子项映射。
-
-JavaScript 和集成参数属于不透明业务内容，不在字符串内部替换组件 ID。两端需要不同代码或打开方式时，分别设置 pc/mobile，不使用 both 强行覆盖。打开方式只控制对应动作，不改变目标页面的布局或权限。
-
-保存前读取整页双端布局和编辑状态；页面已锁定时停止，不解除他人编辑锁。保存前再次检查并发变化，保存后核对组件、事件、页面配置和源码，再释放本次保存软锁。其他事件、其他组件、源码和主题配置均保留。失败或响应丢失时先 get 查询状态，不重复盲写。
-
-修改动作类型时仅生成新类型的配置，移除上一类型遗留的参数。更新同一事件仍需提供完整 config，不对缺少的动作参数作隐式继承。
-
-## 编写边界
-
-事件 JavaScript 的 `code` 与 `compiledCode` 同步维护；这里只编译脚本片段，不使用页面源码的 JSONP/load 外壳，不使用 import/export。`ebSdk`、`pageSdk` 和事件环境由平台提供。异步动作衔接可使用仅适用于事件动作的 `asyncFn`，见 [页面 SDK 基础](../page-source/sdk-foundations.md)。
-
-页面源码 `pageSdk.on('pageLoad')` 与事件配置 `DIDMOUNT` 是不同入口，不混写名称。涉及组件内部数据时按页面 SDK 的 compLoad 等时机处理；不要在加载完成动作中无条件刷新自身，造成重复加载。
-
-配置保存检查和前台行为检查分别判断。设备、企业微信、签署和报表依赖对应资源及运行宿主；不能因动作成功写入普通页面就认定这些外部功能已经执行成功。
-
-## 当前支持范围
-
-18 种动作可识别、查询和保留；其中 17 种支持本指南所列结构的新增/替换。StartSignAction 仅支持已有动作的查询、启停、删除，非空签署目标的新增结构需补充后开放。规则条件结构化编译当前支持 eq、gt 和 and/or 嵌套；不将其他模块的操作符或逻辑码直接拿来填。
-
-原有导航专用命令只覆盖其特定跳页配置，不代表通用事件能力；统一事件设置使用本组命令。新增事件或动作排序不适用于这里。
+# 页面与组件事件配置
+
+## 整体功能介绍
+
+事件配置让页面、组件或组件子项在指定触发时机执行一组有顺序的动作，可实现打开页面、刷新、JavaScript、组件显隐、菜单和集成调用。条件控制把动作组织为 IF/ELSEIF/ELSE 分支；每个分支内部仍然是同样的动作列表，可包含多个动作和进一步的条件控制。
+
+事件配置与页面源码 JS/CSS、表单 JSSDK 事件分别维护。复杂交互可以直接组合事件与条件，不要求一律改写为 JS 或逻辑流；需要代码计算或已有业务流程时再绑定对应动作。
+
+## 模型与存储位置
+
+配置对象拥有触发记录，例如 CLICK 单击、DIDMOUNT 加载完成、列表的 CLICKDATA 单击每一条数据。每种触发记录的 events 是顺序动作列表，支持多个动作；不同触发分别维护。触发类型以对象实际提供的选项为准，不要求所有组件都具有所有触发。
+
+| 对象 | 存储位置/定位方式 |
+|---|---|
+| 页面 | layout.config.eventGroup；省略 --comp |
+| 组件 | comp.config.eventGroup；指定 --comp |
+| 导航/按钮组等子项 | --collection menuConfig/btnGroup/navMenus/newButtons，指定 --item |
+| 标签栏菜单 | --collection items |
+| 列表自定义操作按钮 | --collection listButtons，对应 buttonConfig.btns[].actions |
+| 自定义页面帮助按钮 | --collection customPageButtons，对应按钮 event.value；只配置 CLICK |
+| 显示菜单中的菜单项 | ShowMenu 的 menuItems[].menuEvent |
+
+以上事件容器采用双层数组；其中的触发记录包含有序 events。同一种触发按唯一记录定位，动作数量不限制为一个。条件分支原生保存为同级 IF、零至多个 ELSEIF、可选 ELSE，各分支用自己的 events 保存子动作。条件组与普通动作可以继续组成外层顺序列表。
+
+动作顺序与异步等待不是同一概念：配置按顺序组织；异步完成、失败是否中断、确认框取消后如何继续，取决于动作运行实现。编写异步事件脚本时按 SDK 的 asyncFn 规则处理，不凭数组顺序承诺所有异步请求自动等待完成。
+
+## 查询与整体配置
+
+```bash
+e10-cli designer event schema
+e10-cli designer event get <pageId> --comp <compId> --terminal pc
+e10-cli designer event get <pageId> --terminal pc
+e10-cli designer event set <pageId> --comp <compId> --trigger CLICK --config @sequence.json --apply
+```
+
+sequence.json 使用完整动作列表：
+
+```json
+{"actions":[{"type":"JsCode","config":{"code":"console.info('开始');"}},{"type":"CopyLink"}]}
+```
+
+默认预览，--apply 保存。set 明确替换该触发的完整动作列表，保留其他触发。actions:[] 清空列表并保留触发记录；remove 删除整个触发记录。兼容旧单动作输入 {type,enabled?,config?}，但已有多个动作时拒绝用旧单动作输入隐式覆盖，改用完整 actions 或按 ID 编辑。
+
+可使用 {nativeActions:[平台原生动作节点]} 整体配置原生结构，和 actions 二选一。原生节点须有 id/type，分支必须符合结构；普通未知节点可保留。原生 JS 仍根据 code 重新编译，刷新和显隐检查目标组件。此入口不把未知属性当成已掌握的功能，业务字段和值来源须使用对应入口的真实结构。
+
+```bash
+e10-cli designer event remove <pageId> --comp <compId> --trigger DIDMOUNT --apply
+e10-cli designer event enable <pageId> --comp <compId> --trigger CLICK --value false --apply
+```
+
+enable 兼容入口只用于唯一动作；有多个动作时用 action enable 指定动作 ID。删除不存在的触发会报错。
+
+## 单节点与动作顺序
+
+```bash
+e10-cli designer event action add <pageId> --comp <compId> --trigger CLICK --config @action.json --apply
+e10-cli designer event action update <pageId> --comp <compId> --trigger CLICK --action-id <actionId> --config @action.json --apply
+e10-cli designer event action remove <pageId> --comp <compId> --trigger CLICK --action-id <actionId> --apply
+e10-cli designer event action enable <pageId> --comp <compId> --trigger CLICK --action-id <actionId> --value false --apply
+e10-cli designer event action order <pageId> --comp <compId> --trigger CLICK --config @ids.json --apply
+```
+
+- add 默认追加；--before <兄弟ID> 插入指定节点之前。
+- --parent <分支ID> 定位该分支内部动作列表。省略时 add/order 操作触发的顶层列表；update/remove/enable 按 ID 递归定位。
+- update 提供完整动作 type/config；同类型的内部动作不做隐式参数合并。修改条件分支时不传 actions 会保留其原有子动作，明确 actions:[] 才清空。
+- order 输入该层所有普通动作 ID 和 IF 组首节点 ID，IF/ELSEIF/ELSE 作为完整组一起移动，不把分支拆开排序。
+- 删除 IF 会连同它的 ELSEIF/ELSE 组一起删除；删除其他分支只删除该分支及其后代。未知兄弟动作及其配置保留。
+- 已有节点修改保留 ID；新增生成 ID；用 get 读取真实 ID，不按名称或数组序号猜测。
+
+## 条件分支
+
+完整配置可使用 IF 的 config.branches；首项为 IF，之后为 ELSEIF，mode:else 为末尾 ELSE。每项 actions 支持所有已接入动作及嵌套条件。详见 [交互动作与条件示例](actions-interaction.md)。
+
+```bash
+e10-cli designer event branch add <pageId> --comp <compId> --trigger CLICK --parent <ifId> --config @branch.json --apply
+e10-cli designer event branch update <pageId> --comp <compId> --trigger CLICK --action-id <branchId> --config @branch.json --apply
+e10-cli designer event branch remove <pageId> --comp <compId> --trigger CLICK --action-id <branchId> --apply
+e10-cli designer event branch enable <pageId> --comp <compId> --trigger CLICK --action-id <branchId> --value false --apply
+e10-cli designer event branch order <pageId> --comp <compId> --trigger CLICK --parent <ifId> --config @branch-ids.json --apply
+```
+
+branch add 接受 type:ELSEIF 或 ELSE，指定所属 IF；默认 ELSEIF 插到 ELSE 前，ELSE 放末尾。order 提供同组全部分支 ID，IF 保持首位、ELSE 保持末尾。分支与其内部动作分别启停。结构化配置和原生配置可以表达同样的分支树，不限制分支只有一个子动作。
+
+## 条件字段与目标查询
+
+```bash
+e10-cli designer event fields <pageId> --comp <componentId> --terminal pc
+e10-cli designer event targets --kind apps
+e10-cli designer event targets --kind menu --app-id <appId> --page-id <pageId> --terminal pc
+e10-cli designer event targets --kind layouts --obj-id <objId> --terminal pc
+e10-cli designer event targets --kind types
+e10-cli designer event targets --kind workflow --config @query.json
+e10-cli designer event targets --kind report --config @query.json
+```
+
+fields 按组件当前 dataset 查询字段和 conditionType，并携带数据扩展参数，支持 --config 附加参数。没有数据源时不伪造字段，可使用自定义条件或取得相应来源后提供原生条件树。字段、条件表达式、分支动作是三个不同层次。
+
+目标菜单使用事件入口 entranceType=2。布局查询使用 complete，而非只有浏览控件信息的 associate；支持 --search。workflow/report 保留原生浏览参数，可用 --config 指定搜索、分类和分页；报表默认使用分类 0（全部）；返回分页信息，不将一页当成全量。系统类型查询使用平台提供的选择器，不固定只能选择普通页面或表单布局。需要已知 ID 的资源查询及 ESB 输入结构见 [集成动作](actions-integration.md)。
+
+条件操作符要区分候选显示码与保存码；field.conditionType 提供当前可选内容，不直接据其名称推定保存协议。条件可使用自定义输入、完整字段对象或完整原生树，保留 formInfo/refObjId 等来源属性，不只写字段名称。原生树允许数字或字符串 key/parentNode，节点 key 需唯一，同一字段 ID 可以重复使用。
+
+## 终端与保存
+
+--terminal pc|mobile|both，默认 pc。both 通过双向 refCompId 定位组件；递归处理所有顺序动作、条件后代和显示菜单中的刷新/显隐组件引用。新增结构化动作 ID 两端对应；已有不同 ID 的子项或动作不按名称猜测，请分别配置。显隐内部子项要求同 ID 或明确配对关系，否则停止。代码及业务字符串不做组件 ID 字符串替换。
+
+保存前读取完整双端布局，检查模块、编辑权限、软锁和并发变化；只改选定对象。保存后核对完整事件树、顺序、分支、两端组件、页面配置和源码，在 finally 中释放本次保存软锁。回读失败明确报错，先 get 查询实际状态，不盲目重试。不解除其他编辑会话持有的锁。
+
+## 编写边界
+
+事件 JS 的 code 与 compiledCode 同步编译，使用脚本片段，不写页面源码 JSONP/load 外壳或 import/export。ebSdk/pageSdk 和事件环境由平台提供；页面源码 pageSdk.on('pageLoad') 与 DIDMOUNT 分别维护。加载事件不要无条件刷新自身，避免重复加载。
+
+18 种原有动作与 ELSEIF/ELSE 分支节点可读取和保留；StartSignAction 的非空签署目标新增仍需对应保存结构，其余动作按各自动作参数维护。原生结构可以保留已有签署配置，不等于已经提供签署目标的结构化编译方法。设备、企业微信、ESB、逻辑流和报表还依赖真实资源及宿主，保存回读不替代业务运行检查。

package/skill-docs/references/ebuilder-designer/guide-custom-page.md

@@ -0,0 +1,176 @@
+# 自定义页面组件（CustomPage）
+
+## 功能介绍
+
+自定义页面组件在当前 EB 页面的一块区域中展示其他页面或链接。可以嵌入系统功能页面、表单布局、应用页面或其他可选目标；通过参数打开对应内容，通过条件规则切换展示目标，并配置标题、图标、刷新与最大化等操作。具体目标以当前应用、终端的选择器查询结果为准，不把目标类型限制为示例中列出的几种。
+
+它属于页面组件：组合页面负责把多个页面组织为页签；页面源码负责给页面补充 JS/CSS；自定义页面组件负责在页面内部承载另一个内容区域。嵌入不会赋予用户目标页面的数据权限，也不替代目标的登录及访问权限。
+
+命令入口：`e10-cli designer custom-page`。组件的通用权限使用 [组件权限](component-permission.md)；帮助按钮动作使用 [事件配置](events/guide-events.md)。
+
+## 1. 定位组件与查询
+
+先用 `designer layout <pageId>` 读取两端布局，定位 `type: "CustomPage"` 的组件。需要新增时，可使用内置模板 `designer comp-add <pageId> --template custom-page --yes`，或通过现有组件克隆方式；组件模板应保留当前平台的组件包、配置和两端配对结构，不凭空拼装组件外壳。
+
+若通用添加命令在本次操作后留下软锁，先按 [设计器指南](guide-designer.md) 完成保存收尾并释放本次锁；自定义页面命令会拒绝覆盖已锁定页面。不要释放其他编辑会话持有的锁。
+
+```bash
+e10-cli designer custom-page schema
+e10-cli designer custom-page get <pageId> --comp <componentId> --terminal pc
+e10-cli designer custom-page targets --kind apps
+e10-cli designer custom-page targets --kind menu --app-id <appId> --page-id <pageId> --terminal pc
+e10-cli designer custom-page targets --kind layouts --obj-id <targetFormObjId>
+e10-cli designer custom-page targets --kind app-tags
+```
+
+`menu` 使用本组件的链接选择入口（`module=EB_PAGE`、`entranceType=0`），保留查询返回的目标分类和元数据。`layouts` 查询表单布局候选，默认参数为 `formLayoutType:""`、`terminalType:"pc,mobile"`、`excludeFormLayoutType:"cardView"`，可用 `--config @query.json` 提供本入口所需的其他查询参数。`app-tags` 返回显示条件可使用的应用标识浏览对象。布局和应用标识使用浏览器的 `complete` 数据查询，支持 `--search <关键词>` 及 `--config` 附加查询参数，保留响应中的分页和总数信息；一页结果不等于全部候选。`associate` 主要提供浏览控件配置，不能把它当作候选数据列表。
+
+写入命令均支持 `--config @file.json`，不加 `--apply` 只预览。`--terminal pc|mobile` 默认 pc；两端分别指定各自组件 ID 和保存命令，不因存在配对 ID 就自动覆盖另一端。
+
+## 2. 展示内容与参数
+
+```bash
+e10-cli designer custom-page content set <pageId> --comp <componentId> --terminal pc --config @content.json --apply
+```
+
+| 属性 | 作用 |
+|---|---|
+| `urlType:"custom"` | 使用直接地址 |
+| `urlType:"link"` | 使用选择器目标及其完整链接配置 |
+| `url` | PC 直接地址；移动端命令也接受此输入并转为 `mUrl` |
+| `mUrl` | 移动端直接地址，不能与输入 `url` 同时指定 |
+| `urlLink.link` | 目标页面、参数、布局等完整描述 |
+| `urlLink.url` | 与目标配置对应的实际解析地址 |
+| `linkCustomId` / `linkCustomName` | 原生附加属性；按已有配置保留，不将它们当作通用目标 ID/名称的替代品 |
+
+直接地址示例：
+
+```json
+{"urlType":"custom","url":"https://example.com/portal"}
+```
+
+选择页面时，输入完整 `urlLink`，包括 `link.page.pageId`、`link.page.pageType` 和实际 `url`。目标切换会替换整个 `urlLink`，避免旧布局、参数或目标专属属性混入新目标。因此只改参数时，也应先读取当前 `urlLink`，修改参数后完整提交。
+
+`link` 中常见属性如下；按当前选择器返回的目标保留，不要求所有目标都具有这些属性：
+
+| 属性 | 内容 |
+|---|---|
+| `page` | `pageId/pageName/pageType/parentId/appid` 等目标元数据 |
+| `params` | 参数数组；固定值项形如 `{ "name":"id", "type":"fixed", "value":"记录ID" }` |
+| `selectLayout` / `selectMobileLayout` | 目标表单 PC、移动布局的完整浏览对象 |
+| `isPcMobileSameLayout` | 两端是否采用同一布局的设置 |
+| `keepLayout` | 目标链接携带的布局保留设置 |
+| `openMode` | 本入口原生值，保留目标配置，不套用事件或组合页签的打开方式码表 |
+| `name` / `icon` | 目标名称、图标等展示元数据 |
+
+不能仅凭 `pageId` 推断所有类型的地址：表单布局、系统流程页面、组合页面的地址构造不同，部分目标还依赖布局及业务参数。优先复用该目标选择返回的完整链接对象；仅有候选菜单 ID 时，还需取得对应链接配置或提供正确的目标地址。
+
+外部地址能否嵌入，还取决于目标站点的 iframe、安全策略、登录及跨域限制；配置保存成功不代表外部站点允许展示。
+
+## 3. 标题与图标
+
+```bash
+e10-cli designer custom-page title set <pageId> --comp <componentId> --config @title.json --apply
+```
+
+```json
+{
+  "enabled": true,
+  "text": "关联信息",
+  "icon": { "path":"#实际图标名", "style": { "color":"#1677ff", "fontSize":"20" } }
+}
+```
+
+`enabled` 对应 `titleEnabled`。`text` 更新标题对象的 `nameAlias`，保留原有多语言元数据；旧字符串标题会转为对象。`icon` 合并到 `titleIcon`，可保留图标路径、样式及 `iconDisplayType` 等原生属性。不要用示例图标名代替实际可用图标。
+
+## 4. 顶部操作按钮
+
+先从 `get` 的 `topOperatBtns.btns` 读取实际按钮 ID、动作和可选展示方式。不同组件/版本的按钮集合可能不同，不按按钮序号定位，也不为缺失的内置按钮伪造配置。
+
+```bash
+e10-cli designer custom-page button set <pageId> --comp <componentId> --config @bar.json --apply
+e10-cli designer custom-page button update <pageId> --comp <componentId> --item <buttonId> --config @button.json --apply
+e10-cli designer custom-page button order <pageId> --comp <componentId> --config @all-button-ids.json --apply
+```
+
+- `button set`：整体 `enabled` 开关、原生 `alignType`。保留当前排列值，不推断完整排列码表。
+- `button update`：`isOpen` 启停、`showType` 展示方式、`showContent` 名称/图标/样式、`positionType` 原生位置。
+- `button order`：全部按钮 ID 数组，不能遗漏或重复；同步 `showOrder`。
+
+展示方式为 `ICON` 仅图标、`FONTBTN` 仅文字、`FONTWITHICON` 图标加文字。若按钮带 `showTypeData`，以该按钮列出的选项为准。`showContent` 并不统一：普通图标按钮通常是对象，文字按钮可能是字符串，最大化按钮有 `shrinkContent/spreadContent` 两套图标。修改前读取其结构。
+
+| `event.to` | 按钮作用与配置方法 |
+|---|---|
+| `REFRESHCOM` | 刷新内嵌内容，保留内置动作 |
+| `FULLSCREEN` | 组件最大化/最小化，保留两种状态的显示内容 |
+| `CUSTOMSETTING` | 原生设置入口，保留内置动作 |
+| `HELP` | 帮助按钮，可配置单击动作 |
+
+帮助动作存放在 `topOperatBtns.btns[].event.value` 的双层事件数组中，不是列表按钮的 `actions`：
+
+```bash
+e10-cli designer event set <pageId> --comp <componentId> --collection customPageButtons --item <helpButtonId> --trigger CLICK --config @action.json --apply
+```
+
+例如 `action.json` 可为 `{ "type":"CopyLink" }`。其他动作先读 `designer event schema` 及事件指南。此入口只接受帮助按钮的 CLICK，支持多个顺序动作及递归条件分支，使用统一事件命令维护。配置动作和开启按钮分别处理，按钮启用使用 `button update`。
+
+## 5. 条件切换内容
+
+`conditionControl` 是内容切换规则数组；每条规则有独立 `id`、`conditionSet` 和内容目标。它与控制组件整体显示的 `showCondition` 分开维护。
+
+```bash
+e10-cli designer custom-page rule add <pageId> --comp <componentId> --config @rule.json --apply
+e10-cli designer custom-page rule update <pageId> --comp <componentId> --item <ruleId> --config @patch.json --apply
+e10-cli designer custom-page rule remove <pageId> --comp <componentId> --item <ruleId> --apply
+e10-cli designer custom-page rule order <pageId> --comp <componentId> --config @all-rule-ids.json --apply
+e10-cli designer custom-page rule clear <pageId> --comp <componentId> --apply
+```
+
+新增时生成规则 ID，需提供非空 `conditionSet`；修改可只传条件或目标，其他内容保留。排序需全部规则 ID。规则中的直接地址统一为 `url`，移动规则也不改成 `mUrl`。选页面同样提交完整 `urlLink`。
+
+一般性的自定义文本条件示例：
+
+```json
+{
+  "urlType":"custom",
+  "url":"https://example.com/detail",
+  "conditionSet": {
+    "key":"root", "relationship":"1", "isParent":true, "parentNode":"",
+    "datas":[{
+      "key":"leaf", "isParent":false, "parentNode":"root",
+      "id":"Custom_0123456789abcdef0123456789abcdef",
+      "fieldName":"customField", "fieldType":"String", "text":"左侧文本或平台表达式",
+      "objId":"", "optionType":"", "compType":"Text", "formatType":"", "opts":[],
+      "type":"condition", "refObjId":"",
+      "conditions":{"func":"eq","value":"对照值","type":"","isEsb":false}
+    }]
+  }
+}
+```
+
+条件组 `relationship:"1"` 为 AND、`"0"` 为 OR，组内可嵌套组；节点 `key` 唯一，`parentNode` 指向父组，根为 `""`。同一个字段可出现在不同叶子中，不要求字段 ID 唯一。自定义文本条件有 `eq` 等于、`neq` 不等于的结构；其他字段的操作符和右值对象应来自该入口当前条件编辑器，不能套用浏览数据范围等其他入口的码表。
+
+规则顺序按数组保存；多个条件同时命中时的运行优先级不作为固定规则承诺。设计互斥条件可以避免依赖未明确的优先级。保存和回读只核对配置，不等于证明实际参数值、条件命中或目标业务数据正确。
+
+## 6. 组件显示条件
+
+```bash
+e10-cli designer custom-page visibility set <pageId> --comp <componentId> --config @visibility.json --apply
+e10-cli designer custom-page visibility clear <pageId> --comp <componentId> --apply
+```
+
+`set` 输入该入口原生条件树，保存到 `showCondition`，补充默认 `isNewFilter:true/version:1`；`clear` 移除显示条件。组和节点关系同上，但字段来源及结构属于组件显示条件入口，**不能直接复制内容切换条件的叶子作为显示条件**。
+
+应用标识条件使用 `fieldName/id:"$alreadyInstalledSpecialty$"`、`fieldType/compType:"EbuilderAppTag"`、`mainField:true`、`multiSelect:true`。`conditions` 中可使用 `func:"contains"`、`matchType:"or"`，`value` 为应用标识浏览对象数组，`text` 为名称数组；对象从 `targets --kind app-tags` 查询，包含 `ebAppTag/id/ebTagName/content` 等属性。保留条件编辑器完整叶子元数据，不把名称或单个 ID 当作完整浏览对象。
+
+## 7. 原生扩展、保存与检查
+
+`config set` 提供原生扩展属性的合并入口，例如 `footerEnabled`、`showTopOperatBtnConfig`、完整 `topOperatBtns` 等；已知字段可用它表达专门命令尚未封装的原生选项。对象递归合并，数组整体替换，空对象替换为 `{}`。事件、权限、布局位置、内容和条件使用对应命令，不从扩展入口绕过其处理。未知属性原样保留不等于平台必然支持它。
+
+```bash
+e10-cli designer custom-page config set <pageId> --comp <componentId> --config @native.json --apply
+```
+
+保存前检查页面模块、编辑权限、锁和布局是否变化；保存整份布局后核对组件、两端布局配置及源码，释放本次软锁。若平台接受配置但随后无法读取布局，会尝试恢复此次写入前的布局并回读；恢复失败会明确报错，不将保存响应当作成功。
+
+完成后检查：标题与内嵌区域是否显示、目标是否正确、参数是否对应记录、刷新和最大化是否工作、条件切换与整体显示条件是否符合设计、移动端是否使用独立内容。外部链接限制、登录状态和实际页面效果仍需浏览器检查。

package/skill-docs/references/ebuilder-designer/guide-designer-components.md

@@ -128,3 +128,5 @@ e10-cli designer save <pageId> --layouts @layouts.json
 - 工厂模板（comp-add 复制机制）→ `guide-designer-factory.md`
 - 版本层（list/revert）→ `guide-designer-version.md`
 - 命令速查 → `../common/ref-cli-commands.md`「designer」节
+
+`CustomPage`（自定义页面）组件包含标题、直接地址或页面链接、条件切换、整体显示条件和顶部操作按钮。使用 `designer custom-page`，配置结构与方法见 [自定义页面组件](guide-custom-page.md)。

package/skill-docs/references/ebuilder-designer/guide-designer-factory.md

@@ -462,3 +462,5 @@ factory-collapse-panel.json / factory-new-tab.json 已清空 `flow.linkedNodes`/
 - 布局层（info/layout/save/comp-add）→ `guide-designer.md`
 - 组件 config 字段名 → `guide-designer-components.md`
 - 命令速查 → `../common/ref-cli-commands.md`「designer」节
+
+自定义页面组件使用 `--template custom-page`，生成独立的 PC/MOBILE 组件，默认不绑定业务目标、不带条件或授权。后续使用 `designer custom-page` 配置，详见 [自定义页面组件](guide-custom-page.md)。