building-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating Components

创建组件

Workflow

工作流程

Copy this checklist and track progress:

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 1: Determine placement

Infer from context if possible, otherwise ask the user. See references/placement.md for paths and conventions for each type:

Shared (common) component
Page-specific component
Sub-component of existing component
Page component

Step 2: Create folder structure

Create a kebab-case folder in the appropriate location. See references/folder-structures.md for diagrams of each scenario.

Step 3: Create component file

Create a PascalCase

.tsx

file inside the folder. Follow the conventions in references/REFERENCE.md.

Step 4: Add sub-components (if needed)

If the component needs sub-components, create a

components/

folder inside it. Each sub-component follows the same rules. See references/placement.md for the sub-component pattern.

Step 5: Validate against checklist

Run through the validation checklist below before considering the component complete.

复制以下检查清单并跟踪进度：

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

步骤1：确定组件放置位置

如果可以从上下文推断则直接确定，否则询问用户。请查看references/placement.md了解每种组件类型的路径和规范：

共享（通用）组件
页面专属组件
现有组件的子组件
页面组件

步骤2：创建文件夹结构

在合适的位置创建一个短横线命名（kebab-case）的文件夹。请查看references/folder-structures.md获取每种场景的结构示意图。

步骤3：创建组件文件

在文件夹内创建一个大驼峰命名（PascalCase）的

.tsx

文件。遵循references/REFERENCE.md中的规范。

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

如果该组件需要子组件，请在其文件夹内创建一个

components/

子文件夹。每个子组件遵循相同的规则。请查看references/placement.md了解子组件模式。

步骤5：对照检查清单验证

在完成组件创建前，按照以下验证检查清单逐一核对。

Validation checklist

验证检查清单

After creating a component, verify every item:

创建组件后，验证以下所有项：

Naming

命名规范

Folder name is kebab-case (e.g.,
```
card-content
```
)
File name is PascalCase and matches the exported component (e.g.,
```
CardContent.tsx
```
exports
```
CardContent
```
)
File is inside its own folder (not loose in a parent directory)

文件夹名称为短横线命名（kebab-case）（例如：
```
card-content
```
）
文件名称为大驼峰命名（PascalCase）且与导出的组件名称一致（例如：
```
CardContent.tsx
```
导出
```
CardContent
```
）
文件位于专属文件夹内（而非直接放在父目录中）

Exports

导出规范

Uses named export:

export const ComponentName: React.FC<Props>

No default exports
One component per file

使用命名导出：

export const ComponentName: React.FC<Props>

不使用默认导出
每个文件对应一个组件

Props

Props规范

Props defined as
```
type Props
```
(not
```
interface
```
)
Props ordered: required → optional → function callbacks
```
React.FC<Props>
```
used (or
```
React.FC
```
if no props)

Props使用
```
type Props
```
定义（而非
```
interface
```
）
Props顺序：必填项 → 可选项 → 函数回调
使用
```
React.FC<Props>
```
（若无Props则使用
```
React.FC
```
）

Structure

结构规范

Component placed in the correct directory (common vs page-specific)
Sub-components live in a
```
components/
```
subfolder, not alongside the parent
Implicit return used when the body is JSX-only

组件放置在正确的目录中（通用组件 vs 页面专属组件）
子组件位于
```
components/
```
子文件夹中，而非与父组件同级
当组件主体仅为JSX时使用隐式返回

Files

文件规范

Optional helper files (
```
types.ts
```
,
```
constants.ts
```
,
```
helpers.ts
```
,
```
index.ts
```
) created only if needed

仅在需要时创建可选的辅助文件（
```
types.ts
```
、
```
constants.ts
```
、
```
helpers.ts
```
、
```
index.ts
```
）