weaver-e10-builder 1.6.15 → 1.6.16

package/skill-docs/references/common/capability-boundaries.md

@@ -1,36 +1,36 @@
-# 平台与 CLI 能力边界
-
-> 判「不支持」必须带证据（见下方证据等级）。**CLI 没暴露 ≠ 平台不支持**：命令表只能证明执行器没有，不能升级成平台结论。
-
-## 已支持、容易误判为「不支持」的能力
-
-| 能力 | 结论 | 命令 |
-|---|---|---|
-| 移动端菜单（H5） | 支持。移动端与 PC 是**两套独立记录**（同一 `savePublishMenu`，只换 `terminalType`），可独立增删改；也能把 PC 端菜单整体同步到移动端 | 菜单类命令加 `--terminal mobile`；同步用 `menu sync <appId>` |
-
-## 判断「CLI 支不支持」的正确方式
-
-1. 先查 `references/common/ref-cli-commands.md` 的对应命令与参数；
-2. 再跑 `e10-cli <命令> --help` 确认当前版本有没有该选项；
-3. 能只读验证的，做一次只读查询或回读并记录结果；
-4. 仍无法确认时，标「待环境核查」或「未证实」，不要猜；必要时问用户；
-5. 已确认做不到或只能部分做到时，写进 `plan.md` 的 0.1 和「待确认、需补充及无法实现」一节，保持 `[ ]`。
-
-**禁止绕行**：不要为了完成配置临时编写 `.mjs` 脚本调用内部接口，也不要让用户直接操作浏览器或设计器代替命令；确认没有命令时，保留该项未完成状态并说明影响。
-
-## 证据等级（写预检结论 / 边界表时必填）
-
-| 等级 | 含义 | 能否对外说「不支持」 |
-|---|---|---|
-| 实测 | 有平台原始回执，或写后有独立回读 | 可以，注明环境和日期 |
-| 回读字段 | 平台返回体里确有该字段，语义未必实测 | 不能直接判「不支持」 |
-| 命令表 | 只能证明**当前 CLI 没暴露** | **不能**；命令没暴露不等于平台不支持 |
-| 未证实 | 有结论、无证据 | **不能**对外宣称 |
-
-> 「选项表/命令表」只证明执行器没暴露，不能升级成「平台不提供」。需要平台结论时，先补实测或回读证据；没有证据就写「待环境核查」。
-
-## 边界记录格式
-
-| 需求 | 结论 | 证据等级 | 依据 | 影响与处理 |
-|---|---|---|---|---|
-| <需求项> | 可做 / 部分可做 / 做不到 / 待环境核查 | 实测 / 回读字段 / 命令表 / 未证实 | <具体命令、回执或文档> | <保留未完成、替代方式或需用户决定> |
+# 平台与 CLI 能力边界
+
+> 判「不支持」必须带证据（见下方证据等级）。**CLI 没暴露 ≠ 平台不支持**：命令表只能证明执行器没有，不能升级成平台结论。
+
+## 已支持、容易误判为「不支持」的能力
+
+| 能力 | 结论 | 命令 |
+|---|---|---|
+| 移动端菜单（H5） | 支持。移动端与 PC 是**两套独立记录**（同一 `savePublishMenu`，只换 `terminalType`），可独立增删改；也能把 PC 端菜单整体同步到移动端 | 菜单类命令加 `--terminal mobile`；同步用 `menu sync <appId>` |
+
+## 判断「CLI 支不支持」的正确方式
+
+1. 先查 `references/common/ref-cli-commands.md` 的对应命令与参数；
+2. 再跑 `e10-cli <命令> --help` 确认当前版本有没有该选项；
+3. 能只读验证的，做一次只读查询或回读并记录结果；
+4. 仍无法确认时，标「待环境核查」或「未证实」，不要猜；必要时问用户；
+5. 已确认做不到或只能部分做到时，写进 `plan.md` 的 0.1 和「待确认、需补充及无法实现」一节，保持 `[ ]`。
+
+**禁止绕行**：不要为了完成配置临时编写 `.mjs` 脚本调用内部接口，也不要让用户直接操作浏览器或设计器代替命令；确认没有命令时，保留该项未完成状态并说明影响。
+
+## 证据等级（写预检结论 / 边界表时必填）
+
+| 等级 | 含义 | 能否对外说「不支持」 |
+|---|---|---|
+| 实测 | 有平台原始回执，或写后有独立回读 | 可以，注明环境和日期 |
+| 回读字段 | 平台返回体里确有该字段，语义未必实测 | 不能直接判「不支持」 |
+| 命令表 | 只能证明**当前 CLI 没暴露** | **不能**；命令没暴露不等于平台不支持 |
+| 未证实 | 有结论、无证据 | **不能**对外宣称 |
+
+> 「选项表/命令表」只证明执行器没暴露，不能升级成「平台不提供」。需要平台结论时，先补实测或回读证据；没有证据就写「待环境核查」。
+
+## 边界记录格式
+
+| 需求 | 结论 | 证据等级 | 依据 | 影响与处理 |
+|---|---|---|---|---|
+| <需求项> | 可做 / 部分可做 / 做不到 / 待环境核查 | 实测 / 回读字段 / 命令表 / 未证实 | <具体命令、回执或文档> | <保留未完成、替代方式或需用户决定> |

