You've already forked Nano-Banana-AI-Image-Editor
201 lines
6.6 KiB
Markdown
201 lines
6.6 KiB
Markdown
# Nano Banana AI 图像编辑器 - iFlow 上下文
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 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
|
||
- **桌面应用**: Electron
|
||
|
||
项目结构遵循标准的 React 应用组织方式，主要源代码位于 `src/` 目录下。该项目同时支持Web和桌面应用（Electron）。
|
||
|
||
## 构建和运行
|
||
|
||
### 开发环境
|
||
|
||
1. **安装依赖**:
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
2. **配置环境变量**:
|
||
- 复制 `.env.example` 为 `.env`
|
||
- 在 `.env` 文件中设置 `VITE_GEMINI_API_KEY` (必需)
|
||
- 可选设置 `VITE_ACCESS_TOKEN` 和 `VITE_UPLOAD_ASSET_URL` 以启用图像上传功能
|
||
|
||
3. **启动开发服务器**:
|
||
```bash
|
||
# 启动Web开发服务器
|
||
npm run dev
|
||
|
||
# 启动Electron开发环境
|
||
npm run electron:dev
|
||
```
|
||
访问 `http://localhost:5173` 查看Web应用。
|
||
|
||
### 构建和部署
|
||
|
||
- **构建生产版本**:
|
||
```bash
|
||
# 构建Web版本
|
||
npm run build
|
||
|
||
# 构建Electron桌面应用
|
||
npm run electron:build
|
||
```
|
||
|
||
- **预览生产构建**:
|
||
```bash
|
||
npm run preview
|
||
```
|
||
|
||
### 测试
|
||
|
||
- **运行测试**:
|
||
```bash
|
||
npm run test
|
||
```
|
||
|
||
- **运行测试并监听变化**:
|
||
```bash
|
||
npm run test:watch
|
||
```
|
||
|
||
### 代码质量
|
||
|
||
- **运行 ESLint**:
|
||
```bash
|
||
npm run lint
|
||
```
|
||
|
||
## 开发约定
|
||
|
||
### 代码风格
|
||
|
||
- 使用 TypeScript 进行类型安全检查
|
||
- 使用 ESLint 进行代码规范检查
|
||
- 使用 Prettier 进行代码格式化 (通过 ESLint 配置集成)
|
||
- 组件文件使用 `.tsx` 扩展名
|
||
- 工具函数文件使用 `.ts` 扩展名
|
||
|
||
### 项目结构约定
|
||
|
||
```
|
||
src/
|
||
├── components/ # React 组件
|
||
│ ├── ui/ # 可重用的 UI 组件
|
||
│ │ ├── Button.tsx
|
||
│ │ ├── Input.tsx
|
||
│ │ └── Textarea.tsx
|
||
│ ├── CustomTitleBar.tsx # 自定义标题栏（用于Electron应用）
|
||
│ ├── Header.tsx # 应用头部和导航
|
||
│ ├── PromptComposer.tsx # 提示输入和工具选择
|
||
│ ├── ImageCanvas.tsx # 使用 Konva 的交互式画布
|
||
│ ├── HistoryPanel.tsx # 生成历史和变体
|
||
│ ├── InfoModal.tsx # 关于模态框和链接
|
||
│ ├── Toast.tsx # 消息提示组件
|
||
│ └── ToastContext.tsx # 消息提示上下文
|
||
├── services/ # 外部服务集成
|
||
│ ├── geminiService.ts # Gemini API 客户端
|
||
│ ├── indexedDBService.ts # IndexedDB 数据库服务
|
||
│ ├── cacheService.ts # IndexedDB 缓存层（未使用）
|
||
│ ├── referenceImageService.ts # 参考图像处理（未使用）
|
||
│ └── uploadService.ts # 图像上传服务（未使用）
|
||
├── store/ # Zustand 状态管理
|
||
│ └── useAppStore.ts # 全局应用状态
|
||
├── hooks/ # 自定义 React 钩子
|
||
│ ├── useImageGeneration.ts # 生成和编辑逻辑
|
||
│ ├── useKeyboardShortcuts.ts # 键盘导航
|
||
│ └── useIndexedDBListener.ts # IndexedDB监听器（未使用）
|
||
├── utils/ # 工具函数
|
||
│ ├── cn.ts # 类名工具
|
||
│ └── imageUtils.ts # 图像处理助手
|
||
├── types/ # TypeScript 类型定义
|
||
│ └── index.ts # 核心类型定义
|
||
└── __tests__/ # 测试文件
|
||
├── ImageCanvas.test.tsx
|
||
├── PromptComposer.test.tsx
|
||
├── useAppStore.test.ts
|
||
└── useImageGeneration.test.ts
|
||
```
|
||
|
||
### 组件开发
|
||
|
||
- 组件应保持较小的体积（建议小于200行）
|
||
- 使用函数式组件和 React Hooks
|
||
- 组件应具有明确的接口（Props）
|
||
- 尽可能使用 TypeScript 进行类型定义
|
||
|
||
### 状态管理
|
||
|
||
- 全局状态使用 Zustand 管理 (`src/store/useAppStore.ts`)
|
||
- 服务端状态使用 React Query 管理
|
||
- 组件内部状态使用 React 的 useState 和 useReducer
|
||
|
||
### 测试
|
||
|
||
- 使用 Jest 和 React Testing Library 进行测试
|
||
- 测试文件放在 `src/__tests__` 目录下
|
||
- 测试文件名应与被测试文件名对应，加上 `.test.tsx` 或 `.test.ts` 后缀
|
||
|
||
### 贡献指南
|
||
|
||
1. 遵循既定的代码风格和项目结构
|
||
2. 保持组件在 200 行以内
|
||
3. 维护类型安全，严格使用 TypeScript 和正确定义
|
||
4. 彻底测试，确保键盘导航和可访问性
|
||
5. 记录更改，更新 README 并添加内联注释
|
||
6. 遵守 AGPL-3.0 许可证
|
||
|
||
## 项目特性
|
||
|
||
### AI 图像生成与编辑
|
||
- 文本到图像生成：使用 Google Gemini 2.5 Flash Image 模型从描述性提示创建图像
|
||
- 对话式编辑：使用自然语言指令修改现有图像
|
||
- 区域感知选择：通过绘制遮罩来针对特定区域进行编辑
|
||
|
||
### 用户界面
|
||
- 交互式画布：支持平滑缩放、平移和导航大图像
|
||
- 画笔工具：可变画笔尺寸以实现精确的遮罩绘制
|
||
- 响应式设计：在所有设备上都能完美运行
|
||
- 键盘快捷键：使用热键提高工作效率
|
||
|
||
### 数据管理
|
||
- 生成历史：跟踪所有创作和编辑记录
|
||
- 变体比较：生成并并排比较多个版本
|
||
- 离线缓存：使用 IndexedDB 存储以实现离线资产访问
|
||
- 项目管理：有序存储所有生成的内容
|
||
|
||
### 部署选项
|
||
- Web 应用：标准的 Web 应用程序，可在浏览器中运行
|
||
- 桌面应用：使用 Electron 构建的桌面应用程序，支持 Windows、macOS 和 Linux
|
||
|
||
## 依赖包更新
|
||
|
||
项目已清理未使用的依赖包，当前依赖包括：
|
||
|
||
### 运行时依赖
|
||
- `@google/genai`: Google Generative AI SDK
|
||
- `@radix-ui/react-dialog`: React 对话框组件
|
||
- `@tanstack/react-query`: 服务端状态管理
|
||
- `class-variance-authority`, `clsx`, `tailwind-merge`: 类名工具
|
||
- `idb-keyval`: IndexedDB 封装库
|
||
- `konva`, `react-konva`: Canvas 图形库
|
||
- `lucide-react`: 图标库
|
||
- `react`, `react-dom`: React 核心库
|
||
- `react-day-picker`: 日期选择器组件
|
||
- `zustand`: 客户端状态管理
|
||
|
||
### 开发依赖
|
||
- `@eslint/js`, `eslint`, `typescript-eslint`: 代码质量工具
|
||
- `@testing-library/*`: 测试工具
|
||
- `electron-builder`: Electron 应用构建工具
|
||
- `typescript`: TypeScript 编译器
|
||
- `vite`: 构建工具 |