# 组件创建规范

## 目录结构

采用模块化结构组织组件：

```
src/components/
├── video/
│   ├── index.ts           # 导出入口
│   ├── video.tsx          # 主组件
│   ├── video.types.ts     # 类型定义
│   ├── video.hooks.ts     # 组件专用 hooks（可选）
│   └── video.utils.ts     # 工具函数（可选）
├── button/
│   ├── index.ts
│   └── button.tsx
├── ui/                    # 基础 UI 组件
│   ├── button.tsx
│   └── dialog.tsx
└── index.ts               # 统一导出所有组件
```

## 命名规范

| 类型       | 规范               | 示例               |
| ---------- | ------------------ | ------------------ |
| 文件名     | kebab-case         | `video-player.tsx` |
| 目录名     | kebab-case         | `video-player/`    |
| 组件名     | PascalCase         | `VideoPlayer`      |
| Props 接口 | `{组件名}Props`    | `VideoPlayerProps` |
| Ref 接口   | `{组件名}Ref`      | `VideoPlayerRef`   |
| 导出类型   | `{组件名}{类型名}` | `VideoAnchor`      |

## 文件结构顺序

每个组件文件按以下顺序组织：

1. **Imports** - 导入语句
2. **Types/Interfaces** - 类型定义（需导出）
3. **Constants** - 常量定义
4. **Helper Functions** - 辅助函数
5. **Component** - 组件定义
6. **displayName** - 设置显示名称
7. **Export** - 默认导出

## 组件模板

````tsx
import React, {
  forwardRef,
  useRef,
  useState,
  useImperativeHandle,
} from "react";
import { cn } from "@/lib/utils";

/** 组件配置项 */
export interface ComponentNameProps {
  /** 必填属性说明 */
  requiredProp: string;
  /** 可选属性说明 */
  optionalProp?: boolean;
  /** 子元素 */
  children?: React.ReactNode;
  /** 自定义类名 */
  className?: string;
}

/** 组件 Ref 暴露的方法 */
export interface ComponentNameRef {
  /** 方法说明 */
  methodName: () => void;
}

/**
 * ComponentName - 组件简要说明
 *
 * @example
 * ```tsx
 * <ComponentName requiredProp="value" />
 * ```
 */
const ComponentName = forwardRef<ComponentNameRef, ComponentNameProps>(
  ({ requiredProp, optionalProp = false, className, children }, ref) => {
    // 状态定义
    const [state, setState] = useState<string>("");

    // Ref 定义
    const innerRef = useRef<HTMLDivElement>(null);

    // 暴露方法给父组件
    useImperativeHandle(ref, () => ({
      methodName: () => {
        // 实现
      },
    }));

    return <div className={cn("base-class", className)}>{children}</div>;
  }
);

ComponentName.displayName = "ComponentName";

export default ComponentName;
````

## index.ts 导出模板

```ts
export { default } from "./component-name";
export { default as ComponentName } from "./component-name";
export type { ComponentNameProps, ComponentNameRef } from "./component-name";
```

## 类型规范

- **必须**为所有 props、state、函数参数和返回值声明类型
- **禁止**使用 `any`，使用 `unknown` 或泛型替代
- **导出**所有公共接口和类型
- 使用 `React.ReactNode` 表示子元素类型
- 使用 `React.CSSProperties` 表示样式对象

## 样式规范

- 使用 `cn()` 工具函数合并类名
- 优先使用 Tailwind CSS 类名
- 支持通过 `className` prop 自定义样式
- 避免内联样式，除非是动态计算值

```tsx
// ✅ 推荐
<div className={cn("flex items-center", isActive && "bg-blue-500", className)}>

// ❌ 避免
<div style={{ display: "flex", alignItems: "center" }}>
```

## 最佳实践

1. **单一职责** - 每个组件只做一件事，保持在 200 行以内
2. **使用 forwardRef** - 需要暴露 ref 的组件必须使用
3. **设置 displayName** - 便于 React DevTools 调试
4. **提取逻辑** - 复杂逻辑提取到自定义 hooks
5. **组合优于继承** - 使用 children 和 render props
6. **早返回** - 避免深层嵌套，使用 early return

## 文件拆分指南

| 文件             | 用途           | 何时创建             |
| ---------------- | -------------- | -------------------- |
| `*.tsx`          | 主组件         | 必须                 |
| `*.types.ts`     | 类型定义       | 类型超过 30 行       |
| `*.hooks.ts`     | 组件专用 hooks | 有可复用的状态逻辑   |
| `*.utils.ts`     | 工具函数       | 有纯函数逻辑需要提取 |
| `*.constants.ts` | 常量定义       | 有多个常量需要共享   |

<!-- 1. common / base (基础组件)
存放与业务逻辑解耦的原子级组件。这些组件通常不包含 API 请求，只负责展示和交互。
示例：MyButton, MyInput, Modal, Icon。
用途：如果项目没有使用 Ant Design 或 Element Plus 等 UI 库，或者在其基础上二次封装，则放在此处 [1, 2]。
2. business / biz (业务组件)
存放与特定业务逻辑耦合、但在多个页面中复用的组件。
示例：UserSelect（包含用户列表接口请求）、AddressPicker、OrderCard。
用途：这些组件包含业务状态或特定的数据处理逻辑 [1, 3]。
3. layout (布局组件)
存放页面的整体结构组件。
示例：Header, Footer, Sidebar, NavBar。
用途：定义应用的外壳结构，通常在全局路由配置中使用 [2, 4]。
4. hoc / render-props (高阶/逻辑组件)
存放不直接渲染 UI，而是通过高阶组件（HOC）或 Render Props 模式提供逻辑复用的组件。
示例：withAuth（权限校验）、ErrorBoundary（错误边界）。
5. svg / icons (图标组件)
专门用于存放封装后的 SVG 图标或字体图标组件。
用途：方便通过组件形式调用图标，如 <IconName />。
标准组件内部结构
为了保持清晰，每个具体的组件通常建议以文件夹的形式存在，而不是单个文件：
text
components/
└── MyComponent/
    ├── index.ts          # 组件对外暴露的入口
    ├── MyComponent.tsx   # 组件核心代码
    ├── MyComponent.scss  # 组件私有样式
    ├── types.ts          # TypeScript 类型定义
    ├── hooks.ts          # 组件内部抽离的逻辑 (可选)
    └── __tests__/        # 单元测试文件 (可选)
请谨慎使用此类代码。

注意事项：页面级组件
请注意，仅在单个页面中使用的私有组件，通常不建议放在 src/components 下，而应放在对应页面的文件夹内（例如 src/pages/Home/components），以避免全局组件目录过于臃肿 -->