package/skill-docs/references/common/guide-install.md

@@ -1,44 +1,44 @@
-# 安装、升级与文档同步
-
-## 版本必须匹配
-
-skill 与 CLI 的版本要一致（见 SKILL.md frontmatter 的 `version`）。版本不一致时，命令、选项和文档可能对不上。
-
-```bash
-e10-cli --version          # 应与 SKILL.md 标注的版本一致
-npm install -g weaver-e10-builder
-```
-
-## CLI 升级
-
-- 一般工具：先 `npm rm -g weaver-e10-builder` 卸掉旧包，再重新安装，避免 bin 残留冲突。
-- WorkBuddy：先直接用 bash 删除旧包目录（不走 npm 删除），再用 npm 纯安装，并指定一个有权限的工作目录作为缓存地址。
-
-## skill 安装 / 升级
-
-先卸旧（旧名 `skill-e10-cli`），再装新：
-
-```bash
-npx -y skills remove skill-e10-cli
-npx -y skills add ./weaver-e10-builder.zip --skill -y
-```
-
-`skills remove` 无效时手动删除后再 add：
-
-- Claude Code：`rm -rf ~/.claude/skills/skill-e10-cli` → 新 skill 装到 `~/.claude/skills/weaver-e10-builder`
-- WorkBuddy：`rm -rf ~/.workbuddy/skills/skill-e10-cli` → 新 skill 装到 `~/.workbuddy/skills/weaver-e10-builder`
-
-## 文档树同步
-
-1.1.0 起发布的 skill 是**薄指令层**：只带 SKILL.md、`_catalog.md`、actionflows 指令层和 scripts，不含深目录文档树（适配 marketplace 两级目录限制）。完整文档随配套 CLI 的 `skill-docs` 分发。
-
-- 每次 `e10-cli auth status` 会自动探测本机已装 skill（`~/.claude/skills`、`~/.workbuddy/skills`、`~/.codex/skills`）并同步文档；版本一致则跳过。
-- 手动刷新：`e10-cli skill sync`；可 `--target <安装根目录>` 指定其他工具目录。
-- 装完 skill 后看到 references 文档多出/更新、旧文档被清理，都是正常的同步现象，不是装错或重复安装。
-- 读 `references/...` 提示文件不存在 → 先 `e10-cli skill sync`，或确认 skill 已装后重跑 `e10-cli auth status`。
-
-## 文档读取与模板拷贝
-
-- 文档在 skill 目录内（如 `~/.claude/skills/weaver-e10-builder/`），`references/...`、`actionflows/...`、`assets/...` 均相对该目录。
-- 按决策树命中哪个读哪个，不要一次性全部读入。
-- 页面模板用 `e10-cli skill copy [目录]` 拷到工作区（默认当前目录，放出 `references/`、`actionflows/`、`assets/`）。
+# 安装、升级与文档同步
+
+## 版本必须匹配
+
+skill 与 CLI 的版本要一致（见 SKILL.md frontmatter 的 `version`）。版本不一致时，命令、选项和文档可能对不上。
+
+```bash
+e10-cli --version          # 应与 SKILL.md 标注的版本一致
+npm install -g weaver-e10-builder
+```
+
+## CLI 升级
+
+- 一般工具：先 `npm rm -g weaver-e10-builder` 卸掉旧包，再重新安装，避免 bin 残留冲突。
+- WorkBuddy：先直接用 bash 删除旧包目录（不走 npm 删除），再用 npm 纯安装，并指定一个有权限的工作目录作为缓存地址。
+
+## skill 安装 / 升级
+
+先卸旧（旧名 `skill-e10-cli`），再装新：
+
+```bash
+npx -y skills remove skill-e10-cli
+npx -y skills add ./weaver-e10-builder.zip --skill -y
+```
+
+`skills remove` 无效时手动删除后再 add：
+
+- Claude Code：`rm -rf ~/.claude/skills/skill-e10-cli` → 新 skill 装到 `~/.claude/skills/weaver-e10-builder`
+- WorkBuddy：`rm -rf ~/.workbuddy/skills/skill-e10-cli` → 新 skill 装到 `~/.workbuddy/skills/weaver-e10-builder`
+
+## 文档树同步
+
+1.1.0 起发布的 skill 是**薄指令层**：只带 SKILL.md、`_catalog.md`、actionflows 指令层和 scripts，不含深目录文档树（适配 marketplace 两级目录限制）。完整文档随配套 CLI 的 `skill-docs` 分发。
+
+- 每次 `e10-cli auth status` 会自动探测本机已装 skill（`~/.claude/skills`、`~/.workbuddy/skills`、`~/.codex/skills`）并同步文档；版本一致则跳过。
+- 手动刷新：`e10-cli skill sync`；可 `--target <安装根目录>` 指定其他工具目录。
+- 装完 skill 后看到 references 文档多出/更新、旧文档被清理，都是正常的同步现象，不是装错或重复安装。
+- 读 `references/...` 提示文件不存在 → 先 `e10-cli skill sync`，或确认 skill 已装后重跑 `e10-cli auth status`。
+
+## 文档读取与模板拷贝
+
+- 文档在 skill 目录内（如 `~/.claude/skills/weaver-e10-builder/`），`references/...`、`actionflows/...`、`assets/...` 均相对该目录。
+- 按决策树命中哪个读哪个，不要一次性全部读入。
+- 页面模板用 `e10-cli skill copy [目录]` 拷到工作区（默认当前目录，放出 `references/`、`actionflows/`、`assets/`）。

