97 lines
4.2 KiB
Markdown
97 lines
4.2 KiB
Markdown
# 05. Component System & Reuse Contracts
|
||
|
||
## 1. 核心原则
|
||
|
||
NEX 不要求所有项目安装或开发一套名为 NEX 的 React 组件库。项目已有组件体系应优先作为实现载体。NEX 提供的是组件治理、复用判断和行为契约。
|
||
|
||
## 2. 先盘点现有组件
|
||
|
||
修改前检查项目中:
|
||
|
||
- 基础 UI 组件;
|
||
- 表单组件和校验封装;
|
||
- 页面级复合组件;
|
||
- 布局/导航组件;
|
||
- 反馈与状态组件;
|
||
- 业务域共享组件;
|
||
- 设计系统/主题包(如有)。
|
||
|
||
对候选组件记录名称、路径、导出、使用次数、能力、已知限制和适用页面。不要仅根据名字判断是否等价,要核对 Props、状态和实际行为。
|
||
|
||
## 3. 组件复用决策
|
||
|
||
按此顺序判断:
|
||
|
||
1. 项目已有组件能满足需求:直接复用。
|
||
2. 已有组件只缺少通用能力:考虑向后兼容地扩展。
|
||
3. 多处存在同一重复模式:抽象为项目级共享组件。
|
||
4. 仅一个页面的特例:先保留局部实现,除非有明确复用价值。
|
||
5. 第三方组件已足够满足需求:可以直接使用,不必机械封装。
|
||
|
||
不因 NEX 采用某个概念名称就新增 `Nex*` 组件。如果已有组件叫 `PageHead`、`Ctlbar`、`DataTable` 等,且契约满足要求,就继续使用现有命名。
|
||
|
||
## 4. 组件分层(概念模型)
|
||
|
||
| 层级 | 职责 | 示例 |
|
||
|---|---|---|
|
||
| Foundation | Token、主题、图标和基础样式 | 颜色语义、字体尺度、焦点样式 |
|
||
| Primitive | 基础交互控件 | Button、Input、Select、Tooltip |
|
||
| Composite | 高频复合组件 | 页面头部、搜索栏、表格工具栏、指标卡 |
|
||
| Pattern | 页面/任务模式 | 列表管理、编辑流程、专业工作区 |
|
||
|
||
项目可采用不同目录结构或命名方式。
|
||
|
||
## 5. 常见能力合同
|
||
|
||
以下是能力要求,不是要求必须创建这些组件:
|
||
|
||
### Page Heading
|
||
- 标题、说明、面包屑和主操作层级明确。
|
||
- 小屏下标题和操作不会互相挤压。
|
||
- 强调型 Hero 只在项目设计规范允许的场景使用。
|
||
|
||
### Search / Filter Toolbar
|
||
- 搜索、筛选、重置和应用行为可预测。
|
||
- 已应用筛选条件可见。
|
||
- Enter 搜索、自动搜索或显式提交按项目规范统一。
|
||
- 批量操作仅在存在选中项时展示或启用。
|
||
|
||
### Data Table / List
|
||
- 加载、空数据、错误、无权限和分页状态清晰。
|
||
- 行点击与行内操作不互相吞事件。
|
||
- 选择、排序、筛选和分页行为一致。
|
||
- 长内容、窄屏和键盘导航有可用策略。
|
||
|
||
### Form
|
||
- 必填、校验、错误、提交中和保存结果清晰。
|
||
- 字段标签、帮助文案和错误信息可关联。
|
||
- 取消/关闭时对未保存内容的行为明确。
|
||
|
||
### Modal / Drawer / Overlay
|
||
- 容器选择符合任务复杂度和上下文需要。
|
||
- 焦点进入、焦点返回、Esc 行为和遮罩交互合理。
|
||
- 层级由项目层级体系/组件库管理。
|
||
|
||
### Feedback / Status
|
||
- 状态同时具备文本或图标语义,不只靠颜色。
|
||
- 长标签截断时必须提供可访问的完整文本;Tooltip 只是一个呈现渠道,不得成为键盘或触屏用户获取关键内容的唯一方式。
|
||
- 装饰性图标不得混入控件的可访问名称;图标与可见文本并列时应避免重复朗读。
|
||
- 图标按钮必须有简洁、描述动作的可访问名称;不得把图标库内部名称、字体字形名或 glyph token(例如 `upload`、`down`)拼进用户可读名称。
|
||
- 当文本本身已提供名称时,伴随图标通常应从辅助技术名称计算中隐藏;当图标承载唯一含义时,应为控件提供明确的业务名称。
|
||
- 通知、行内提示和页面级错误的使用场景不混淆。
|
||
|
||
## 6. 组件变更验收
|
||
|
||
修改共享组件时,至少检查:
|
||
- 所有已知调用方;
|
||
- 默认值和变体兼容性;
|
||
- Light/Dark(若项目支持);
|
||
- 桌面和窄屏行为;
|
||
- 键盘与可访问性;
|
||
- 空、加载、错误和禁用状态;
|
||
- 视觉回归范围。
|
||
|
||
## 7. 参考命名说明
|
||
|
||
`NexPageHeader`、`NexSearchToolbar`、`NexDataTable`、`NexStatCard` 等名称只用于表达一类能力,不构成命名要求。若项目已有等价组件,应建立映射并复用,不要为追求 NEX 命名一致而重命名或重构成熟资产。
|