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

9.8 KiB
Raw Permalink Blame History

📌 落地状态以总览为准(2026-06-21):本文「未开始/未实现」等表述已过时——L1 主题(amis-theme.css §10-15 密度/按钮/弹窗)、L2 行选中、设计中心 DesignCenterPage 已上线。当前落地状态见 总览-2026-06-21 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 组件边界约束)。
  • 自定义组件(甘特/地图/组织架构图)每个单独立项,本期不铺开。