Files
eip4-platform/docs/组件设计体系-design-2026-06-15.md
zhengwr 624ffe8a15 docs: 06-21 进度文档对齐 + P0/P1 实施记录
- 新建 项目进度与路线-总览-2026-06-21(取代06-17版),刷新A/B矩阵+增量交付+下一步+§9实施记录
- README 索引刷新到06-21;旧总览+14份过时/已完成文档加状态横幅;落地路线图回写里程碑

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 13:56:14 +08:00

104 lines
9.8 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
> 📌 **落地状态以总览为准(2026-06-21)**:本文「未开始/未实现」等表述已过时——L1 主题(amis-theme.css §10-15 密度/按钮/弹窗)、L2 行选中、设计中心 DesignCenterPage 已上线。当前落地状态见 [总览-2026-06-21](项目进度与路线-总览-2026-06-21.md) B4。
# EIP4 组件设计体系 — 设计文档
> 日期:2026-06-15 状态:设计已成形(brainstorm 共识),具体数值/形态待真实数据校准
> 范围:跨 `eip4-web`(前端壳 + 主题 + 运行时渲染器)与 `eip4-platform/platform-converter`(schema 产出)
> 缘起:从"editGrid 添加按钮位置"升级为"全站 UI/UE 达不到生产级 → 立一套合理好用的组件体系"
---
## 1. 背景与目标
- 现状:1238+ 业务页由元数据驱动、转换器产出 amis schema 渲染。功能正确,但跑的是 **amis 默认皮肤 + 仅做了功能正确、未做视觉/交互打磨**,整体观感"达不到生产级"。
- 已有资产:`claude-design-设计输入包/` 已把 1500+ 页归纳为 **11 种页面模式**,给出目标审美(**飞书多维表格 / 钉钉宜搭的密度感**)、效率优先原则、**design tokens 主题化**要求、amis 组件边界约束。**规格不缺,缺的是落成生产级实现。**
- 目标:建立一套**组件设计体系**,让自动转换出来的页面达到生产级;优先把"渲染出来的 App 质量"拉起来。
## 2. 设计原则(顶层,约束所有后续决策)
1. **分组件定夺**:多数组件**保真换肤**(只现代化视觉、交互流程不变、用户 0 学习成本);只对明确"不好用"的(树编辑、列表选中)才**现代化重做交互**。
2. **双约束:老兼容 + 新 UX(核心)**:框架**同时具备两套行为**,不是二选一。
- 默认 = 保真:老系统怎么操作,新系统就怎么操作 → 老页面零风险。
- 现代化 = 按页可覆盖:哪页升级、升成什么样,**拿那一页的真实数据/字段量看了再定**,逐页覆盖。
- 开关落在转换器配置层(每模板可标注),天然支持"交付不同客户换不同档位"。
3. **效率优先于装饰**:密度、键盘操作、批量操作 > 留白与动效(参考飞书/宜搭密度)。
4. **Token 主题化**:全部视觉决策用 design tokens 组织,换色不换骨架。
5. **数据驱动校准**:具体宿主形态、密度数值、交互细节**不在设计阶段写死**,对着真实重型页校准。
## 3. 路线决策:A — Token/主题先行,逐级升级
四层"代价阶梯",**绝大多数组件停在 L1 即可**;越往下代价越大、用得越少:
| 层 | 机制 | 改什么 | 代价/风险 | 覆盖 |
|---|---|---|---|---|
| **L1 Token/主题** | 扩 `eip4-web/src/shell/theme.css` + `amis-theme.css`(CSS 变量/覆盖) | 全局密度、间距、字号、圆角、颜色、组件态(hover/选中/禁用)、表格/表单/弹窗视觉规范 | **零 SDK 重建、零回归、随时回退** | 约 80% 的"很差",全 11 模式观感 |
| **L2 Schema 约定** | 改转换器 `UiTypeMapper` / `TemplateToAmisConverter` 产出 | 用 amis 已有能力把组件配"对"(列表选中模式、picker 列、子表工具栏、审批时间线结构、**表单宿主策略**) | 改 Java + 重转重导,低风险 | 能用 schema 表达的交互 |
| **L3 运行时渲染器** | 宿主 `amisRequire('amis')` 注册自定义 React 渲染器(`AmisRenderer.tsx` 已有注册通道) | amis schema 表达不出来的交互(如树的现代化行内编辑) | 在 app 代码内,**不动 bundle** | 少数硬交互 |
| **L4 fork SDK** | 改 amis 源码 + 重建 `public/sdk-local/sdk.js` | amis 内核级限制(如 editGrid 按钮进表头工具栏 ⊞ 同排) | **最重**:踩源码漂移坑、需全站回归 | 最后一档手术刀,单点动用 |
**现状基础(非从零)**:`theme.css`(壳层 tokens:主色 `#2B5CE6`、`--text`/`--line`/`--surface-2`…)+ `amis-theme.css`(316 行,把壳层 token 映射到 amis cxd 变量,含深色模式,经 `main.tsx` 在 `sdk.css` 后加载)。但现有 316 行**主要只对齐了品牌色**,未做密度/间距/字号/组件态/交互体系化打磨 → 这是 L1 主战场。
> ⚠️ **L4 源码漂移坑(已核实)**:线上 `public/sdk-local/sdk.js` 的 InputTable 与 `amis-fork` 源码已不一致(线上缺 `tableContentClassName`/`showFooterAddBtn` 等标记,是更旧/不同实现)。从 amis-fork 重建会换成另一个 amis 版本 → 全站 883 页回归风险。**故 L4 一律单独立项、单点动用,绝不为换肤动它。**
## 4. 11 模式 × 组件处置表(含 5 个痛点归位)
| 痛点 / 模式 | 对应模式 | 现状问题 | 处置层 | 定性 |
|---|---|---|---|---|
| **①树的编辑** | M3 树 / M9 树选择窗 | 加节点走弹窗表单、无拖拽、无属性抽屉 | **L2+L3** | **现代化重做**:行内增改名 + 拖拽排序 + 选中节点右侧属性 Drawer |
| **②列表选中** | M1 列表(60%) | 勾选/行高亮弱、单选双击与批量勾选语义混 | **L1+L2** | **现代化**:双击=查看、勾选+工具栏=批量、选中行强高亮、固定操作列 |
| **③各种选择框** | M8 选择窗 / M9 树选择窗 + picker | 弹窗朴素、无"已选区"、单/多选不清 | **L1+L2** | **保真换肤+配置**:搜索框+简化列表+已选计数+确定/取消,统一所有"放大镜"字段 |
| **④审批页面** | M11 审批 + 待办中心 | 无时间线、无当前节点操作区、待办中心未独立 | **L1+L2(+特建)** | **现代化**:表单+审批时间线+同意/驳回/转办;待办中心独立页(批量同意、移动端卡片) |
| **⑤其余归纳** | M2 主子表 / M4 树+列表 / M5 日历 / M6 组合 / M7 表单 / M10 报表 | 默认皮肤、密度松、缺合计行/分组小计规范 | **L1 为主** | **保真换肤**:统一密度/间距/字号/状态色/表格规范 |
> 11 模式定义见 `claude-design-设计输入包/03-页面模式规格-11种模板.md`;组件边界见 `02-设计约束-amis组件边界.md`。
## 5. 表单宿主策略(CRUD 新增/编辑 — 内容多时不挤)
**问题**:M2 主子表/M7 表单在 ERP 高字段密度下,全塞进居中 Dialog 必然憋屈。
**根因修复(L1,任何宿主都先做)**:分组折叠(基本信息/明细/附件,可折叠,而非一堵字段墙)+ 统一栅格间距(tokens,2/3 列响应式)+ 吸顶标题 + 吸底操作条(保存/提交常驻、body 内滚动)+ 主子表子表各自带工具栏。
**宿主策略(L2,可配置、数据驱动、不现在写死)**:
- 候选宿主:amis `dialog` / `drawer` / `page`(整页路由) / `wizard`(分步) 均可用,无需 fork。
- **默认 = 保真**(老系统怎么弹就怎么弹);**升级 = 按页覆盖**,阈值/覆盖名单是参数。
- 候选分级规则(**待真实数据校准,非定论**):轻量(≤~12 字段)→Dialog;中等→右侧宽 Drawer;重型(主子表/多 Tab/ERP 密集)→整页路由(左锚点导航+吸底操作条)。
- 转换器已知每模板字段数 + 是否主子表,可据此自动判定宿主,并允许逐页覆盖。
## 6. 设计工具 IA(Thread B,本期 A 之后再做)
- 现状:`PageRenderPage.tsx` 给**每个页面**(管理员可见)挂一颗「设计」按钮,打开 F4-L1 低代码设计器(`amis-editor` 三屏,`DesignerPage.tsx`)。
- 用户主张:**应有一个独立的"设计中心"模块集中管理/设计所有功能页**,而不是每页一颗散落的设计按钮。
- 处置:**记录为 Thread B**,主线 A(组件体系)落到生产级后再做。届时方向 = 收敛为集中式设计中心(页面列表 + 进入设计 + 版本/overlay 管理),逐步弱化/移除每页设计按钮。
## 7. 待真实数据校准清单(Open Decisions — 不在本文档写死)
1. 表单宿主分级阈值(字段数边界)+ 哪些模板进"现代化覆盖名单"——拿合同管理(主子表)、设备台账(列表)、某审批单等真实页校准。
2. L1 密度数值(行高、字号阶、间距阶、表格紧凑度)——对照飞书/宜搭与老系统截图定标。
3. 树编辑现代化版的具体交互(行内 vs Drawer 属性面板的边界)。
4. 列表选中的单选/多选/双击语义在各业务页是否统一。
5. editGrid 按钮入表头(⊞ 同排)是否值得动 L4 —— 默认**保留现左对齐工具栏兜底**,仅当成硬需求时单独立项。
## 8. 分期建议(先后顺序,数值待校准)
1. **P0**:L1 design tokens + amis 主题体系化(密度/间距/字号/组件态),先在 **M1 列表**(60%)定下密度基调 → 立刻全站观感提升。
2. **P1**:M1 列表选中现代化 + M8/M9 选择框统一(换肤+配置)。
3. **P2**:M2 主子表表单宿主策略 + 根因修复(分组折叠/吸底条)。
4. **P3**:M3/M9 树编辑现代化(L2→L3)。
5. **P4**:M11 审批 + 待办中心。
6. **P5**:M7 表单(移动端样张)、M10 报表、其余模式收尾。
7. **后续**:Thread B 设计中心;按需 L4 单点项(editGrid 表头按钮等)。
## 9. 验收口径("生产级"怎么算)
- 对照老系统截图:功能 parity 不丢(默认保真档)。
- 对照飞书多维表格/钉钉宜搭:密度、状态反馈、键盘/批量效率达现代水平。
- 双端:同一 schema 桌面 + 移动响应式降级(crud→卡片、多列→单列)成立。
- 每个模式有一张"对照样张"(老 vs 新)+ 真实数据走查通过。
## 10. 非目标(YAGNI)
- 不重写 amis(不走自定义组件库先行 B 路线)。
- 不为换肤重建 SDK(L4 仅单点)。
- 不在本期做自由画布式表单、无限嵌套子表、单元格内迷你图表(违反 amis 组件边界约束)。
- 自定义组件(甘特/地图/组织架构图)每个单独立项,本期不铺开。