# 开发规范 > **文档版本**：v1.1 > **最后更新**：2025-01-18 --- ## 目录 1. [文件命名规范](#1-文件命名规范) 2. [组件编写规范](#2-组件编写规范) 3. [导入顺序规范](#3-导入顺序规范) 4. [Git Commit 规范](#4-git-commit-规范) --- ## 1. 文件命名规范 | 类型 | 命名规范 | 示例 | | --------- | ------------- | ------------------------- | | 组件文件 | PascalCase | `StoryboardItem.tsx` | | Hook 文件 | camelCase | `useStoryboards.ts` | | 工具文件 | camelCase | `formatDuration.ts` | | 类型文件 | camelCase | `storyboard.ts` | | 常量文件 | camelCase | `routes.ts` | | 样式文件 | kebab-case | `globals.css` | | 测试文件 | 原文件名.test | `StoryboardItem.test.tsx` | --- ## 2. 组件编写规范 ### 2.1 组件文件结构 ```typescript // 组件文件结构 import { useState, useCallback, memo } from 'react'; import { cn } from '@/lib/utils'; import { Button } from '@/components/ui/button'; import type { Storyboard } from '@types'; // Props 类型定义 interface StoryboardItemProps { storyboard: Storyboard; isSelected: boolean; onSelect: (id: string) => void; className?: string; } // 组件实现 export const StoryboardItem = memo(function StoryboardItem({ storyboard, isSelected, onSelect, className, }: StoryboardItemProps) { // Hooks const [isHovered, setIsHovered] = useState(false); // 事件处理 const handleClick = useCallback(() => { onSelect(storyboard.id); }, [storyboard.id, onSelect]); // 渲染 return (

setIsHovered(true)} onMouseLeave={() => setIsHovered(false)} >

{storyboard.title}

{storyboard.description}

); }); ``` ### 2.2 组件编写原则 1. **单一职责**：每个组件只负责一个功能 2. **Props 类型化**：所有 Props 必须定义类型 3. **使用 memo**：对于频繁渲染的组件使用 memo 优化 4. **事件处理**：使用 useCallback 缓存事件处理函数 5. **样式管理**：使用 cn 工具函数合并样式 --- ## 3. 导入顺序规范 ```typescript // 1. React 相关 import { useState, useEffect, useCallback } from "react"; // 2. 第三方库 import { useQuery } from "@tanstack/react-query"; import { z } from "zod"; // 3. 内部别名导入 - 组件 import { Button } from "@components/ui/button"; import { LoadingSpinner } from "@components/common"; // 4. 内部别名导入 - 其他 import { useStoryboards } from "@hooks/api/useStoryboards"; import { useEditorStore } from "@stores/editorStore"; import { cn } from "@/lib/utils"; // 5. 类型导入 import type { Storyboard } from "@types"; // 6. 相对路径导入 import { StoryboardItem } from "./StoryboardItem"; import "./StoryboardPanel.css"; ``` --- ## 4. Git Commit 规范 ### 4.1 Commit 消息格式 ``` ():