组件设计规范#

组件是前端工程的基本复用单元。设计良好的组件应当单一职责、接口清晰、易于测试。

单一职责#

• 一个组件只解决一类问题
• 不要把数据请求、复杂业务逻辑和展示混在一起
• 复杂页面由小组件组合而成

Props 与 Events#

• 父向子用 props 传递数据，子向父用事件
• props 尽量是基本类型或只读对象
• 事件命名使用 on + 动词，例如 onChange、onSubmit

interface Props {
  value: string;
  onChange: (next: string) => void;
  disabled?: boolean;
}

受控与非受控#

• 受控组件：值由父组件通过 props 管理
• 非受控组件：内部自己维护状态，通过 ref 暴露
• 优先设计为受控，必要时提供默认值支持非受控用法

可访问性#

• 给交互元素合理的 role 与 aria 属性
• 保证键盘可操作
• 颜色对比度满足 WCAG AA

文档与示例#

每个通用组件都应配套：

• 用途说明
• Props 表格
• 至少一个可用示例