package/skill-docs/references/common/ref-cli-commands.md

@@ -91,6 +91,14 @@
 | `e10-cli form edit-field <objId> <appId> <fieldId> [选项]` | 编辑字段属性，**主表与明细表字段均可**（明细字段按 fieldId 自动定位所属明细表）。`--title` 显示名、**`--type <类型>` 改字段类型**（取值同 `add-field`，如 `Text`/`Number`/`Date`/`Select`/`Department`；走读-改-写，**不用删字段重建**，显示名/列名/位置都保留；改成 `EBuilder`/`Flow` 必须同时给 `--sform-id`）、`--required`/`--no-required`、`--sform-id`（改EBuilder关联）、`--relate-from`（值带出）、**`--multiple`/`--no-multiple`**（人员/部门/EBuilder/Browser 多选切换）、**`--data-title`**（关联字段的标题栏，写 `dataTitle`）。**`--required`/`--no-required` 写的是布局组件**（必填只存在于布局里，字段定义没有这个键），命令会顺带把布局一并保存。改成 `EBuilder` 或换关联表时，**浏览显示列按新目标表自动补齐**（只在没配过、或旧列不属于新目标表时才写，不冲掉手工配的）。**`--data-key` / `--column-name` 分别改字段编码与数据库列名**（两者独立；只给 `--data-key` 时列名跟随）。`--title` / `--data-key` / `--column-name` / `--desc` 保存后**逐项回读校验**，平台返回 200 却未落库时明确报错。**⚠ 字段已有数据时平台拒绝改动结构**（显示名例外）——报「此列已存在数据不可修改数据库字段名称」，该文案与实际情况不符，它拦的不止字段名 |
 | `e10-cli form field-lang get <objId> <appId> <fieldId>` | 查看字段名称的中英文多语言配置；未配置时返回当前中文名称和 `configured:false` |
 | `e10-cli form field-lang set <objId> <appId> <fieldId> --zh <中文> --en <English>` | 设置字段名称多语言。先保存多语言标签，再读取完整字段并回写 `labelObj.title`，不会覆盖字段其他属性 |
