frontend-component-build

前端组件构建

构建可用于生产环境的组件。采用与技术栈无关的原则。大多数模式都适用于 React、Vue、Svelte 或原生 Web 组件。

这项技能关注如何出色地实现一个组件。若需了解更广泛的系统设计，请参阅 design-system。若需了解日常视觉设计决策，请参阅 design-standards。

---

适用场景

• 从头开始构建新组件
• 重构现有组件
• 设计组件 API（props、slots、events）
• 为现有组件添加无障碍支持
• 根据设计实现组件

不适用场景

• 构建完整的设计系统（使用 design-system）
• 页面级设计决策（使用 design-standards）
• 后端或数据工作（使用 code-review-web）
• 仅针对性能进行优化（使用 performance-optimization）

---

所需输入

• 组件的用途（它满足什么 UI 需求）
• 设计方案（或愿意进行设计）
• 框架或技术背景
• 组件必须支持的状态
• 无障碍要求

---

框架：6 个维度

完整的组件需要涵盖六个维度。遗漏任何一个，组件都不完整。

1. 组成结构

编写任何标记之前，先确定组件由哪些部分组成。

常见组成结构：

• 按钮：容器 + 标签 +（可选）图标 +（可选）加载指示器
• 模态框：背景遮罩 + 容器 + 标题栏 + 主体 + 页脚 + 关闭控件
• 表单输入框：标签 + 输入框 +（可选）帮助文本 +（可选）错误消息
• 卡片：容器 +（可选）标题栏 + 主体 +（可选）页脚 +（可选）媒体内容

预先为各部分命名，可以让 API 一目了然。

2. 变体

组件支持哪些变化？

• 视觉变体（主要、次要、幽灵、危险）
• 尺寸变体（小、中、大）
• 功能变体（带图标、不带图标、仅图标）

变体应为一组受控选项，而不是任意扩展的集合。记录受支持的选项；没有实际用例时，拒绝新增变体的请求。

3. 状态

组件必须处理哪些状态？

• 默认
• 悬停（支持指针时）
• 焦点（始终需要——键盘导航离不开它）
• 激活／按下
• 禁用
• 加载中（适用时）
• 错误（适用于输入框、表单和受验证约束的组件）
• 空（适用于显示数据的组件）

每种状态都需要视觉表现和无障碍处理。

4. Props／API

设计组件的契约。

API 设计原则：

• 尽量减少必需的 props。 哪些是每次都真正需要的？这些才是必需项。其他内容都应有合理的默认值。
• 布尔型 props 是警示信号。 三个布尔值意味着七种组合。优先使用枚举字符串：使用 variant: "primary" | "secondary" | "ghost"，而不是 primary={true} ghost={false}。
• 优先使用 children，而不是 props。 内容就应作为内容传入。slots 可用时，不要另设 headerText 和 bodyText props。
• 组合优于配置。 一个通过 12 个 props 实现 5 种功能的组件，通常应拆成 5 个更小的组件。
• 为 props 指定类型。 使用 TypeScript、PropTypes 或 JSDoc。类型就是不会过时的文档。

5. 无障碍访问

从一开始就构建无障碍体验。事后再添加无障碍功能会困难 5 倍。

通用要求：

• 优先使用语义化 HTML 元素（<button>、<a>、<nav>、<form> 等），而非通用的 <div>
• 支持键盘导航（Tab、Shift+Tab，按钮支持 Enter/Space）
• 焦点清晰可见
• 点击目标最小尺寸为 44 × 44 像素
• 仅在语义化 HTML 不足时使用 ARIA

特定组件要求：

