You've already forked Nano-Banana-AI-Image-Editor
更新描述文档；
修复了若干错误；
This commit is contained in:
233
IFLOW.md
233
IFLOW.md
@@ -1,142 +1,133 @@
|
||||
# Nano Banana AI Image Editor - iFlow 文档
|
||||
# Nano Banana AI 图像编辑器 - iFlow 上下文
|
||||
|
||||
## 项目概述
|
||||
|
||||
Nano Banana AI Image Editor 是一个基于 React 的 AI 图像编辑工具，用户可以通过直观的界面与 Google 的 Gemini AI 模型进行交互，实现图像生成和编辑功能。
|
||||
这是一个基于 React 和 TypeScript 的 AI 图像生成与编辑应用，名为 Nano Banana AI Image Editor。它利用 Google Gemini 2.5 Flash Image 模型，提供文本到图像生成和基于自然语言的图像编辑功能。该应用具有现代化的用户界面，支持交互式画布、区域选择和历史记录管理。
|
||||
|
||||
## 技术栈
|
||||
主要技术栈包括：
|
||||
- **前端框架**: React 18, TypeScript
|
||||
- **状态管理**: Zustand (应用状态), React Query (服务端状态)
|
||||
- **UI 库**: Tailwind CSS
|
||||
- **画布库**: Konva.js (react-konva)
|
||||
- **AI 集成**: Google Generative AI SDK (Gemini)
|
||||
- **数据存储**: IndexedDB (通过 idb-keyval)
|
||||
- **构建工具**: Vite
|
||||
|
||||
- **核心框架**: React 18.x (TypeScript)
|
||||
- **构建工具**: Vite 5.x
|
||||
- **语言**: TypeScript (ES2020)
|
||||
- **状态管理**: Zustand
|
||||
- **数据获取**: TanStack Query (React Query)
|
||||
- **UI 框架**:
|
||||
- Tailwind CSS 3.x (样式框架)
|
||||
- Radix UI (无样式的可访问 UI 组件)
|
||||
- Lucide React (图标库)
|
||||
- **图像处理**:
|
||||
- Konva (2D 画布库)
|
||||
- react-konva (Konva 的 React 封装)
|
||||
- **本地存储**: IndexedDB (通过 idb-keyval 库操作)
|
||||
- **AI 集成**: Google Generative AI SDK (@google/genai)
|
||||
- **工具库**:
|
||||
- class-variance-authority (组件变体管理)
|
||||
- clsx + tailwind-merge (CSS 类名合并)
|
||||
- fabric.js (备用画布库)
|
||||
项目结构遵循标准的 React 应用组织方式，主要源代码位于 `src/` 目录下。
|
||||
|
||||
## 代码风格和命名规范
|
||||
## 构建和运行
|
||||
|
||||
### 开发环境
|
||||
|
||||
1. **安装依赖**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **配置环境变量**:
|
||||
- 复制 `.env.example` 为 `.env`
|
||||
- 在 `.env` 文件中设置 `VITE_GEMINI_API_KEY` (必需)
|
||||
- 可选设置 `VITE_ACCESS_TOKEN` 和 `VITE_UPLOAD_ASSET_URL` 以启用图像上传功能
|
||||
|
||||
3. **启动开发服务器**:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
访问 `http://localhost:5173` 查看应用。
|
||||
|
||||
### 构建和部署
|
||||
|
||||
- **构建生产版本**:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
- **预览生产构建**:
|
||||
```bash
|
||||
npm run preview
|
||||
```
|
||||
|
||||
### 测试
|
||||
|
||||
- **运行测试**:
|
||||
```bash
|
||||
npm run test
|
||||
```
|
||||
|
||||
- **运行测试并监听变化**:
|
||||
```bash
|
||||
npm run test:watch
|
||||
```
|
||||
|
||||
### 代码质量
|
||||
|
||||
- **运行 ESLint**:
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
|
||||
## 开发约定
|
||||
|
||||
### 代码风格
|
||||
- 使用 TypeScript 严格模式 (strict: true)
|
||||
- 函数式组件为主，使用 React Hooks
|
||||
- 组件文件使用 .tsx 扩展名
|
||||
- 工具函数文件使用 .ts 扩展名
|
||||
- 使用 ESLint 进行代码检查
|
||||
- 启用严格的 TypeScript 编译选项
|
||||
|
||||
### 命名规范
|
||||
- 组件文件和组件名使用 PascalCase (如 `Header.tsx`, `ImageCanvas`)
|
||||
- 工具函数和普通文件使用 camelCase (如 `imageUtils.ts`, `useAppStore.ts`)
|
||||
- 常量使用 UPPER_SNAKE_CASE
|
||||
- 变量和函数使用 camelCase
|
||||
- 组件 Props 接口命名为组件名 + Props (如 `ButtonProps`)
|
||||
- Hook 函数以 use 开头 (如 `useAppStore`, `useImageGeneration`)
|
||||
- 使用 TypeScript 进行类型安全检查
|
||||
- 使用 ESLint 进行代码规范检查
|
||||
- 使用 Prettier 进行代码格式化 (通过 ESLint 配置集成)
|
||||
- 组件文件使用 `.tsx` 扩展名
|
||||
- 工具函数文件使用 `.ts` 扩展名
|
||||
|
||||
## 样式和 UI 框架
|
||||
|
||||
### Tailwind CSS
|
||||
- 使用自定义颜色方案，以香蕉黄 (banana) 为主题色
|
||||
- 定义了 light 主题颜色 (背景、面板、边框、文字等)
|
||||
- 使用自定义间距、阴影和动画
|
||||
- 使用 tailwind-merge 和 clsx 进行类名合并
|
||||
|
||||
### 组件设计
|
||||
- 使用 Radix UI 构建无样式的可访问组件
|
||||
- 自定义 UI 组件位于 `src/components/ui` 目录
|
||||
- 组件变体使用 class-variance-authority 管理
|
||||
- 图标使用 Lucide React
|
||||
|
||||
## 项目结构
|
||||
### 项目结构约定
|
||||
|
||||
```
|
||||
Nano-Banana-AI-Image-Editor/
|
||||
├── src/
|
||||
│ ├── components/ # React 组件
|
||||
│ │ ├── ui/ # 基础 UI 组件
|
||||
│ │ ├── Header.tsx # 应用头部
|
||||
│ │ ├── ImageCanvas.tsx # 图像画布
|
||||
│ │ ├── PromptComposer.tsx # 提示词编辑器
|
||||
│ │ ├── HistoryPanel.tsx # 历史记录面板
|
||||
│ │ └── ... # 其他组件
|
||||
│ ├── hooks/ # 自定义 React Hooks
|
||||
│ │ ├── useImageGeneration.ts # 图像生成 Hook
|
||||
│ │ ├── useIndexedDBListener.ts # IndexedDB 监听 Hook
|
||||
│ │ └── useKeyboardShortcuts.ts # 键盘快捷键 Hook
|
||||
│ ├── services/ # 业务逻辑服务
|
||||
│ │ ├── geminiService.ts # Gemini AI 服务
|
||||
│ │ ├── indexedDBService.ts # IndexedDB 操作服务
|
||||
│ │ ├── uploadService.ts # 文件上传服务
|
||||
│ │ └── cacheService.ts # 缓存服务
|
||||
│ ├── store/ # 状态管理
|
||||
│ │ └── useAppStore.ts # 全局状态管理 (Zustand)
|
||||
│ ├── utils/ # 工具函数
|
||||
│ │ ├── cn.ts # 类名合并工具
|
||||
│ │ └── imageUtils.ts # 图像处理工具
|
||||
│ ├── types/ # TypeScript 类型定义
|
||||
│ ├── App.tsx # 根组件
|
||||
│ ├── main.tsx # 应用入口
|
||||
│ └── vite-env.d.ts # Vite 类型声明
|
||||
├── public/ # 静态资源
|
||||
├── node_modules/ # 依赖包
|
||||
├── index.html # HTML 模板
|
||||
├── package.json # 项目配置
|
||||
├── tsconfig.json # TypeScript 配置
|
||||
├── vite.config.ts # Vite 配置
|
||||
├── tailwind.config.js # Tailwind 配置
|
||||
├── postcss.config.js # PostCSS 配置
|
||||
├── eslint.config.js # ESLint 配置
|
||||
└── README.md # 项目说明
|
||||
src/
|
||||
├── components/ # React 组件
|
||||
│ ├── ui/ # 可重用的 UI 组件
|
||||
│ ├── PromptComposer.tsx # 提示输入和工具选择
|
||||
│ ├── ImageCanvas.tsx # 使用 Konva 的交互式画布
|
||||
│ ├── HistoryPanel.tsx # 生成历史和变体
|
||||
│ ├── Header.tsx # 应用头部和导航
|
||||
│ └── InfoModal.tsx # 关于模态框和链接
|
||||
├── services/ # 外部服务集成
|
||||
│ ├── geminiService.ts # Gemini API 客户端
|
||||
│ ├── uploadService.ts # 图像上传服务
|
||||
│ ├── cacheService.ts # IndexedDB 缓存层
|
||||
│ └── referenceImageService.ts # 参考图像处理
|
||||
├── store/ # Zustand 状态管理
|
||||
│ └── useAppStore.ts # 全局应用状态
|
||||
├── hooks/ # 自定义 React 钩子
|
||||
│ ├── useImageGeneration.ts # 生成和编辑逻辑
|
||||
│ └── useKeyboardShortcuts.ts # 键盘导航
|
||||
├── utils/ # 工具函数
|
||||
│ ├── cn.ts # 类名工具
|
||||
│ └── imageUtils.ts # 图像处理助手
|
||||
└── types/ # TypeScript 类型定义
|
||||
└── index.ts # 核心类型定义
|
||||
```
|
||||
|
||||
## 核心功能模块
|
||||
### 组件开发
|
||||
|
||||
### 1. 图像画布 (ImageCanvas)
|
||||
- 使用 Konva 和 react-konva 实现图像显示和编辑
|
||||
- 支持图像缩放、平移
|
||||
- 实现画笔工具进行遮罩绘制
|
||||
- 支持图像下载功能
|
||||
- 组件应保持较小的体积（建议小于200行）
|
||||
- 使用函数式组件和 React Hooks
|
||||
- 组件应具有明确的接口（Props）
|
||||
- 尽可能使用 TypeScript 进行类型定义
|
||||
|
||||
### 2. 提示词编辑 (PromptComposer)
|
||||
- 用户输入提示词生成图像
|
||||
- 提供提示词建议功能
|
||||
- 集成 AI 模型参数调整 (如风格、质量等)
|
||||
### 状态管理
|
||||
|
||||
### 3. 历史记录 (HistoryPanel)
|
||||
- 显示生成的图像历史
|
||||
- 支持历史图像的查看和重新编辑
|
||||
- 使用 IndexedDB 存储历史数据
|
||||
- 全局状态使用 Zustand 管理 (`src/store/useAppStore.ts`)
|
||||
- 服务端状态使用 React Query 管理
|
||||
- 组件内部状态使用 React 的 useState 和 useReducer
|
||||
|
||||
### 4. 状态管理 (useAppStore)
|
||||
- 使用 Zustand 管理全局状态
|
||||
- 存储画布状态、用户设置、历史记录等
|
||||
- 提供状态操作方法
|
||||
### 测试
|
||||
|
||||
### 5. AI 服务 (geminiService)
|
||||
- 集成 Google Gemini AI 模型
|
||||
- 实现图像生成和编辑功能
|
||||
- 处理与 AI 模型的交互
|
||||
- 使用 Jest 和 React Testing Library 进行测试
|
||||
- 测试文件放在 `src/__tests__` 目录下
|
||||
- 测试文件名应与被测试文件名对应，加上 `.test.tsx` 或 `.test.ts` 后缀
|
||||
|
||||
## 开发环境配置
|
||||
### 贡献指南
|
||||
|
||||
1. 安装依赖: `npm install`
|
||||
2. 启动开发服务器: `npm run dev`
|
||||
3. 构建生产版本: `npm run build`
|
||||
4. 代码检查: `npm run lint`
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 项目使用 IndexedDB 存储图像数据，需要注意存储空间管理
|
||||
- AI 功能需要配置 Google API 密钥
|
||||
- 图像处理功能依赖浏览器 Canvas API
|
||||
- 移动端适配需要特别关注界面布局和交互
|
||||
1. 遵循既定的代码风格和项目结构
|
||||
2. 保持组件在 200 行以内
|
||||
3. 维护类型安全，严格使用 TypeScript 和正确定义
|
||||
4. 彻底测试，确保键盘导航和可访问性
|
||||
5. 记录更改，更新 README 并添加内联注释
|
||||
6. 遵守 AGPL-3.0 许可证
|
||||
Reference in New Issue
Block a user