weaver-e10-builder 1.2.2 → 1.2.5

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

@@ -26,6 +26,16 @@ e10-cli designer save <pageId> --layouts @layouts.json
 >
 > **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 一例）
@@ -104,7 +114,8 @@ e10-cli designer save <pageId> --layouts @layouts.json
 
 ## 相关指南
 
-- 布局层（info/layout/save/lock/theme/position）→ `guide-designer.md`
+- 布局层（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」节

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

@@ -0,0 +1,127 @@
+# 页面组件自定义 CSS
+
+需求里出现「给这个组件调样式」「自定义 CSS」「改选择器」「样式不生效」「DOM 结构」时读本篇。组件 config 字段见 `guide-designer-components.md`，布局读写机制见 `guide-designer.md`。
+
+## 定位与职责边界
+
+自定义 CSS 写在**组件**上，形如：
+
+```
+comp.config.styles[N].customStyle.base.codeSource   ← 自由文本 CSS
+```
+
+- **页面级没有自由 CSS 槽位**。`layout.config.style` 里只有结构化的 `page.margin/padding/background`。想整页统一风格，只能往组件上写。
+- **CLI 只负责写**：写对、写稳、写后回读比对。样式在页面上如何渲染、样式缓存如何编译，是平台的事，命令不做判断也不承诺。
+- **一个页面有 PC/MOBILE 两套布局，每个终端各有一份组件**，靠互指 `refCompId` 配对。设计器本身就是双端同写，所以 `css write` 默认也双端。
+
+## `styles` 记录契约
+
+`comp.config.styles` 是数组，里面有**两种互不相干的记录**，标志位正好相反：
+
+| | 自由 CSS 记录 | 主题绑定记录 |
+|---|---|---|
+| 形态 | `{category, useCustom:true, useComStyle:false, styleVersion, customStyle:{…}}` | `{id, category, customType, useCustom:false, themeId, useComStyle:true}` |
+| 来源 | 用户/CLI 写的自定义样式 | 组件自带的外观主题（Picture、CountDown 的模板就带） |
+| CLI 行为 | 读它、写它 | **绝不碰**（写 CSS 时追加一条新记录，不动它） |
+
+干净组件的 `styles` 是**空数组 `[]`**。三种输入状态及对应行为：
+
+1. `styles` 为空 → 新建一条记录（只需 `category`/`useCustom`/`useComStyle`/`styleVersion` + `customStyle.base.codeSource` 四个键）。
+2. 已有自由记录 → **外科式**只换 `customStyle.base.codeSource`，`customStyle` 下的 `title`/`content`/`footer`/`container` 等图形化样式块与记录的其它字段原样保留。
+3. 只有主题绑定记录 → **追加**一条自由记录，第 0 条一字不动。
+
+## 命令
+
+```bash
+# 读（默认双端；compId 给 PC 或 MOBILE 任一端的都可以）
+e10-cli designer css read <pageId> <compId> [--terminal pc|mobile|both] [--json]
+
+# 写（默认双端、默认整段替换）
+e10-cli designer css write <pageId> <compId> --css "<CSS>"
+e10-cli designer css write <pageId> <compId> --css-file <路径>
+e10-cli designer css write <pageId> <compId> --css "<CSS>" --append
+e10-cli designer css write <pageId> <compId> --clear
+e10-cli designer css write <pageId> <compId> --css "<CSS>" --terminal pc
+```
+
+- **`--css` 与 `--css-file` 是两个选项，没有 `@file` 约定。** `@media` 开头的 CSS 是合法写法，用 `@文件` 会被当成路径。
+- `--append` **非幂等**：重复跑会重复追加。想改内容用整段替换。
+- `--clear` 清空内容但**保留记录**（不动 `customStyle` 其它块）。
+- 两端现有 CSS **都非空且不一致**时，双端写会覆盖其中一端 —— 命令会拦下并点名两端字节数，确认覆盖加 `--yes`，只想改一端用 `--terminal`。
+- 写完会**回读比对**；对不上直接报错（服务端可能没落库或改写了形状），用 `css read` 看实际值。
+
+## 写选择器：**不要写组件 id**
+
+**`customStyle.base.codeSource` 是组件级的** —— 每段 CSS 本来就只属于它所在的那个组件，平台在编译时会自己套上 `#<comId>` 限域。所以源码里**再写一遍 id 是错的**：
+
+```css
+/* ✅ 对：直接写类名 */
+.ebcoms-navPanel-wrapper-square { border-radius: 12px; }
+.content { background: #070d1a; }
+
+/* ❌ 错：多写了组件 id */
+#f3708b2387bd757a336ab0e176243801 .ebcoms-navPanel-wrapper-square { … }
+```
+
+写进去会怎样：轻则多余，重则**不生效** —— 一个页面 PC 与 MOBILE 是两份布局、两个不同的实例 id，同一段 CSS 双端同时写时（设计器自己就是双端同写、两端 `codeSource` 一模一样），写死哪一端的 id，另一端就必不匹配。
+
+> 组件 DOM 文档里说的「官方样式生成器一律以 `#<comId>` 限域」，讲的是**编译产物**（`sourceCode.cssCache`）长什么样，**不是叫你写在源码里**。
+
+组件 DOM 由三层拼出来，**类名前缀区分来源**：
+
+| 前缀 | 来源 |
+|---|---|
+| `ebcom-` | 引擎/框架层（源码里搜不到，由引擎外壳生成） |
+| `ebcoms-` | 组件自己写的 |
+| `ui-` | `@weapp/ui` 第三方组件追加的 |
+
+- 引擎外壳的 `id` 与挂在组件根上的 `data-id` 都是组件实例 id —— **它们是给平台编译用的，不要写进你的选择器**。
+- 页面层外壳是 `#ebpage_<pageId>`，同样**别拿它定位组件**。
+- 各组件的 `ebcom-*` 外壳类名不统一（如 NList → `ebcom-nlist`、CountDown → `ebcom-countdown`、CollapsePanel → `ebcom-collapsepanel`），以 DOM 结构文档为准，不要凭类型名拼。
+
+写样式时：**只写类名，不写 id**；**不要杜撰类名**（拼错就是静默不生效）；尽量不用 `!important` 去压默认样式。
+
+## 查 DOM 结构：`designer dom`
+
+内置 **27 个组件**的 DOM 结构索引，随 skill 资产分发，用来把「用户说的部位」翻成选择器。
+
+```bash
+e10-cli designer dom-list                    # 全表：类型 / 体量 / 组件名
+e10-cli designer dom NList --keys            # 先看骨架：usage / pickTree / legend / 各区块体量
+e10-cli designer dom NList --section shared.title        # 只取需要的子树
+e10-cli designer dom NList --section shared.title --refs # 就地展开 {"ref":"shared.x"}
+```
+
+**先 `--keys` 再 `--section`**：文档中位数 20 多 KB，整份打出来很占上下文，而 `usage`/`pickTree`/`legend` 三段散文才是找对树的关键。
+
+文档里的记号（各文件自己的 `legend` 也有解释）：
+
+| 记号 | 含义 |
+|---|---|
+| `[cls]` | 条件类名，满足业务条件才挂 |
+| `{a\|b}` | 同一个位置按配置二选一 |
+| `a > b` | 父子层级压缩写法 |
+| `<comId>` | 组件实例 id。**只出现在文档对编译产物的描述里**，写源码选择器时不要用（见上） |
+| `ref:shared.x` / `{"ref":"shared.x"}` | 引用同文件的复用片段，用 `--refs` 展开 |
+| `uncontrolled` | 第三方（`@weapp/ui` 等）渲染，只给挂载点 |
+
+覆盖的 27 个组件（命令按**平台组件 type** 取，也认下面的常见写法）：
+
+| 平台 type | 也认 | 平台 type | 也认 |
+|---|---|---|---|
+| `NavPanel` | nav-panel | `NList` | nlist、n-list |
+| `NavBar` | nav-bar | `DigitalPanel` | digitalpanel、digital-panel |
+| `ProgressChart` | progress-bar、progressbar | `PageHeader` | pageheader、page-header |
+| `EbButton` | eb-button | `CountDown` | count-down |
+| `FastCreate` | fast-create | `SearchGlobal` | search-global |
+| `CollapsePanel` | collapse-panel | `NewTab` | new-tab |
+| `Comment` / `Picture` / `Slide` / `Calendar` | — | `Bar`/`BarStack`/`Line`/`HBar`/`HBarStack`/`Pie`/`Circular`/`Nightingale`/`Gauge`/`Treemap`/`Bubble` | — |
+
+`NavMenu`、`InternalContainer` **暂无**文档，命令会直接说明并列出已覆盖清单。
+
+## 坑
+
+- **注释不会被编译进去**，但 CLI 写进去时**原样保存**，回读比对会按去掉注释后比 —— 所以带注释的原文是安全的。
+- **MOBILE 端的布局不返回样式缓存**，双端写完之后想确认效果，看 PC 端更省事。
+- **别手写 `sourceCode.cssCache`** —— 那是平台的编译产物，手写会和下次编译打架。
+- 改完布局记得收尾 `designer unlock`（多人协作防并发；`/layout/save` 本身不校验锁）。

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

