You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
9.8 KiB
9.8 KiB
项目结构
文档版本：v1.1
最后更新：2025-01-18
目录
1. 目录结构
src/
├── app/ # 应用入口层
│ ├── App.tsx # 根组件
│ ├── Router.tsx # 路由配置
│ └── providers/ # Provider 组件
│ ├── index.tsx
│ ├── QueryProvider.tsx
│ └── ThemeProvider.tsx
│
├── components/ # 组件层
│ ├── ui/ # 基础 UI 组件 (shadcn/ui)
│ │ ├── button.tsx
│ │ ├── input.tsx
│ │ ├── dialog.tsx
│ │ └── ...
│ │
│ ├── layout/ # 布局组件
│ │ ├── AppLayout.tsx # 应用主布局
│ │ ├── TopBar.tsx # 顶部导航栏
│ │ ├── LeftSidebar.tsx # 左侧边栏（项目/素材库）
│ │ ├── CenterArea.tsx # 中间区域（分镜列表+预览+AI输入）
│ │ └── RightSidebar.tsx # 右侧边栏（图片提示词/角度变换/镜头调整）
│ │
│ ├── features/ # 功能组件
│ │ ├── storyboard/ # 分镜相关
│ │ │ ├── StoryboardPanel.tsx
│ │ │ ├── StoryboardItem.tsx
│ │ │ ├── StoryboardEditor.tsx
│ │ │ └── index.ts
│ │ │
│ │ ├── timeline/ # 分镜看板相关
│ │ │ ├── Storyboard BoardPanel.tsx
│ │ │ ├── Storyboard BoardTrack.tsx
│ │ │ ├── Storyboard BoardItem.tsx
│ │ │ ├── Storyboard BoardControls.tsx
│ │ │ └── index.ts
│ │ │
│ │ ├── preview/ # 预览相关
│ │ │ ├── PreviewPanel.tsx
│ │ │ ├── VideoPlayer.tsx
│ │ │ ├── PlaybackControls.tsx
│ │ │ └── index.ts
│ │ │
│ │ ├── ai/ # AI 功能
│ │ │ ├── AIPromptPanel.tsx
│ │ │ ├── AIGenerateForm.tsx
│ │ │ ├── AIPreviewModal.tsx
│ │ │ └── index.ts
│ │ │
│ │ ├── resources/ # 资源管理
│ │ │ ├── ResourcePanel.tsx
│ │ │ ├── ResourceGrid.tsx
│ │ │ ├── ResourceUploader.tsx
│ │ │ └── index.ts
│ │ │
│ │ ├── project/ # 项目管理
│ │ │ ├── ProjectList.tsx
│ │ │ ├── ProjectCard.tsx
│ │ │ ├── CreateProjectModal.tsx
│ │ │ └── index.ts
│ │ │
│ │ └── settings/ # 设置
│ │ ├── SettingsPanel.tsx
│ │ ├── ExportSettings.tsx
│ │ └── index.ts
│ │
│ └── common/ # 通用组件
│ ├── LoadingSpinner.tsx
│ ├── ErrorBoundary.tsx
│ ├── EmptyState.tsx
│ ├── Tooltip.tsx
│ └── index.ts
│
├── hooks/ # 自定义 Hooks
│ ├── api/ # API 相关 Hooks
│ │ ├── useProjects.ts
│ │ ├── useStoryboards.ts
│ │ ├── useResources.ts
│ │ └── useAIGenerate.ts
│ │
│ ├── useDebounce.ts
│ ├── useLocalStorage.ts
│ ├── useMediaQuery.ts
│ ├── useKeyboardShortcuts.ts
│ └── index.ts
│
├── stores/ # Zustand 状态管理
│ ├── appStore.ts # 全局应用状态
│ ├── projectStore.ts # 项目状态
│ ├── editorStore.ts # 编辑器状态
│ ├── uiStore.ts # UI 状态
│ └── index.ts
│
├── services/ # 服务层
│ ├── api/ # API 服务
│ │ ├── client.ts # Axios 客户端配置
│ │ ├── projects.ts # 项目 API
│ │ ├── storyboards.ts # 分镜 API
│ │ ├── resources.ts # 资源 API
│ │ ├── ai.ts # AI 生成 API
│ │ └── index.ts
│ │
│ └── mock/ # Mock 数据服务
│ ├── mockClient.ts
│ ├── mockData.ts
│ └── handlers.ts
│
├── types/ # TypeScript 类型定义
│ ├── project.ts
│ ├── storyboard.ts
│ ├── resource.ts
│ ├── timeline.ts
│ ├── ai.ts
│ ├── api.ts
│ └── index.ts
│
├── utils/ # 工具函数
│ ├── format.ts # 格式化工具
│ ├── validation.ts # 验证工具
│ ├── storage.ts # 存储工具
│ ├── time.ts # 时间处理
│ └── index.ts
│
├── constants/ # 常量定义
│ ├── config.ts # 配置常量
│ ├── routes.ts # 路由常量
│ ├── keys.ts # 键名常量
│ └── index.ts
│
├── styles/ # 全局样式
│ ├── globals.css # 全局 CSS
│ └── animations.css # 动画定义
│
├── assets/ # 静态资源
│ ├── images/
│ └── fonts/
│
├── lib/ # 第三方库配置
│ └── utils.ts # shadcn/ui 工具
│
├── main.tsx # 应用入口
└── vite-env.d.ts # Vite 类型声明
2. 模块职责说明
| 目录 | 职责 | 原则 |
|---|---|---|
app/ |
应用配置、Provider、路由 | 只放应用级配置 |
components/ui/ |
基础 UI 组件 | 无业务逻辑，纯展示 |
components/layout/ |
布局组件 | 定义页面结构 |
components/features/ |
功能组件 | 按功能模块组织 |
components/common/ |
通用组件 | 跨模块复用 |
hooks/ |
自定义 Hooks | 逻辑复用 |
stores/ |
全局状态 | Zustand stores |
services/ |
外部服务交互 | API 调用、Mock |
types/ |
类型定义 | 所有 TS 类型 |
utils/ |
工具函数 | 纯函数，无副作用 |
constants/ |
常量 | 配置、枚举、键名 |
2.1 组件层级说明
UI 组件 (components/ui/)
- 职责：提供基础的、可复用的 UI 组件
- 特点：无业务逻辑，完全受控
- 示例：Button、Input、Dialog、Select
- 来源：主要来自 shadcn/ui
布局组件 (components/layout/)
- 职责：定义页面的整体结构和布局
- 特点：组合 UI 组件，定义页面骨架
- 示例：AppLayout、TopBar、Sidebar
功能组件 (components/features/)
- 职责：实现具体的业务功能
- 特点：包含业务逻辑，调用 API 和状态管理
- 组织：按功能模块分组（storyboard、timeline、preview 等）
通用组件 (components/common/)
- 职责：跨功能模块复用的组件
- 特点：通用性强，可配置性高
- 示例：LoadingSpinner、ErrorBoundary、EmptyState
3. 导入别名配置
3.1 Vite 配置
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from "path";
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
"@": path.resolve(__dirname, "./src"),
"@components": path.resolve(__dirname, "./src/components"),
"@hooks": path.resolve(__dirname, "./src/hooks"),
"@stores": path.resolve(__dirname, "./src/stores"),
"@services": path.resolve(__dirname, "./src/services"),
"@types": path.resolve(__dirname, "./src/types"),
"@utils": path.resolve(__dirname, "./src/utils"),
"@constants": path.resolve(__dirname, "./src/constants"),
"@assets": path.resolve(__dirname, "./src/assets"),
},
},
});
3.2 TypeScript 配置
// tsconfig.json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@components/*": ["src/components/*"],
"@hooks/*": ["src/hooks/*"],
"@stores/*": ["src/stores/*"],
"@services/*": ["src/services/*"],
"@types/*": ["src/types/*"],
"@utils/*": ["src/utils/*"],
"@constants/*": ["src/constants/*"],
"@assets/*": ["src/assets/*"]
}
}
}
3.3 使用示例
// ✅ 推荐：使用别名
import { Button } from "@components/ui/button";
import { useStoryboards } from "@hooks/api/useStoryboards";
import { useEditorStore } from "@stores/editorStore";
import { cn } from "@/lib/utils";
import type { Storyboard } from "@types";
// ❌ 避免：使用相对路径（深层嵌套时）
import { Button } from "../../../components/ui/button";
import { useStoryboards } from "../../../hooks/api/useStoryboards";
相关文档
最后更新：2025-01-18 | 版本：v1.1