• 按钮： 使用 <button>。不要用 <div> 假装按钮。
• 模态框： 限制焦点范围，按 ESC 关闭，关闭后将焦点返回触发元素，并设置 role="dialog" 和 aria-labelledby。
• 表单输入框： 通过 for/id 或 aria-labelledby 关联标签。通过 aria-describedby 关联错误消息。处于错误状态时设置 aria-invalid。
• 切换控件： 两种状态使用带 aria-pressed 的 <button>，或开/关状态使用 role="switch"。
• 标签页： 使用 role="tablist" / role="tab" / role="tabpanel"，并设置 aria-selected，支持方向键导航。
• 工具提示和弹出框： 聚焦和悬停时均可触发。可通过 ESC 关闭。
• 加载状态： 使用 aria-live 播报，让屏幕阅读器知道内容发生了变化。

6. 测试

在宣布组件完成之前，验证其功能正常。

按优先级排列的测试类型：

1. 视觉回归。 在不同变体和状态下正确渲染。（使用 Storybook 和视觉差异工具，或手动截屏。）
2. 无障碍访问。 通过 axe 或同等自动化检查。
3. 键盘导航。 Tab、Enter、Escape 和方向键均按预期工作。
4. 组件逻辑。 属性产生预期输出。事件正确触发。（单元测试。）
5. 集成。 组件在预期的父级上下文中正常工作。

没有经过至少自动化无障碍测试的组件，就不算完成。

---

工作流

1. 了解使用场景。 这个组件满足什么 UI 需求？会出现在哪里？周边有哪些组件？
2. 勾勒结构。 为各个部分命名。
3. 列出变体和状态。 与设计系统保持一致，必要时定义新变体和状态。
4. 设计 API。 确定必需属性、可选属性、子元素和事件，并为其指定类型。
5. 使用语义化 HTML 编写标记。 选择合适的元素。避免将通用 <div> 用于交互功能。
6. 使用设计令牌设置样式。 不要硬编码颜色、间距或尺寸。
7. 添加交互。 管理焦点、处理键盘事件并添加 ARIA。
8. 添加状态。 悬停、聚焦、激活、禁用、加载、错误。
9. 测试。 自动化无障碍检查、键盘导航、视觉回归。
10. 编写文档。 用法、API、示例、反模式。

---

常见问题模式

• 使用 <div onClick> 构建。 这会失去键盘无障碍性、屏幕阅读器语义和焦点。请使用 <button> 或 <a>。
• 硬编码颜色和尺寸。 令牌的存在自有其原因。硬编码值会妨碍主题切换和一致性。
• 布尔属性泛滥。 <Button primary large rounded fullWidth disabled icon />。布尔属性太多，意味着你其实需要更少、设计更周全的变体。
• 忘记焦点状态。 悬停状态受到关注，焦点状态却常被忽略。键盘用户会看到不可见的按钮。
• 未考虑禁用状态。 禁用按钮的外观应明显表明其已禁用，还应设置 aria-disabled，并且不能响应点击。
• 随意编造 ARIA。 ARIA 角色和属性都有特定行为。编造 ARIA 比不使用 ARIA 更糟。优先使用语义化 HTML。
• 加载状态没有播报。 屏幕阅读器不知道加载动画已经出现。请使用 aria-live="polite" 或 role="status"。
• 仅通过工具提示提供关键信息。 仅悬停时显示的内容对键盘和触屏用户不可见。关键信息应放在可见的 UI 中。
• 组件没有文档。 未来的你、队友或下一位维护者，都无法使用他们无法理解的内容。

---

输出格式

完整的组件交付内容包括：

• 组件代码（使用适当的框架）
• **Storybook（或同等工具）**条目，展示所有变体和状态
• 文档：
  • 结构示意图或说明
  • Props/API 表格
  • 使用示例（基础、高级、边缘情况）
  • 适用场景与替代方案
  • 反模式（应避免的做法）
  • 无障碍说明
• 测试（视觉回归、无障碍和逻辑）

---

参考文件

• references/component-spec-template.md - 用于在构建前记录组件信息（props、状态、无障碍和边缘情况）的模板。
• references/component-api-patterns.md - 设计灵活组件 API 的常见模式（复合组件、受控与非受控、多态 as prop、render props、插槽）。
• references/accessibility-patterns.md - 常见交互组件的 ARIA 模式。