@@ -17,15 +17,16 @@
 | `e10-cli designer layout <pageId> --json` | 导出布局 JSON 文件，供 save/comp-add 复用（`--json` 是全局选项，非 layout 专属隐藏） | GET `/layout/list`（落地为文件） |
 | `e10-cli designer save <pageId> --layouts <json\|@file> [--page-name] [--sync-outdate]` | 保存布局（CLI 内部 LZ 压缩后 POST）。`--layouts` 必填（**不是位置参数**） | POST `/layout/save` |
 | `e10-cli designer lock <pageId>` / `designer unlock <pageId>` | 锁定/解锁页面 | POST `/layout/lock` |
-| `e10-cli designer theme <pageId> <themeId> [--terminal <PC\|MOBILE>]` | 给页面设置主题（`--terminal` 默认 PC） | POST `/layout/refTheme` |
-| `e10-cli designer theme-list <pageId>` / `designer theme-info <pageId>` | 查可选主题列表 / 当前主题详情 | 契约外 `/theme/list`、`/theme/info` |
+| `e10-cli designer css read <pageId> <compId> [--terminal <pc\|mobile\|both>]` | 读组件自定义 CSS（默认双端；`<compId>` 给任一端都行） | GET `/layout/list` |
+| `e10-cli designer css write <pageId> <compId> (--css <文本> \| --css-file <路径>) [--append\|--clear] [--terminal] [--yes]` | 写组件自定义 CSS（默认**双端同写**、默认整段替换）。写后回读比对，对不上报错 | POST `/layout/save` |
+| `e10-cli designer dom-list` / `designer dom <type> [--keys] [--section <path>] [--refs]` | 查写 CSS 要用的**组件 DOM 结构索引**（27 个组件；先 `--keys` 看骨架，再 `--section` 取子树） | 读随包资产 |
 | `e10-cli designer position <pageId> <compId> --x --y --w --h` | 调组件栅格位置（PC，封装 `/layout/save`：改 `config.layout.x/y/w/h` 后 save） | POST `/layout/save` |
 | `e10-cli designer comp-add <pageId> --type <Type> [--template @<file>] [--from <srcPage> --comp <id>] [--x --y --w --h]` | 加组件（封装 `/layout/save`）。**`--type` 是选项不是位置参数**。两种取源：`--type --template @<file>`（factory 模板，见 `guide-designer-factory.md`）/ `--from <srcPage> --comp <id>`（从活页克隆）。`--h` 按该指南「组件高度判断」自行算 | POST `/layout/save` |
 | `e10-cli designer comp-remove <pageId> <compId>` | 移除组件（含 PC/MOBILE refCompId 两端） | POST `/layout/save` |
-| `e10-cli designer comp-library <pageId> [--custom] [--json]` | 查页面可用组件库（只读目录，不含 config 模板；加组件仍走 `comp-add --template`） | 契约外 `/api/ebuilder/coms/component/list` |
-| `e10-cli designer style <pageId> <compId>` / `designer style-set <pageId> <compId> --var <name> --value <val>` | 查/改组件视觉样式（CSS 变量；style-set best-effort、非持久） | 改 `sourceCode.cssCache.ebd_style_lib` + `/layout/save` |
 
-> 组件 config 字段名与配置机制见 `guide-designer-components.md`；版本 list/revert 见 `guide-designer-version.md`。
+> **页面主题（`/layout/refTheme`）、页面可用组件库（`/api/ebuilder/coms/component/list`）这两类接口目前没有 CLI 命令封装**，故不列在此表 —— 上表只列**实际可执行**的命令。
+
+> 组件 config 字段名与配置机制见 `guide-designer-components.md`；自定义 CSS 与 DOM 结构索引见 `guide-designer-css.md`；版本 list/revert 见 `guide-designer-version.md`。
 
 ---