+| `e10-cli form description get <objId> <appId>` | 查看**表单说明**（`description`，表单基本信息里的说明文字；与表单名称、自定义标题是分开的三套） |
+| `e10-cli form description set <objId> <appId> [<说明>] [--clear]` | 设置**表单说明**，`--clear` 清空；多行文本用 `@文件`。走 `obj/saveOrUpdate` 整对象回写（读回全字段 → 只换 `description` → 剔除标题字段与只读字段回写 → 回读校验），不影响名称/标题/日志等其它字段。内容未变化时不发写请求 |
+| `e10-cli form log-setting get <objId> <appId>` | 查看**日志设置**（表单基本信息「表单」页的日志设置）：卡片详情页显示日志（`enableLog`）、记录类型（`logTypes`：查阅情况=1 / 操作日志=2 / 表单修改日志=3 / 打印日志=4）、表单修改日志显示方式（`formLogShowType`：`group`=分组 / `tile`=平铺）、日志展示模式（`dataLogShowType`，已确认 `single`=单个展示） |
+| `e10-cli form log-setting set <objId> <appId> [--show-log on\|off] [--log-types <列表>] [--form-log-show-type group\|tile]` | 修改日志设置：`--log-types` 用逗号分隔的 chip 名称或数字（如 `操作日志,打印日志`），清空用 `none`；只改点名的项，走 `obj/saveOrUpdate` 整对象回写并回读校验，不影响表单说明/名称/标题等其它字段 |
+| `e10-cli form name-lang get <objId> <appId>` | 查看**表单名称**的中英文与多语言标签 id；未配置时返回当前名称和 `configured:false` |
+| `e10-cli form name-lang set <objId> <appId> [--zh <中文>] [--en <English>]` | 设置**表单名称**多语言（`--zh` / `--en` 至少一个）。先写多语言标签拿 targetId，再用 `name:{nameAlias,nameAliasLabelId}` 整体回写表单对象，两端回读校验。中文是默认语言；只给 `--en` 时保留当前名称作中文。首次设置会新建标签并挂回表单；与字段名多语言、自定义标题互不影响 |
+| `e10-cli form base-setting get <objId> <appId> [--part field\|data]` | 查看表单**功能设置**某一段（`formBaseSetting`，`--part` 缺省 `field`）：字段设置的浏览框数据获取最新标题；数据设置的启用附件鉴权、免登场景执行联动，以及该段其它已落库的键；`--json` 输出完整对象 |
+| `e10-cli form base-setting set <objId> <appId> [--part field\|data] [--browser-latest-title on\|off] [--linkage-mode system\|custom] [--file-permission on\|off] [--login-free-execute on\|off] [--detail-button-mode system\|custom] [--detail-batch-always-visible on\|off] [--detail-row-action-position float\|inline] [--data-log-mode system\|custom] [--record-form-log on\|off] [--insert-data-log on\|off]` | 修改表单功能设置：**字段设置**「浏览框数据获取最新标题」（`currentRelDetail`）；**数据设置·字段联动设置** 设置类型（`linkageFilePermissionType`）、启用附件鉴权（`linkageFilePermission`）、免登场景执行联动（`fdLinkageNoLoginExecute`）；**数据设置·明细表按钮设置** 设置类型（`subBtnType`）、批量操作按钮常显（`fixBatchOperate`）、行操作按钮位置（`rowActionPosition`：`float`=明细行上 / `inline`=明细行内）；**数据设置·数据日志设置** 设置类型（`insertDataLogType`）、记录表单日志（`needDataLog`）、新建数据记录日志（`insertDataLog`）。**每段的设置类型 `system`=读取系统设置、`custom`=自定义设置，段内单项只有自定义设置下才生效**；改单项时若该段不是自定义设置，命令会自动切成 `custom` 并标注，也可显式指定（显式设 `system` 时不能再改该段其它单项）。不给 `--part` 时按选项推断，两段混用会报错。只改点名项、整段回写并回读校验。详见 `references/form/guide-form-base-setting.md` |
 | `e10-cli form serial-mark set <objId> <appId> <fieldId> --segments @<json>` | **表单编号**（纯建模表）：用 JSON 数组组合任意编号规则，数组顺序即拼接顺序。段类型 `fixed`/`year`/`serial`/`field`/`system`/`date`；field 段可 inline `shortName` 代字映射。子命令组：`set`(配置,--segments) / `add-segment`(增量追加段) / `short-name`(代字 list/set) / `read`(查看) / `fields`(查可绑定字段) / `enable`(启用) / `disable`(停用，可加 `--field <fieldId>` 只停某一个字段的编号) / `clear`(解除绑定)。**`disable` 停用 ≠ `clear` 解除**：停用只关开关（`isUse=0`），绑定记录与组成段原样保留、可 `enable` 恢复；解除走删除接口，绑定不可逆。要「暂时不生成编号」一律用 `disable`。被编码字段平台自动只读。**⚠ 仅对未绑流程的纯建模表有效——eb表单绑流程后表单编号字段在流程提交时不生效，编号改走流程编号（`workflow numbering`，落到 REQUEST_NO 系统字段）** |
 | `e10-cli form field-options <objId> <appId> <fieldId> --options @<json> [--default <key>]` | 设选项/默认值。options.json: `[{"name":"选项名","valueKey":"可选"}]`；`--default` 用平台生成的长 valueKey（`form read --app-id` 获取），不是 name |
 | `e10-cli form option-template <list\|read\|create\|copy\|delete>` | **Select 选项预设模板管理**（下拉选项复用：多个表单共享一套选项，模板改了各表单跟着变）。`list [--system]` 列模板（默认自定义模板，--system 看系统内置）；`read <模板ID> [--flat]` 看选项树；`create <名称> --options @<json> [--level 1] [--describe 文本]` 建模板（options.json: `[{"name":"低","valueKey":"10","children":[]}]`，**valueKey 必须数字**，children 嵌套=多级）；`copy <模板ID>` 复制（系统 default 模板不可复制）；`delete <模板ID>` 删模板（被引用时平台拒绝）。**字段引用模板**：`form add-field --option-template <模板ID或名>` 或 fields.json 写 `"optionTemplate":"模板名"`（Select 专有，选项不内联） |
