building-components

创建组件

工作流

复制此清单并跟踪进度：

Component Progress:
- [ ] Step 1: Determine placement
- [ ] Step 2: Create folder structure
- [ ] Step 3: Create component file
- [ ] Step 4: Add sub-components (if needed)
- [ ] Step 5: Validate against checklist
- [ ] Step 6: Run lint fix and re-check

步骤 1：确定放置位置

尽可能根据上下文判断，否则询问用户。
有关各类型的路径和约定，请参阅 references/placement.md：

• 共享（通用）组件
• 特定页面的组件
• 现有组件的子组件
• 页面组件

如果任务要添加或提取自定义 Hook，请在创建文件前确定其归属：

• 仅将 src/hooks/ 用于共享 Hook，或有意设计为在多个组件、页面或领域中复用的 Hook
• 如果 Hook 仅用于所属组件的内部行为，请将其与该组件放在一起
• 不要将仅供单个组件内部使用的 Hook 放在 src/hooks/ 中

步骤 2：创建文件夹结构

在适当的位置创建一个 kebab-case 文件夹。
各类场景的示意图请参阅 references/folder-structures.md。

步骤 3：创建组件文件

在文件夹内创建一个 PascalCase .tsx 文件。
遵循 references/REFERENCE.md 中的约定。

步骤 4：添加子组件（如有需要）

如果组件需要子组件，请在其中创建一个 components/ 文件夹。 每个子组件都遵循相同规则。有关子组件模式，请参阅 references/placement.md。

步骤 5：根据清单进行验证

在确认组件完成前，逐项检查以下验证清单。

步骤 6：运行 lint 修复并重新检查

仅对创建或修改的文件运行带自动修复的 linter。如果自动修复后仍有错误，请告知用户需要手动修复并停止操作——不要使用 eslint-disable、@ts-ignore、@ts-expect-error 或任何其他抑制指令来掩盖错误。

---

验证清单

创建组件后，逐项确认：

命名

• 文件夹名称为 kebab-case（例如，card-content）
• 文件名为 PascalCase，且与导出的组件名称一致（例如，CardContent.tsx 导出 CardContent）
• 文件位于自己的文件夹内（而不是直接放在父目录中）

导出

• 使用命名导出：export const ComponentName: React.FC<Props>
• 不使用默认导出
• 每个文件仅包含一个组件

Props

• Props 定义为 type Props（而非 interface）
• Props 按以下顺序排列：必需项 → 可选项 → 函数回调
• 使用 React.FC<Props>（如果没有 Props，则使用 React.FC）

结构

• 组件放在正确的目录中（通用目录或特定页面目录）
• 子组件放在 components/ 子文件夹中，而不是与父组件并列
• 如果添加了自定义 Hook，其放置位置应符合其作用范围：共享 Hook 放在 src/hooks/，组件专用 Hook 放在所属组件旁边
• 函数体仅包含 JSX 时使用隐式返回
• 条件 JSX 渲染使用 {condition ? <Element /> : null}，绝不使用 condition && <Element />

文件

• 仅在需要时创建可选辅助文件（types.ts、constants.ts、helpers.ts、index.ts）
• 除非确实是共享 Hook，否则不要将新的自定义 Hook 添加到 src/hooks/

Lint

• 已对更改的组件文件运行 lint
• 已运行 lint 自动修复
• 已修改的文件中没有新增 lint 错误