293 lines
7.5 KiB
Markdown
293 lines
7.5 KiB
Markdown
# EasyFlow 基础组件规范 v1
|
||
|
||
## 1. 文档目标
|
||
|
||
本规范用于统一 EasyFlow 常见组件与页面组合层的视觉气质、尺寸节奏、状态表达和布局原则。
|
||
|
||
适用范围：
|
||
|
||
- `easyflow-ui-admin`
|
||
- `easyflow-ui-usercenter`
|
||
- `easyflow-ui-websdk`
|
||
|
||
## 2. 组件总原则
|
||
|
||
EasyFlow 的组件应遵守以下统一气质：
|
||
|
||
- 柔和但理性
|
||
- 轻盈但稳定
|
||
- 精致但克制
|
||
- 现代但不花哨
|
||
|
||
统一要求：
|
||
|
||
- 同类组件尺寸档位一致
|
||
- 同类组件状态规则一致
|
||
- 同类组件交互反馈一致
|
||
- 同类组件在不同端只允许密度差异，不允许语言割裂
|
||
|
||
## 3. 按钮 Button
|
||
|
||
### 3.1 角色层级
|
||
|
||
- `Primary`：主操作，如新建、保存、发布、提交、确认
|
||
- `Secondary`：辅助操作，如取消、返回、次级入口
|
||
- `Ghost`：低干扰操作，如工具栏辅助动作
|
||
- `Text`：最弱层级操作，如查看详情、轻跳转
|
||
- `Danger`：删除、停用、清空等高风险动作
|
||
|
||
### 3.2 设计要求
|
||
|
||
- 主按钮明确，但不刺眼、不厚重、不夸张。
|
||
- 同一区域内按钮高度、圆角、左右内边距和图标尺寸统一。
|
||
- 图标按钮必须有足够点击热区，不可只按图标本体大小计算。
|
||
|
||
### 3.3 状态要求
|
||
|
||
- `hover`：轻微提亮或轻微背景变化
|
||
- `active`：轻微下压感或更深一档颜色
|
||
- `focus`：清晰焦点环
|
||
- `disabled`：降低对比度并禁用交互
|
||
- `loading`：保留按钮宽度，不发生跳变
|
||
|
||
### 3.4 禁止事项
|
||
|
||
- 一个区域同时出现多个同权重主按钮
|
||
- 用危险红色做普通主操作
|
||
- 用超大圆角和重阴影制造主操作感
|
||
|
||
## 4. 输入类组件 Input / Select / DatePicker / Search
|
||
|
||
### 4.1 统一要求
|
||
|
||
- 高度和按钮保持统一档位
|
||
- 占位文案、前后缀图标、清空按钮间距一致
|
||
- 默认边框克制，focus 时明确但不过亮
|
||
|
||
### 4.2 搜索框
|
||
|
||
- 搜索是效率辅助，不应默认比主按钮更抢眼。
|
||
- 搜索图标优先弱化，placeholder 保持清楚但不过深。
|
||
- 高级筛选展开后，信息层级仍需清晰，不形成工具栏拥堵。
|
||
|
||
### 4.3 校验与提示
|
||
|
||
- 错误提示应紧邻字段出现
|
||
- 描述文案优先解释“为什么错”和“怎么改”
|
||
- 成功态与错误态使用统一结构，不因页面定制
|
||
|
||
## 5. 标签 Tag / Badge / Status
|
||
|
||
### 5.1 使用原则
|
||
|
||
- 标签用于分类、状态、轻量属性展示，不承担主要信息块角色。
|
||
- 状态标签优先语义明确，而不是丰富多彩。
|
||
|
||
### 5.2 视觉要求
|
||
|
||
- 默认低饱和背景 + 清晰文字
|
||
- 相同状态在不同页面使用相同颜色和风格
|
||
- 控制一页中高彩状态标签的数量
|
||
|
||
## 6. 卡片 Card / Panel
|
||
|
||
### 6.1 使用原则
|
||
|
||
- 卡片和面板用于承载内容分组，不应形成“层层包裹”的视觉噪音。
|
||
- 一个页面尽量维持一种主容器语言。
|
||
|
||
### 6.2 结构建议
|
||
|
||
- 头部：标题 + 摘要 / 操作
|
||
- 内容：主体信息
|
||
- 底部：补充信息或收尾动作
|
||
|
||
### 6.3 视觉要求
|
||
|
||
- 主要通过内边距、标题层级、弱分隔建立结构
|
||
- 弱边框或极轻阴影即可，不做厚重悬浮卡片
|
||
|
||
## 7. 弹窗 Modal / 抽屉 Drawer / 浮层 Popover
|
||
|
||
### 7.1 总原则
|
||
|
||
- 浮层是为了帮助完成任务，不是为了制造空间戏剧性。
|
||
- 同类浮层的头部、说明区、底部操作区和关闭行为保持一致。
|
||
|
||
### 7.2 弹窗
|
||
|
||
- 适合短流程确认、中小表单、明确单任务场景
|
||
- 标题清楚，说明短而直接
|
||
- 底部按钮顺序稳定，避免不同页面顺序漂移
|
||
|
||
### 7.3 抽屉
|
||
|
||
- 适合中等复杂度编辑、详情查看、分步信息处理
|
||
- 内容区滚动、头部固定、底部操作区布局应保持稳定
|
||
|
||
### 7.4 Popover / Dropdown
|
||
|
||
- 只承载轻量选择、操作列表和局部补充信息
|
||
- 避免承载过长表单或复杂业务流程
|
||
|
||
## 8. 表格 Table
|
||
|
||
### 8.1 总体原则
|
||
|
||
- 表格优先服务检索、比较和快速操作
|
||
- 密度应克制统一，不要有的列很松，有的区域很挤
|
||
|
||
### 8.2 设计要求
|
||
|
||
- 表头、行高、单元格内边距、状态标签、行内操作维持统一节奏
|
||
- 行 hover 应轻，不造成过强闪烁
|
||
- 行内操作不应在未 hover 时完全不可发现
|
||
|
||
### 8.3 长列表策略
|
||
|
||
- 默认考虑分页、筛选、排序
|
||
- 数据量大时优先评估虚拟滚动或懒加载
|
||
- 表格工具栏与筛选区视作统一效率区域，不割裂设计
|
||
|
||
## 9. 工具栏 Toolbar / 筛选区 Filter Bar
|
||
|
||
### 9.1 总原则
|
||
|
||
- 工具栏服务任务效率，不应变成页面视觉中心。
|
||
- 搜索、筛选、批量操作、导入导出、主操作要形成明确优先级。
|
||
|
||
### 9.2 推荐布局
|
||
|
||
- 左侧：页面标题补充信息或筛选条件
|
||
- 右侧：主操作、次级操作
|
||
- 搜索与筛选默认退后于主操作
|
||
|
||
### 9.3 设计要求
|
||
|
||
- 避免同时叠加过多输入框、下拉、标签和按钮
|
||
- 高级筛选建议折叠或分层展示
|
||
|
||
## 10. Tabs / Breadcrumb / 导航类组件
|
||
|
||
### 10.1 Tabs
|
||
|
||
- 用于同级内容切换，不用于承载复杂操作入口
|
||
- 当前态应清晰，但不依赖厚重背景或夸张动画
|
||
- 标签过多时优先滚动或收纳，不压缩到难读
|
||
|
||
### 10.2 Breadcrumb
|
||
|
||
- 只表达路径，不承载大量操作
|
||
- 当前页层级清晰，前层级适度弱化
|
||
|
||
### 10.3 导航
|
||
|
||
- 导航风格轻量，重点是帮助定位，不抢占内容区注意力
|
||
- 选中态与 hover 态要统一，避免不同模块风格分裂
|
||
|
||
## 11. 表单 Form
|
||
|
||
### 11.1 结构原则
|
||
|
||
- 标签、字段、说明、错误、帮助信息保持稳定顺序
|
||
- 长表单按逻辑分组，避免一屏超长无层次
|
||
|
||
### 11.2 交互要求
|
||
|
||
- 提交时必须有 loading、防重复提交和错误回填
|
||
- 必填项策略统一，不做页面级个性化表达
|
||
- 表单保存失败必须说明原因和可恢复路径
|
||
|
||
## 12. 空状态 / 错误状态 / 无权限状态
|
||
|
||
### 12.1 空状态
|
||
|
||
必须同时包含：
|
||
|
||
- 当前为空的原因
|
||
- 一句简洁说明
|
||
- 明确的下一步动作
|
||
|
||
### 12.2 错误状态
|
||
|
||
必须同时包含：
|
||
|
||
- 错误说明
|
||
- 重试或返回路径
|
||
- 必要时的诊断信息入口
|
||
|
||
### 12.3 无权限状态
|
||
|
||
- 明确告诉用户为什么不可访问
|
||
- 指向申请权限、联系管理员或返回路径
|
||
|
||
## 13. AI 相关组件
|
||
|
||
### 13.1 对话与消息区
|
||
|
||
- AI 输出区域应强调可读性与节奏，不做过度聊天气泡装饰
|
||
- 系统消息、用户消息、工具状态、执行结果要有清晰区分
|
||
|
||
### 13.2 工作流 / Agent 状态块
|
||
|
||
- 优先表达当前步骤、执行状态、结果摘要、错误恢复
|
||
- 用结构和状态说明表达过程，不靠大面积特效制造“智能感”
|
||
|
||
### 13.3 知识 / 检索 / 引用信息
|
||
|
||
- 应有稳定的辅助信息样式
|
||
- 引用、命中来源、分块信息不应与主回答混成一层
|
||
|
||
## 14. 页面组合层建议
|
||
|
||
### 14.1 列表页
|
||
|
||
推荐结构：
|
||
|
||
1. 页面标题
|
||
2. 说明或摘要
|
||
3. 工具栏
|
||
4. 表格 / 卡片列表
|
||
5. 分页 / 列表底部说明
|
||
|
||
### 14.2 详情页
|
||
|
||
推荐结构：
|
||
|
||
1. 标题与主操作
|
||
2. 摘要信息
|
||
3. 主内容区
|
||
4. 次级面板区
|
||
|
||
### 14.3 配置页
|
||
|
||
- 优先按模块分组，而不是长表单堆叠
|
||
- 危险配置、基础配置、实验性配置层级明确分开
|
||
|
||
## 15. 三端差异建议
|
||
|
||
### 15.1 Admin
|
||
|
||
- 更紧凑
|
||
- 更强调检索、管理、批量操作和信息秩序
|
||
|
||
### 15.2 User Center
|
||
|
||
- 更轻松
|
||
- 更强调个人任务、引导和可读性
|
||
|
||
### 15.3 Web SDK
|
||
|
||
- 更轻、更简、更对话化
|
||
- 但按钮、输入、面板、标签与状态反馈必须保持同源
|
||
|
||
## 16. 交付检查重点
|
||
|
||
做组件或页面时，至少确认：
|
||
|
||
- 是否符合 `冷静智能` 主题
|
||
- 是否复用了统一 Token 与公共组件
|
||
- 是否保持组件族一致
|
||
- 是否补齐了状态与异步反馈
|
||
- 是否在不同尺寸下仍然清晰、顺手、不拥挤
|