@@ -100,7 +108,7 @@
 | `e10-cli form relate <appId> <objId> <目标字段> --from <源字段>` | **HRM 值带出联动**：源字段为表内 Employee（人员）或 Department（部门）类型，换源自动填目标字段（换申请人→填邮箱/工号/部门；换所属部门→填部门编号/上级部门）。`--key` 从平台清单校验（默认 Employee=department、Department=name），`--title` 指定显示名（默认属性中文名）。详见 `form/guide-form-linkage.md` |
 | `e10-cli form delete-field <objId> <appId> <fieldId...>` | **删除字段**（可一次多个，批量）。**仍被布局引用的字段平台不允许删除**（报「当前字段已被布局引用，不允许删除」）；加 `--force` 时 CLI 先从布局移除再重试——会**连字段的标题组件一起摘**（一个字段在布局里是「字段本体 + 标题标签」两个组件），否则表单上会留下孤儿标签。字段**有数据**时同样删不掉 |
 | `e10-cli form delete <objId> <appId>` | 删除**整个表单**（不是字段；删字段用上面的 delete-field） |
-| `e10-cli form rename <objId> <appId> <新名称>` | 修改**表单名称**。⚠ 表单名称与**自定义标题**是分开的两套（标题用 `form title`），两者不一致属正常状态，不是漏改。平台该接口是整对象覆盖，命令内部**先读回完整对象、只换名称、再整体回写**，不会清掉其它配置；改完回读校验。改名称**不影响**标题 |
+| `e10-cli form rename <objId> <appId> <新名称>` | 修改**表单名称**。⚠ 表单名称与**自定义标题**是分开的两套（标题用 `form title`），两者不一致属正常状态，不是漏改。平台该接口是整对象覆盖，命令内部**先读回完整对象、只换名称、再整体回写**，不会清掉其它配置；改完回读校验。改名称**不影响**标题。**已配置名称多语言时只改默认语言文本，保留 `nameAliasLabelId`（英文等其它语言不动）** |
 | `e10-cli form title get <objId> <appId>` | 查看**表单自定义标题**：标题文本、表单页面名、是否隐藏页面头部 / 隐藏表单标题、页面名是否全含 |
 | `e10-cli form title set <objId> <appId> [--show-name <文本>] [--form-page-name <文本>] [--hide-header\|--no-hide-header] [--hide-title\|--no-hide-title] [--page-name-all-in 0\|1]` | 修改自定义标题（至少要给一项）。先读回现有标题、叠上改动再整份提交，改完逐项回读校验。⚠ **标题处于隐藏状态时，改了标题文本界面上也看不出变化**（`get` 会提示） |
 | `e10-cli form permission create <add\|update\|show> <objId> <appId> [--right-id <id>] --org-type <类型> [--org-id <id>] [--org-name <名>] [设置项]` | **创建权限**（谁能新建记录）。通用对象支持 all/employee/department/company/role/group/post/partTime/grade/external/externalAll；`all`/`externalAll` 的 orgId 自动 0。`update` 只改点名项并整行回写；`show` 查看布局/优先级/描述/条件/同步列表。设置项见下一行 |
