freedakgmail
71 lines
4.2 KiB
Markdown
71 lines
4.2 KiB
Markdown
# UI/UX 与公共组件规范
|
||
|
||
本规则用于指导 UI/UX 设计、公共组件抽取和组件登记管理。
|
||
|
||
## UI/UX 设计原则
|
||
|
||
- 禁止使用 emoji 作为 UI 图标。
|
||
- 首选专业图标库：Lucide Icons，其次 Feather Icons；Ant Design 项目可使用 Ant Design Icons。
|
||
- 禁止使用中文拼音缩写表达业务含义；优先使用英文、中文全称或清晰的领域命名。
|
||
- UI 实现应关注一致性、可访问性、响应式布局和错误状态。
|
||
- 页面设计应先确定信息架构，再确定视觉样式：导航、页面标题、主操作区、筛选区、内容区、分页区、反馈区。
|
||
- 表单必须明确必填、校验、错误提示、提交中、提交成功、提交失败和取消路径。
|
||
- 列表和表格必须明确加载、空数据、错误、筛选无结果、分页、排序和批量操作状态。
|
||
- 时间、金额、状态、权限、危险操作等高频模式必须统一呈现，不允许每个页面各自发挥。
|
||
|
||
## 公共组件抽取原则
|
||
|
||
- 同一交互或视觉模式在两个及以上页面出现，优先抽取公共组件。
|
||
- 即使只出现一次，但包含复杂状态、权限、时间段、分页、筛选、表格联动等逻辑，也应优先抽取为领域组件或组合组件。
|
||
- 公共组件 API 应表达业务语义，不暴露页面内部状态细节。
|
||
- 公共组件应保持稳定输入输出：`value`、`onChange`、`loading`、`disabled`、`error`、`empty`、`pagination` 等状态显式建模。
|
||
- 不把页面特有文案、接口请求、路由跳转硬塞进基础公共组件；这些应留在页面层或领域组合层。
|
||
|
||
## 优先沉淀的组件类型
|
||
|
||
- 页面布局：`PageLayout`、`PageHeader`、`ContentCard`、`ActionBar`。
|
||
- 查询筛选：`FilterBar`、`SearchInput`、`TimeRangePicker`、`DateRangePreset`。
|
||
- 数据展示：`DataTable`、`Pagination`、`EmptyState`、`LoadingState`、`ErrorState`。
|
||
- 表单交互：`FormField`、`FormSection`、`SubmitBar`、`ConfirmDialog`。
|
||
- 反馈与状态：`StatusBadge`、`PermissionGate`、`Toast`、`ResultPanel`。
|
||
- 业务高频组件：根据项目领域沉淀，不提前抽象不存在的业务概念。
|
||
|
||
## 页面实现顺序
|
||
|
||
- 先定义页面布局和数据流，再实现页面。
|
||
- 先抽取公共组件，再堆页面细节。
|
||
- 先覆盖加载、空态、错误、分页和权限状态，再补视觉细节。
|
||
- 当组件参数开始膨胀时，优先评估是否应拆成基础组件、领域组件和页面容器三层。
|
||
|
||
## UI 公共组件登记表
|
||
|
||
- 一旦项目出现可复用 UI 组件，必须创建或更新 `pmdocs/ui-components.md`。
|
||
- `pmdocs/ui-components.md` 用于记录组件沉淀情况，避免重复造分页、时间段、筛选栏、表格、表单等组件。
|
||
- 组件登记表至少包含：组件名、组件类型、适用场景、输入状态、输出事件、使用页面、维护状态。
|
||
- 推荐格式：
|
||
|
||
| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | 状态 |
|
||
|---|---|---|---|---|---|---|
|
||
| `Pagination` | 基础组件 | 列表/表格分页 | `page` / `pageSize` / `total` | `onChange` | 用户列表、订单列表 | 稳定 |
|
||
| `TimeRangePicker` | 组合组件 | 时间范围筛选 | `start` / `end` / `preset` | `onChange` | 数据看板、订单筛选 | 稳定 |
|
||
| `FilterBar` | 组合组件 | 列表筛选栏 | `filters` / `onFilterChange` | `onChange` / `onReset` | 用户列表、订单列表 | 稳定 |
|
||
| `DataTable` | 基础组件 | 数据表格 | `columns` / `data` / `loading` / `pagination` | `onPageChange` / `onSort` | 用户列表、订单列表 | 稳定 |
|
||
|
||
- 公共组件新增、重命名、废弃或职责变化时，必须同步更新组件登记表。
|
||
- 组件登记表只记录复用组件，不记录一次性页面局部元素。
|
||
|
||
## 组件参数膨胀应对策略
|
||
|
||
当组件参数超过 10 个，或出现以下情况时，应重新评估组件边界：
|
||
|
||
- 参数包含页面特定文案、路由、接口请求
|
||
- 参数包含复杂业务规则或权限判断
|
||
- 参数存在互斥或复杂依赖关系
|
||
- 不同使用场景需要不同参数子集
|
||
|
||
应对策略：
|
||
|
||
1. 拆成基础组件 + 领域组件 + 页面容器三层
|
||
2. 使用组合模式而不是配置模式
|
||
3. 使用 Render Props 或 Slots 传递复杂逻辑
|
||
4. 使用 Context 或状态管理隔离跨层状态 |