weaver-e10-builder 1.6.16 → 1.7.1

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

@@ -1,130 +1,132 @@
-# 设计器组件层指南（骨架）
-
-> 本文件为 `SKILL.md` 的子模块，在用户配置具体组件时加载。
->
-> **重要**：组件层**不是原生后端接口**——平台没有按组件类型分的 HTTP 端点。所有组件配置最终落地经 `designer save`（POST `/layout/save`，见 `guide-designer.md`）：读布局 → 改 `comps[].config` → 保存。本骨架只给机制与接口能确定的 Slide 字段；**其余组件 config 字段集与取值枚举接口未给，须运行时 inspect 真实页面查 `comp.config`，不凭空构造**（盲造触发 ERR-007/008 崩页）。
->
-> 本 skill 自包含分发，不依赖任何本机样本文件；"inspect 真实页面"指用户对自己的页面运行 `designer layout <pageId> --json` 查看实际 comp.config，是运行时操作。
-
----
-
-## 机制说明
-
-所有组件配置的工作流一致：
-
-```bash
-# 1. 导出布局（作为 save 入参基础，取自 /layout/list）。--json 走 stdout，日志走 stderr，故 `>` 只收 JSON 干净；勿 `2>&1` 混入日志
-e10-cli designer layout <pageId> --terminal all --json > layouts.json
-# 2. 定位目标 comp，改 comp.config.<字段>
-# 3. 保存（comps 整体重传）
-e10-cli designer save <pageId> --layouts @layouts.json
-```
-
-> **保真规则**：save 是浅合并，入参取自 `/layout/list`、**只构造 `comps`**（见 `guide-designer.md`「入参数据来源铁律」）。改 comp.config 子字段后，整个 comps 数组随 save 重传；`pageId`/`terminalType`/`module`/`ecodeVersion`/`appId` 等元数据保持原值不动。
->
-> **save 必须含两端**：`layouts.json` 要含 **PC + MOBILE 两端**（用 `--terminal all` 导出）。只传 PC 端 save 会**覆盖丢失 MOBILE 端布局**（save 是整页覆盖，不是按端 merge）。
->
-> **PC/MOBILE 同名组件**经 `refCompId` 互连——改一端 config 时注意另一端是否需同步。
-
-### 自定义 CSS
-
-组件的外观有两层：`comp.config.styles[N].customStyle` 下的**图形化样式块**（`title`/`content`/`footer`/`container` 的字号、背景、边框等），以及其中的 **`base.codeSource` 自由文本 CSS**。后者就是需求里说的「自定义 CSS」。
-
-- 干净组件的 `styles` 是**空数组**；Picture/CountDown 之类自带**主题绑定记录**（`useComStyle:true`），与自由 CSS 记录是两回事，**不要碰**。
-- 不要绕开命令直接改布局 JSON，也不要去动 `sourceCode.cssCache`（平台的编译产物）。
-- 用 `e10-cli designer css read/write` 读写，用 `e10-cli designer dom <type>` 查该组件的 DOM 结构来写选择器。
-
-完整契约、选择器作用域速查、27 个组件的 DOM 文档对照表与各条坑 → `guide-designer-css.md`。
-
----
-
-## 接口给出的组件字段（Slide 一例）
-
-接口文档（layout-save §4.3 config 内部结构 + §6.1 完整 Slide 入参）只给 Slide 一个完整 config 示例。**只有 Slide 的字段名是接口确定的**，可照此修改：
-
-| config 字段 | 类型 | 说明 |
-|------|------|------|
-| `name` | String | 组件显示名 |
-| `title` / `titleEnabled` | String / Boolean | 标题文本 / 是否启用 |
-| `footerEnabled` | Boolean | 是否启用页脚 |
-| `pics` | Array | 图片列表 |
-| `imageMode` | String | 图片填充模式 |
-| `switchEffect` | String | 切换效果 |
-| `intervalTime` | Object | 轮播间隔 `{type, value}` |
-| `speed` | Integer | 切换速度（ms） |
-| `lazyLoad` | Boolean | 是否懒加载 |
-| `imgSourceType` | String | 图片来源类型 |
-| `eventGroup` | Array | 事件配置列表 |
-| `filter` | **Object** | 数据过滤条件（HTTP 契约：filter 类型为 Object，传 `[]` 与契约不符） |
-| `showNum` | Integer | 展示数量 |
-| `layout` | Object | 栅格布局 `{i, x, y, w, h, ...}` |
-| `flow` / `disabled` | Object | 流程 / 禁用配置 |
-
-> **需 inspect 真实页面查原始值**：上表**字段名**来自接口 Slide 示例；但 `imageMode`/`switchEffect`/`imgSourceType` 等字段的**完整取值枚举接口未给**（示例仅各一例）——须 inspect 自己已配好的 Slide 组件查可选值，勿凭枚举造。
-
----
-
-## 其余组件（Calendar / DigitalPanel / Chart / NavPanel / List 等）
-
-> 除 Slide 外，各组件 config 字段集与取值枚举**接口文档均未给出**。下表**字段名**来自示例页面结构（非穷尽、非权威，以 inspect 真实页面为准）；**取值**一律须运行时 inspect 自己的页面 `comp.config` 查，不赋空值（`字段=''`/`[]`/`{}` 凭空造值会触发 ERR-007/008）。
-
-| 组件 type | config 顶层字段（结构示例，取值须 inspect） |
-|---|---|
-| `DigitalPanel` | name/type/title/titleEnabled/footerEnabled/panels/showmode/columns/timedRefresh/layout/flow/disabled/styles |
-| `NavPanel` | name/type/title/titleEnabled/column/pageColumn/enableGroup/menuConfig/menuSourceType/showSearch/commonMenu*/groupMode/openType/userSource/groupBrowser/menuBrowser/menuDisplayRange/externalDataInterfaceSetting/actionTemplateStr/layout/flow/disabled/styles |
-| `Pie` / `Bar` / `Line`（图表） | name/type/title/titleEnabled/topOperatBtns/measures/dimensions/height/barType(Bar)/label(Bar)/filterVersion/dataset/filter/searchConditions/dataListDisplay/xAxis/yAxis/showTotal/showLimit/hideForNoData/tools/layout/flow/disabled/styles |
-| `NList`（列表） | name/type/mode/pageMode/title/titleEnabled/footerEnabled/pageSize/headMerge/listVersion/dataset/order/filter/tableField/personalFields/searchConditions/enableGroup/filterIsNull/isFilterSub/version/rootStr/fieldUsage/layout/flow/disabled/styles |
-| `Calendar`（日历） | name/type/title/titleEnabled/footerEnabled/calendarType/condition/defaultView/weekStart/filter/showViewModeChange/viewModeSelectType/showLunar/useAttendanceHoliday/monthChangeAutoSelectFirstDate/dataSetNodes/baseInfo/historyData/topOperatBtns/bottomOperatBtns/commonConditionSetting/layout/flow/disabled/styles |
-| `Circular`/`BarStack`/`HBar`/`HBarStack`/`Nightingale`/`Gauge`/`Treemap`/`Bubble`（新增图表） | name/type/title/titleEnabled/topOperatBtns/showTopOperatBtnConfig/measures/dimensions/height/[label/chartType/totalTitle 因类型而异]/layout/flow/disabled/styles/filterVersion/hasCssCache |
-| `Picture`（图片） | name/type/title/titleEnabled/footerEnabled/width/height/path/position/imageMode/imgFormat/textTitle/textDescribe/styles/layout/flow/disabled |
-| `NewTab`（标签页） | name/type/title/titleEnabled/footerEnabled/rerender/tabs/addChildAfterSelect/topOperatBtns/layout/flow/disabled/styles/displayName |
-| `CollapsePanel`（折叠面板） | name/type/title/titleEnabled/footerEnabled/panels/spreadType/expandAll/layout/flow/disabled/styles/displayName |
-| `ProgressChart`（进度条） | name/type/title/titleEnabled/rangeColor/dataset/denominator/showText/showName/valueType/layout/flow/disabled/styles |
-| `NavBar`（导航栏） | name/type/title/titleEnabled/navMenus/rightArrow/separator/splitBgColor/layout/flow/disabled/styles |
-| `NavMenu`（导航菜单） | name/type/fixedArea/dataSource/showType/showMore/hideSelf/showPortal/showWorkMessage/navMenus/remember/leftSider/layout/flow/disabled/styles |
-| `CountDown`（倒计时） | name/type/title/titleEnabled/topOperatBtns/timingType/endType/deadline/paramName/countDownSettings/layout/flow/disabled |
-| `SearchGlobal`（搜索框） | name/type/title/titleEnabled/footerEnabled/fixedArea/layout/flow/disabled/styles |
-| `EbButton`（按钮） | name/type/titleEnabled/footerEnabled/btnText/btnType/size/btnKind/groupSize/showExpandIcon/btnGroup/showBtnNum/layout/flow/disabled/styles |
-| `FastCreate`（快速新建） | name/type/title/labelPosition/moduleType/setPersonnel/showTimeField/relatedPersonnel/enterAdd/layout/flow/disabled/styles |
-| `PageHeader`（页头） | name/type/title/titleEnabled/icon/newButtons/underTheTitle/layout/flow/disabled/styles/displayName |
-| `Comment`（评论） | name/type/commentTitle/title/showEmpty/hasEdit/showEditAvatar/showListAvatar/pageSize/showSource/showTime/moduleValue/componentShowType/displaySetting/targetId/layout/flow/disabled/styles |
-
-> 配置流程（**数据绑定的条目结构怎么填，参考 `assets/factory/example-configured.json`（原8组件）/ `example-configured-2.json`（新增20组件）**——已配置好的整页范例，业务值替占位，照 `comps[].config` 里各绑定的真实填充结构填）：
-> 1. `designer comp-add <pageId> --type <Type> --template @<file>` 用 factory 模板（平台初始态）克隆出干净 comp；
-> 2. 参考 `example-configured.json`/`example-configured-2.json` 里同类型 comp 的 `config`，把数据绑定（tableField/measures/dimensions/menuConfig/panels/pics 等）用你自己表单的真实 fieldId/objId 填进去；
-> 3. `designer save`。
->
-> 组件 `type`/`package`/`category`/`applyStyle`/`styleCategoryCompKey`/`styleCategoryPackage` 同样从真实 comp 复制真实值，不编造、不赋空。
->
-> **机器随机 id 硬规则**：页面/组件配置里**所有由工具生成的随机 hex 机器 id 首位都不能是数字**（后端校验，浏览器样本首位恒为 a-f 字母）：`comp.id`(32 位)、图表 `axisId`(32 位)/`shortKey`(7 位，平台数据行/分组键)、NavPanel 菜单项/事件组/事件 id、DigitalPanel panel id 等。CLI `designer chart`/`digital-panel`/`nav-panel` 已统一用 `genLetterHex()`（首位强制 a-f）自动生成；agent 手工改 config 时须遵守同规则。真实数字标识（objId/pageId/formId/字段 id）照常可数字开头，勿动。
->
-> **图标 path 必须带 `#` 前缀**。平台按 path **首字符分流**：`#` 开头走系统图标（`AssetsIcon`），**否则当成图片路径**去加载（`AssetsImg`）—— 所以写 `Icon-Project-o`（漏了 `#`）**不报错，只是静默不显示**，是最难查的一类问题。平台样本与 CLI 默认值都是带 `#` 的（`#icon-eBuilder-o`）。
-> 真要发**图片**才不带 `#`（以 `/`、`./`、`../`、`http(s)://`、`data:` 开头）。CLI 的 `designer nav-panel menu-add --icon` / `designer digital-panel panel-add --icon` / `form button … --icon` 都会**自动补 `#`**（见 `services/icon-path.ts`）；agent 手工改 config 时须自己带上。
->
-> **图标对象的形状按组件分两套，别混用**：
-> - 导航面板 / app：`{path, style:{color, fillType:'borderColor', borderColor}}`
-> - **数字面板 KPI 卡**（`panels[].icon`，真机读回的形状）：`{path, style:{fontSize:36, color, disabled:false, fillType:'backgroundColor', borderColor, bgColor}, iconDisplayType:'line'}` —— `fillType` 是 **`backgroundColor`**，底色键叫 **`bgColor`**（在 `style` 里），`iconDisplayType` 在**图标对象顶层**。没有 `path` 时整块图标不渲染。
->
-> **数字面板的卡 id 硬规则**：`config.panels[]` 里**每张卡的 `id` 必须两两不同**。撞了平台不报错，但设计器里两张卡会互相串。CLI `designer digital-panel panel-add` 会自动避开已占用的 id，并在保存前复查一遍。
-
----
-
-## 加/删组件
-
-加组件 = 向对应 `terminalType` 的 `comps[]` push 一个 config**完整**的新 `LayoutComponentEntity` → `designer save`。删组件 = 从 `comps[]` 移除 → save。
-
-- **comp id**：前端生成的 32 位无连字符 UUID（接口 §4.3 comps id 字段约束）。
-- **config 完整性**：config 字段必须完整，缺字段崩页（ERR-007/008）。
-- **加组件首选 factory 模式**：`designer comp-add <pageId> --type <Type> --template @<file>` 用本 skill 自带的 `assets/factory/factory-<name>.json`（28 组件均有，原8源 2ganjing/新增20源 0805yuanshi 平台初始态、绑定空），克隆后参考 `example-configured.json`/`example-configured-2.json` 填数据绑定。详见 `guide-designer-factory.md`。勿凭空拼装 config（除 Slide 外字段集接口未给，盲造 ERR-007/008）。
-
-> 删组件 = 从 `comps[]` 移除目标 comp 后 `designer save`。
-
----
-
-## 相关指南
-
-- 布局层（info/layout/save/lock/position）→ `guide-designer.md`
-- 自定义 CSS 与组件 DOM 结构索引（`designer css` / `designer dom`）→ `guide-designer-css.md`
-- 工厂模板（comp-add 复制机制）→ `guide-designer-factory.md`
-- 版本层（list/revert）→ `guide-designer-version.md`
-- 命令速查 → `../common/ref-cli-commands.md`「designer」节
+# 设计器组件层指南（骨架）
+
+> 本文件为 `SKILL.md` 的子模块，在用户配置具体组件时加载。
+>
+> **重要**：组件层**不是原生后端接口**——平台没有按组件类型分的 HTTP 端点。所有组件配置最终落地经 `designer save`（POST `/layout/save`，见 `guide-designer.md`）：读布局 → 改 `comps[].config` → 保存。本骨架只给机制与接口能确定的 Slide 字段；**其余组件 config 字段集与取值枚举接口未给，须运行时 inspect 真实页面查 `comp.config`，不凭空构造**（盲造触发 ERR-007/008 崩页）。
+>
+> 本 skill 自包含分发，不依赖任何本机样本文件；"inspect 真实页面"指用户对自己的页面运行 `designer layout <pageId> --json` 查看实际 comp.config，是运行时操作。
+
+---
+
+## 机制说明
+
+所有组件配置的工作流一致：
+
+```bash
+# 1. 导出布局（作为 save 入参基础，取自 /layout/list）。--json 走 stdout，日志走 stderr，故 `>` 只收 JSON 干净；勿 `2>&1` 混入日志
+e10-cli designer layout <pageId> --terminal all --json > layouts.json
+# 2. 定位目标 comp，改 comp.config.<字段>
+# 3. 保存（comps 整体重传）
+e10-cli designer save <pageId> --layouts @layouts.json
+```
+
+> **保真规则**：save 是浅合并，入参取自 `/layout/list`、**只构造 `comps`**（见 `guide-designer.md`「入参数据来源铁律」）。改 comp.config 子字段后，整个 comps 数组随 save 重传；`pageId`/`terminalType`/`module`/`ecodeVersion`/`appId` 等元数据保持原值不动。
+>
+> **save 必须含两端**：`layouts.json` 要含 **PC + MOBILE 两端**（用 `--terminal all` 导出）。只传 PC 端 save 会**覆盖丢失 MOBILE 端布局**（save 是整页覆盖，不是按端 merge）。
+>
+> **PC/MOBILE 同名组件**经 `refCompId` 互连——改一端 config 时注意另一端是否需同步。
+
+### 自定义 CSS
+
+组件的外观有两层：`comp.config.styles[N].customStyle` 下的**图形化样式块**（`title`/`content`/`footer`/`container` 的字号、背景、边框等），以及其中的 **`base.codeSource` 自由文本 CSS**。后者就是需求里说的「自定义 CSS」。
+
+- 干净组件的 `styles` 是**空数组**；Picture/CountDown 之类自带**主题绑定记录**（`useComStyle:true`），与自由 CSS 记录是两回事，**不要碰**。
+- 不要绕开命令直接改布局 JSON，也不要去动 `sourceCode.cssCache`（平台的编译产物）。
+- 用 `e10-cli designer css read/write` 读写，用 `e10-cli designer dom <type>` 查该组件的 DOM 结构来写选择器。
+
+完整契约、选择器作用域速查、27 个组件的 DOM 文档对照表与各条坑 → `guide-designer-css.md`。
+
+---
+
+## 接口给出的组件字段（Slide 一例）
+
+接口文档（layout-save §4.3 config 内部结构 + §6.1 完整 Slide 入参）只给 Slide 一个完整 config 示例。**只有 Slide 的字段名是接口确定的**，可照此修改：
+
+| config 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | String | 组件显示名 |
+| `title` / `titleEnabled` | String / Boolean | 标题文本 / 是否启用 |
+| `footerEnabled` | Boolean | 是否启用页脚 |
+| `pics` | Array | 图片列表 |
+| `imageMode` | String | 图片填充模式 |
+| `switchEffect` | String | 切换效果 |
+| `intervalTime` | Object | 轮播间隔 `{type, value}` |
+| `speed` | Integer | 切换速度（ms） |
+| `lazyLoad` | Boolean | 是否懒加载 |
+| `imgSourceType` | String | 图片来源类型 |
+| `eventGroup` | Array | 事件配置列表 |
+| `filter` | **Object** | 数据过滤条件（HTTP 契约：filter 类型为 Object，传 `[]` 与契约不符） |
+| `showNum` | Integer | 展示数量 |
+| `layout` | Object | 栅格布局 `{i, x, y, w, h, ...}` |
+| `flow` / `disabled` | Object | 流程 / 禁用配置 |
+
+> **需 inspect 真实页面查原始值**：上表**字段名**来自接口 Slide 示例；但 `imageMode`/`switchEffect`/`imgSourceType` 等字段的**完整取值枚举接口未给**（示例仅各一例）——须 inspect 自己已配好的 Slide 组件查可选值，勿凭枚举造。
+
+---
+
+## 其余组件（Calendar / DigitalPanel / Chart / NavPanel / List 等）
+
+> 除 Slide 外，各组件 config 字段集与取值枚举**接口文档均未给出**。下表**字段名**来自示例页面结构（非穷尽、非权威，以 inspect 真实页面为准）；**取值**一律须运行时 inspect 自己的页面 `comp.config` 查，不赋空值（`字段=''`/`[]`/`{}` 凭空造值会触发 ERR-007/008）。
+
+| 组件 type | config 顶层字段（结构示例，取值须 inspect） |
+|---|---|
+| `DigitalPanel` | name/type/title/titleEnabled/footerEnabled/panels/showmode/columns/timedRefresh/layout/flow/disabled/styles |
+| `NavPanel` | name/type/title/titleEnabled/column/pageColumn/enableGroup/menuConfig/menuSourceType/showSearch/commonMenu*/groupMode/openType/userSource/groupBrowser/menuBrowser/menuDisplayRange/externalDataInterfaceSetting/actionTemplateStr/layout/flow/disabled/styles |
+| `Pie` / `Bar` / `Line`（图表） | name/type/title/titleEnabled/topOperatBtns/measures/dimensions/height/barType(Bar)/label(Bar)/filterVersion/dataset/filter/searchConditions/dataListDisplay/xAxis/yAxis/showTotal/showLimit/hideForNoData/tools/layout/flow/disabled/styles |
+| `NList`（列表） | name/type/mode/pageMode/title/titleEnabled/footerEnabled/pageSize/headMerge/listVersion/dataset/order/filter/tableField/personalFields/searchConditions/enableGroup/filterIsNull/isFilterSub/version/rootStr/fieldUsage/layout/flow/disabled/styles |
+| `Calendar`（日历） | name/type/title/titleEnabled/footerEnabled/calendarType/condition/defaultView/weekStart/filter/showViewModeChange/viewModeSelectType/showLunar/useAttendanceHoliday/monthChangeAutoSelectFirstDate/dataSetNodes/baseInfo/historyData/topOperatBtns/bottomOperatBtns/commonConditionSetting/layout/flow/disabled/styles |
+| `Circular`/`BarStack`/`HBar`/`HBarStack`/`Nightingale`/`Gauge`/`Treemap`/`Bubble`（新增图表） | name/type/title/titleEnabled/topOperatBtns/showTopOperatBtnConfig/measures/dimensions/height/[label/chartType/totalTitle 因类型而异]/layout/flow/disabled/styles/filterVersion/hasCssCache |
+| `Picture`（图片） | name/type/title/titleEnabled/footerEnabled/width/height/path/position/imageMode/imgFormat/textTitle/textDescribe/styles/layout/flow/disabled |
+| `NewTab`（标签页） | name/type/title/titleEnabled/footerEnabled/rerender/tabs/addChildAfterSelect/topOperatBtns/layout/flow/disabled/styles/displayName |
+| `CollapsePanel`（折叠面板） | name/type/title/titleEnabled/footerEnabled/panels/spreadType/expandAll/layout/flow/disabled/styles/displayName |
+| `ProgressChart`（进度条） | name/type/title/titleEnabled/rangeColor/dataset/denominator/showText/showName/valueType/layout/flow/disabled/styles |
+| `NavBar`（导航栏） | name/type/title/titleEnabled/navMenus/rightArrow/separator/splitBgColor/layout/flow/disabled/styles |
+| `NavMenu`（导航菜单） | name/type/fixedArea/dataSource/showType/showMore/hideSelf/showPortal/showWorkMessage/navMenus/remember/leftSider/layout/flow/disabled/styles |
+| `CountDown`（倒计时） | name/type/title/titleEnabled/topOperatBtns/timingType/endType/deadline/paramName/countDownSettings/layout/flow/disabled |
+| `SearchGlobal`（搜索框） | name/type/title/titleEnabled/footerEnabled/fixedArea/layout/flow/disabled/styles |
+| `EbButton`（按钮） | name/type/titleEnabled/footerEnabled/btnText/btnType/size/btnKind/groupSize/showExpandIcon/btnGroup/showBtnNum/layout/flow/disabled/styles |
+| `FastCreate`（快速新建） | name/type/title/labelPosition/moduleType/setPersonnel/showTimeField/relatedPersonnel/enterAdd/layout/flow/disabled/styles |
+| `PageHeader`（页头） | name/type/title/titleEnabled/icon/newButtons/underTheTitle/layout/flow/disabled/styles/displayName |
+| `Comment`（评论） | name/type/commentTitle/title/showEmpty/hasEdit/showEditAvatar/showListAvatar/pageSize/showSource/showTime/moduleValue/componentShowType/displaySetting/targetId/layout/flow/disabled/styles |
+
+> 配置流程（**数据绑定的条目结构怎么填，参考 `assets/factory/example-configured.json`（原8组件）/ `example-configured-2.json`（新增20组件）**——已配置好的整页范例，业务值替占位，照 `comps[].config` 里各绑定的真实填充结构填）：
+> 1. `designer comp-add <pageId> --type <Type> --template @<file>` 用 factory 模板（平台初始态）克隆出干净 comp；
+> 2. 参考 `example-configured.json`/`example-configured-2.json` 里同类型 comp 的 `config`，把数据绑定（tableField/measures/dimensions/menuConfig/panels/pics 等）用你自己表单的真实 fieldId/objId 填进去；
+> 3. `designer save`。
+>
+> 组件 `type`/`package`/`category`/`applyStyle`/`styleCategoryCompKey`/`styleCategoryPackage` 同样从真实 comp 复制真实值，不编造、不赋空。
+>
+> **机器随机 id 硬规则**：页面/组件配置里**所有由工具生成的随机 hex 机器 id 首位都不能是数字**（后端校验，浏览器样本首位恒为 a-f 字母）：`comp.id`(32 位)、图表 `axisId`(32 位)/`shortKey`(7 位，平台数据行/分组键)、NavPanel 菜单项/事件组/事件 id、DigitalPanel panel id 等。CLI `designer chart`/`digital-panel`/`nav-panel` 已统一用 `genLetterHex()`（首位强制 a-f）自动生成；agent 手工改 config 时须遵守同规则。真实数字标识（objId/pageId/formId/字段 id）照常可数字开头，勿动。
+>
+> **图标 path 必须带 `#` 前缀**。平台按 path **首字符分流**：`#` 开头走系统图标（`AssetsIcon`），**否则当成图片路径**去加载（`AssetsImg`）—— 所以写 `Icon-Project-o`（漏了 `#`）**不报错，只是静默不显示**，是最难查的一类问题。平台样本与 CLI 默认值都是带 `#` 的（`#icon-eBuilder-o`）。
+> 真要发**图片**才不带 `#`（以 `/`、`./`、`../`、`http(s)://`、`data:` 开头）。CLI 的 `designer nav-panel menu-add --icon` / `designer digital-panel panel-add --icon` / `form button … --icon` 都会**自动补 `#`**（见 `services/icon-path.ts`）；agent 手工改 config 时须自己带上。
+>
+> **图标对象的形状按组件分两套，别混用**：
+> - 导航面板 / app：`{path, style:{color, fillType:'borderColor', borderColor}}`
+> - **数字面板 KPI 卡**（`panels[].icon`，真机读回的形状）：`{path, style:{fontSize:36, color, disabled:false, fillType:'backgroundColor', borderColor, bgColor}, iconDisplayType:'line'}` —— `fillType` 是 **`backgroundColor`**，底色键叫 **`bgColor`**（在 `style` 里），`iconDisplayType` 在**图标对象顶层**。没有 `path` 时整块图标不渲染。
+>
+> **数字面板的卡 id 硬规则**：`config.panels[]` 里**每张卡的 `id` 必须两两不同**。撞了平台不报错，但设计器里两张卡会互相串。CLI `designer digital-panel panel-add` 会自动避开已占用的 id，并在保存前复查一遍。
+
+---
+
+## 加/删组件
+
+加组件 = 向对应 `terminalType` 的 `comps[]` push 一个 config**完整**的新 `LayoutComponentEntity` → `designer save`。删组件 = 从 `comps[]` 移除 → save。
+
+- **comp id**：前端生成的 32 位无连字符 UUID（接口 §4.3 comps id 字段约束）。
+- **config 完整性**：config 字段必须完整，缺字段崩页（ERR-007/008）。
+- **加组件首选 factory 模式**：`designer comp-add <pageId> --type <Type> --template @<file>` 用本 skill 自带的 `assets/factory/factory-<name>.json`（28 组件均有，原8源 2ganjing/新增20源 0805yuanshi 平台初始态、绑定空），克隆后参考 `example-configured.json`/`example-configured-2.json` 填数据绑定。详见 `guide-designer-factory.md`。勿凭空拼装 config（除 Slide 外字段集接口未给，盲造 ERR-007/008）。
+
+> 删组件 = 从 `comps[]` 移除目标 comp 后 `designer save`。
+
+---
+
+## 相关指南
+
+- 布局层（info/layout/save/lock/position）→ `guide-designer.md`
+- 自定义 CSS 与组件 DOM 结构索引（`designer css` / `designer dom`）→ `guide-designer-css.md`
+- 工厂模板（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)。