@@ -612,6 +620,9 @@ e10-cli report py preagg --report-id <id> [--app-id <id>]
 | `e10-cli matrix enable <id>` / `disable <id>` | 启用 / 停用（停用后数据只读） |
 | `e10-cli matrix update <id>` / `delete <ids...>` | 更新基本信息（名称/描述/同步方式）/ 删除（级联删配置、数据、维护者） |
 | `e10-cli matrix data` | 矩阵数据维护（映射行）。`data save` 简写为 `[{rowId?, "<列configId>": ["<实体ID>"]}]`：**带 `rowId` 改那一行、不带为新增**（行 id 用 `data list` 拿；同步型矩阵的行 id 就是部门 id）。改行只给要改的列即可，CLI 自动补全其余列并回读比对 |
+| `e10-cli matrix person list [--keyword <kw>]` | 列出**人员矩阵**（组织架构里与条件矩阵并列的另一套矩阵，`/bs/hrm/matrix/*`）：id / 名称 / 启停 / 描述 |
+| `e10-cli matrix person fields <matrixId>` | 查看人员矩阵的字段（列）及字段类型、排序 |
+| `e10-cli matrix person data <matrixId>` | 查看人员矩阵的行数据（平台返回的当前页）；人员值按姓名展开。人员矩阵目前只提供只读查看，建改删暂未开放 |
 | `e10-cli matrix maintainer options\|list\|get\|add\|update\|delete` | 矩阵维护者配置：先查当前矩阵可用主体、维护类型、数据权限、条件码表和值列，再用 JSON 配置新增或完整更新；`delete <matrixId> <条目ID> [更多条目ID...]` 删除指定维护者。写入或删除后按条目回读核对。详见 `references/hrm/guide-matrix.md` |
 
 > 行从哪来（`syncType`）、字段能不能改（`permList` 里有没有 `FIELD`）、以及「条件列 → 人员列 → 数据映射 → 运行时读回」的完整步骤见 `references/hrm/guide-matrix.md`。

package/skill-docs/references/components/ref-component-common.md

