Files

2025-10-06 00:02:40 +08:00

6.6 KiB

Raw Blame History

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）。

构建和运行

开发环境

安装依赖:
```
npm install
```
配置环境变量:
- 复制 .env.example 为 .env
- 在 .env 文件中设置 VITE_GEMINI_API_KEY (必需)
- 可选设置 VITE_ACCESS_TOKEN 和 VITE_UPLOAD_ASSET_URL 以启用图像上传功能

启动开发服务器:

# 启动Web开发服务器
npm run dev

# 启动Electron开发环境
npm run electron:dev

访问 http://localhost:5173 查看Web应用。

构建和部署

构建生产版本:

# 构建Web版本
npm run build

# 构建Electron桌面应用
npm run electron:build

预览生产构建:
```
npm run preview
```

测试

运行测试:
```
npm run test
```
运行测试并监听变化:
```
npm run test:watch
```

代码质量

运行 ESLint:
```
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 后缀

贡献指南

遵循既定的代码风格和项目结构
保持组件在 200 行以内
维护类型安全，严格使用 TypeScript 和正确定义
彻底测试，确保键盘导航和可访问性
记录更改，更新 README 并添加内联注释
遵守 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: 构建工具

6.6 KiB Raw Blame History Unescape Escape