4.2 KiB
4.2 KiB
05. Component System & Reuse Contracts
1. 核心原则
NEX 不要求所有项目安装或开发一套名为 NEX 的 React 组件库。项目已有组件体系应优先作为实现载体。NEX 提供的是组件治理、复用判断和行为契约。
2. 先盘点现有组件
修改前检查项目中:
- 基础 UI 组件;
- 表单组件和校验封装;
- 页面级复合组件;
- 布局/导航组件;
- 反馈与状态组件;
- 业务域共享组件;
- 设计系统/主题包(如有)。
对候选组件记录名称、路径、导出、使用次数、能力、已知限制和适用页面。不要仅根据名字判断是否等价,要核对 Props、状态和实际行为。
3. 组件复用决策
按此顺序判断:
- 项目已有组件能满足需求:直接复用。
- 已有组件只缺少通用能力:考虑向后兼容地扩展。
- 多处存在同一重复模式:抽象为项目级共享组件。
- 仅一个页面的特例:先保留局部实现,除非有明确复用价值。
- 第三方组件已足够满足需求:可以直接使用,不必机械封装。
不因 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 命名一致而重命名或重构成熟资产。