@@ -1,98 +1,98 @@
-# 组件通用属性与样式
-
-> 适用 `@weapp/ui` 全部组件：属性与样式这部分是共通的，单看这一份即可。组件各自的专有属性见同目录下的组件文档。
-
-## 一、每个组件都有的属性（BaseProps）
-
-| 属性 | 类型 | 说明 |
-|---|---|---|
-| `className` | string | 挂到组件根节点，用来加自己的样式作用域 |
-| `style` | CSSProperties | 合并到组件根节点的行内样式 |
-| `customRender` | `(ctx, element) => ReactNode` | 包一层或整体替换组件的渲染结果 |
-| `overlayClassName` | string | 浮层样式名。**只有部分组件实现**（Radio / Checkbox / Menu / At / BreadCrumb 等），用前确认该组件是否支持 |
-| `prefixCls` | string | class 前缀。**不要用来改样式**：less 里的前缀是编译期写死的，改它只会换类名，样式表仍指向 `.ui-*` |
-| `weaComId` | string | 组件标识，一般不用 |
-| `children` | ReactNode | 子节点 |
-
-`customRender` 的第一个参数是组件实例，用来读取组件状态；返回的节点会**直接替代**原渲染结果，所以包裹时记得把 `element` 放回去：
-
-```jsx
-<Browser
-  module="hrm"
-  type="resource"
-  customRender={function (ctx, element) {
-    return <div className="my-browser-wrap">{element}</div>;
-  }}
-/>
-```
-
-## 二、表单类组件的通用属性（FormProps）
-
-表单类组件（Input / Select / Checkbox / Radio / Switch / Upload / Browser 等）在 BaseProps 之外还有：
-
-| 属性 | 类型 | 说明 |
-|---|---|---|
-| `readOnly` | boolean | 只读，只显示值、不加载输入工具 |
-| `disabled` | boolean | 禁用 |
-| `required` | boolean | 必填 |
-| `passport` | boolean | 加密显示为 `********` |
-| `placeholder` | string | 占位提示 |
-| `rule` | string \| function | 校验规则 |
-| `showRequiredMark` | boolean | 是否显示必填标记 |
-| `fieldId` / `fieldName` | string \| number | 隐藏域标识 |
-
-## 三、样式：四层钩子
-
-按可靠性从高到低，优先用上面的：
-
-| 层 | 手段 | 作用范围 |
-|---|---|---|
-| 变量层 | 在**页面根节点**重声明 CSS 变量（`--primary` 等） | 整个页面子树 |
-| 组件根层 | `className` / `style` | 组件根节点 |
-| 内容层 | `customRender` / 组件的 `bodyRender`、`customRenderItem` | 组件内部指定位置 |
-| 浮层专用 | `overlayClassName`、组件的弹层属性（如 `browserDialogProps`） | 该组件的弹层 |
-
-```jsx
-// 页面根节点声明变量，只影响这个页面
-<div className="my-page" style={{ '--primary': '#2f6fed', '--border-radius-md': '8px' }}>
-  ...
-</div>
-```
-
-**不要把变量写在 `:root` 上** —— 那会改掉整个平台的样式。
-
-## 四、浮层不在页面 DOM 里
-
-弹窗、下拉这类浮层通过 Portal 挂到 `body` 下的 `.ui-dialog-portal`：
-
-- 页面根节点上声明的 CSS 变量和后代选择器**都够不到浮层**；
-- 部分组件的弹层会继承组件上的 `className`（例如 Browser 把属性透传给内部 Dialog），所以同一个 className 有时会同时命中根节点和弹层；
-- 需要单独控制弹层时，用该组件的弹层属性或 `overlayClassName`，不要靠 DOM 层级猜；
-- 层级由变量控制：`--dialog-zindex`、`--popover-zindex`、`--modal-zindex`、`--toast-zindex`、`--picker-zindex` 等。
-
-## 五、常用 CSS 变量
-
-| 类别 | 变量 |
-|---|---|
-| 主色与状态色 | `--primary`、`--success`、`--warning`、`--danger`、`--info` |
-| 文字色 | `--main-fc`、`--regular-fc`、`--secondary-fc`、`--placeholder-fc`、`--link-fc` |
-| 背景 | `--bg-white`、`--bg-base`、`--bg-weak`、`--bg-gray` |
-| 边框与圆角 | `--border-color`、`--diviling-line-color`、`--border-solid`、`--border-radius-xs/sm/md/lg` |
-| 间距 | `--h-spacing-xs/sm/md/lg/xl`、`--v-spacing-xs/sm/md/lg/xl` |
-| 字号与行高 | `--font-size-sm/md/lg/base/heading`、`--line-height-base`、`--line-height-sm` |
-| 密度 | `--hd`（1px 换算单位，组件按它缩放） |
-
-## 六、不要做的事
-
-- 不用 `.ui-browser__xxx` 这类**内部 class** 覆盖样式，也不读 `weId`、不依赖 DOM 层级 —— 平台升级就会断；
-- 不改 `prefixCls` 指望换一套样式；
-- 不把 CSS 变量写到 `:root` 或 `body`；
-- 不编造组件或 props，列表见 `guide-page-code.md` 第六节。
-
-## 七、自检
-
-- [ ] 组件根节点上的样式走 `className` / `style`，没有去写内部 class
-- [ ] CSS 变量声明在页面根节点，没有写到 `:root`
-- [ ] 需要改弹层时用了组件的弹层属性，没有去猜 DOM 结构
-- [ ] `customRender` 包裹时把 `element` 渲染回去了
-- [ ] 没有依赖 `prefixCls` 改样式
+# 组件通用属性与样式
+
+> 适用 `@weapp/ui` 全部组件：属性与样式这部分是共通的，单看这一份即可。组件各自的专有属性见同目录下的组件文档。
+
+## 一、每个组件都有的属性（BaseProps）
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `className` | string | 挂到组件根节点，用来加自己的样式作用域 |
+| `style` | CSSProperties | 合并到组件根节点的行内样式 |
+| `customRender` | `(ctx, element) => ReactNode` | 包一层或整体替换组件的渲染结果 |
+| `overlayClassName` | string | 浮层样式名。**只有部分组件实现**（Radio / Checkbox / Menu / At / BreadCrumb 等），用前确认该组件是否支持 |
+| `prefixCls` | string | class 前缀。**不要用来改样式**：less 里的前缀是编译期写死的，改它只会换类名，样式表仍指向 `.ui-*` |
+| `weaComId` | string | 组件标识，一般不用 |
+| `children` | ReactNode | 子节点 |
+
+`customRender` 的第一个参数是组件实例，用来读取组件状态；返回的节点会**直接替代**原渲染结果，所以包裹时记得把 `element` 放回去：
+
+```jsx
+<Browser
+  module="hrm"
+  type="resource"
+  customRender={function (ctx, element) {
+    return <div className="my-browser-wrap">{element}</div>;
+  }}
+/>
+```
+
+## 二、表单类组件的通用属性（FormProps）
+
+表单类组件（Input / Select / Checkbox / Radio / Switch / Upload / Browser 等）在 BaseProps 之外还有：
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `readOnly` | boolean | 只读，只显示值、不加载输入工具 |
+| `disabled` | boolean | 禁用 |
+| `required` | boolean | 必填 |
+| `passport` | boolean | 加密显示为 `********` |
+| `placeholder` | string | 占位提示 |
+| `rule` | string \| function | 校验规则 |
+| `showRequiredMark` | boolean | 是否显示必填标记 |
+| `fieldId` / `fieldName` | string \| number | 隐藏域标识 |
+
+## 三、样式：四层钩子
+
+按可靠性从高到低，优先用上面的：
+
+| 层 | 手段 | 作用范围 |
+|---|---|---|
+| 变量层 | 在**页面根节点**重声明 CSS 变量（`--primary` 等） | 整个页面子树 |
+| 组件根层 | `className` / `style` | 组件根节点 |
+| 内容层 | `customRender` / 组件的 `bodyRender`、`customRenderItem` | 组件内部指定位置 |
+| 浮层专用 | `overlayClassName`、组件的弹层属性（如 `browserDialogProps`） | 该组件的弹层 |
+
+```jsx
+// 页面根节点声明变量，只影响这个页面
+<div className="my-page" style={{ '--primary': '#2f6fed', '--border-radius-md': '8px' }}>
+  ...
+</div>
+```
+
+**不要把变量写在 `:root` 上** —— 那会改掉整个平台的样式。
+
+## 四、浮层不在页面 DOM 里
+
+弹窗、下拉这类浮层通过 Portal 挂到 `body` 下的 `.ui-dialog-portal`：
+
+- 页面根节点上声明的 CSS 变量和后代选择器**都够不到浮层**；
+- 部分组件的弹层会继承组件上的 `className`（例如 Browser 把属性透传给内部 Dialog），所以同一个 className 有时会同时命中根节点和弹层；
+- 需要单独控制弹层时，用该组件的弹层属性或 `overlayClassName`，不要靠 DOM 层级猜；
+- 层级由变量控制：`--dialog-zindex`、`--popover-zindex`、`--modal-zindex`、`--toast-zindex`、`--picker-zindex` 等。
+
+## 五、常用 CSS 变量
+
+| 类别 | 变量 |
+|---|---|
+| 主色与状态色 | `--primary`、`--success`、`--warning`、`--danger`、`--info` |
+| 文字色 | `--main-fc`、`--regular-fc`、`--secondary-fc`、`--placeholder-fc`、`--link-fc` |
+| 背景 | `--bg-white`、`--bg-base`、`--bg-weak`、`--bg-gray` |
+| 边框与圆角 | `--border-color`、`--diviling-line-color`、`--border-solid`、`--border-radius-xs/sm/md/lg` |
+| 间距 | `--h-spacing-xs/sm/md/lg/xl`、`--v-spacing-xs/sm/md/lg/xl` |
+| 字号与行高 | `--font-size-sm/md/lg/base/heading`、`--line-height-base`、`--line-height-sm` |
+| 密度 | `--hd`（1px 换算单位，组件按它缩放） |
+
+## 六、不要做的事
+
+- 不用 `.ui-browser__xxx` 这类**内部 class** 覆盖样式，也不读 `weId`、不依赖 DOM 层级 —— 平台升级就会断；
+- 不改 `prefixCls` 指望换一套样式；
+- 不把 CSS 变量写到 `:root` 或 `body`；
+- 不编造组件或 props，列表见 `guide-page-code.md` 第六节。
+
+## 七、自检
+
+- [ ] 组件根节点上的样式走 `className` / `style`，没有去写内部 class
+- [ ] CSS 变量声明在页面根节点，没有写到 `:root`
+- [ ] 需要改弹层时用了组件的弹层属性，没有去猜 DOM 结构
+- [ ] `customRender` 包裹时把 `element` 渲染回去了
+- [ ] 没有依赖 `prefixCls` 改样式