product/TinyPanda
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

文档 完善项目文档结构，添加 AGENTS.md 和更新 README.md

Browse Source
This commit is contained in:
yuantao
2026-01-30 14:01:32 +08:00
commit 067636aa29
2 changed files with 398 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
AGENTS.md Normal file
View File

@@ -0,0 +1,185 @@
# TinyPanda 项目上下文
## 项目概述
TinyPanda 是一个基于 Electron 桌面应用框架的专业图片压缩工具，使用 Tinify API 提供高质量图片压缩服务。
**技术栈：**
- **Electron 32.0.0** - 跨平台桌面应用框架
- **Tinify API** - 图片压缩服务
- **JSZip 3.10.1** - 文件打包下载
- **Electron Store 8.2.0** - 配置持久化
- **原生 CSS** - Windows 11 Fluent Design 风格 UI
**项目作者：** Pandora Studio
**项目仓库：** https://git.pandorastudio.cn/product/TinyPanda.git
**API 文档：** https://tinify.cn/developers/reference/nodejs
## 核心功能
1. **批量图片压缩** - 支持队列管理，可同时处理多张图片
2. **实时进度显示** - 显示压缩进度和状态
3. **压缩效果对比** - 显示压缩前后大小对比及节省比例
4. **打包下载** - 支持将所有压缩后的图片打包为 ZIP 下载
5. **拖拽上传** - 支持拖拽图片到上传区域
6. **自定义标题栏** - 无边框窗口，支持最小化、最大化、关闭
**支持的图片格式：** JPG/JPEG、PNG、WebP
## 项目结构
```
TinyPanda/
├── src/
│ ├── main/
│ │ └── index.js # Electron 主进程（窗口管理、IPC 通信、文件操作）
│ └── renderer/
│ ├── index.html # 渲染进程 HTML 结构
│ ├── styles.css # Windows 11 Fluent Design 风格样式
│ ├── app.js # 渲染进程逻辑（队列管理、UI 交互）
│ └── icons.js # 自定义图标 Web Component (tp-icon)
├── .env # 环境变量（TINIFY_API_KEY）
├── .gitignore
├── package.json # 项目配置和依赖
├── package-lock.json
├── README.md # 项目说明文档
└── brief.txt # 项目简要说明
```
## 构建和运行
### 安装依赖
```bash
npm install
```
### 开发模式运行
```bash
npm run dev
```
### 打包应用
```bash
# 仅打包 Windows 应用
npm run build:win
# 打包所有平台
npm run build
```
### 注意事项
- 首次运行需要在 `.env` 文件中配置 `TINIFY_API_KEY`
- 开发模式下会自动打开开发者工具（当 `NODE_ENV=development`）
- 打包后的应用会输出到 `dist` 目录
## 开发约定
### 代码风格
- 使用 ES6+ JavaScript 语法
- 主进程和渲染进程通过 IPC (Inter-Process Communication) 通信
- 使用 `async/await` 处理异步操作
### IPC 通信协议
**主进程提供的 IPC 处理器：**
| 处理器名称 | 参数 | 返回值 | 说明 |
|-----------|------|--------|------|
| `get-api-key` | 无 | `{ apiKey: string }` | 获取当前 API Key |
| `set-api-key` | `key: string` | `{ success: boolean }` | 设置 API Key |
| `validate-api-key` | `key: string` | `{ valid: boolean }` | 验证 API Key 有效性 |
| `compress-image` | `filePath: string` | `{ success: boolean, compressedData?: string, error?: string }` | 压缩单张图片 |
| `get-image-info` | `filePath: string` | `{ success: boolean, size?: number, error?: string }` | 获取图片文件信息 |
| `save-compressed-image` | `savePath: string, base64Data: string` | `{ success: boolean, error?: string }` | 保存压缩后的图片 |
| `create-zip` | `files: Array<{name: string, data: string}>` | `{ success: boolean, zipData?: string, error?: string }` | 创建 ZIP 压缩包 |
| `select-save-directory` | 无 | `{ canceled: boolean, path?: string }` | 选择保存目录 |
| `select-files` | 无 | `{ canceled: boolean, files?: string[] }` | 选择多个文件 |
| `window-minimize` | 无 | 无 | 最小化窗口 |
| `window-maximize` | 无 | 无 | 最大化/还原窗口 |
| `window-close` | 无 | 无 | 关闭窗口 |
| `window-is-maximized` | 无 | `boolean` | 获取窗口最大化状态 |
### UI 设计规范
- 遵循 Windows 11 Fluent Design 设计语言
- 使用自定义 Web Component `<tp-icon>` 渲染图标
- 状态标签使用颜色编码：
- `status-pending` - 黄色（待处理）
- `status-processing` - 蓝色（处理中）
- `status-completed` - 绿色（已完成）
- `status-error` - 红色（错误）
### 文件命名约定
- 文件大小格式化函数：`formatSize(bytes)` - 返回格式化字符串（如 "1.5 MB"）
- 队列项结构：
```javascript
{
id: number, // 唯一标识
name: string, // 文件名
path: string, // 文件路径
originalSize: number, // 原始大小（字节）
compressedSize: number|null, // 压缩后大小（字节）
compressedData: string|null, // 压缩数据（Base64）
status: 'pending'|'processing'|'completed'|'error',
progress: number // 进度（0-100）
}
```
### API Key 管理
- API Key 通过 `.env` 文件或运行时设置
- 每个账户每月有 500 次免费压缩额度
- 验证 API Key 时，如果返回非 Credentials 错误，则认为 Key 格式正确
## Electron 配置
**窗口配置：**
- 尺寸：1200x800
- 无边框窗口（`frame: false`）
- 支持自定义标题栏和窗口控制按钮
- Node 集成启用（`nodeIntegration: true`）
- 上下文隔离禁用（`contextIsolation: false`）
**打包配置：**
- App ID：`cn.pandorastudio.tinypanda`
- 产品名称：TinyPanda
- Windows 目标：NSIS 安装程序
- 图标：`assets/icon.ico`
## 测试建议
**手动测试清单：**
1. API Key 验证功能
2. 单张图片压缩
3. 批量图片压缩
4. 拖拽上传功能
5. 压缩进度显示
6. 压缩前后大小对比
7. 单张下载功能
8. 打包下载功能
9. 窗口控制（最小化、最大化、关闭）
10. 错误处理（无效 API Key、无效文件等）
## 常见问题
**Q: 如何获取 Tinify API Key？**
A: 访问 https://tinify.cn/ 注册账号，免费账户每月有 500 次压缩额度。
**Q: 压缩失败怎么办？**
A: 检查 API Key 是否有效、网络连接是否正常、文件格式是否支持。
**Q: 如何修改 UI 样式？**
A: 主要样式在 `src/renderer/styles.css` 中，使用 CSS 变量定义主题色。
**Q: 如何添加新的图片格式支持？**
A: 修改 `src/main/index.js` 中的文件选择器过滤器，以及 Tinify 支持的格式。
## 贡献指南
如需修改代码，请遵循以下步骤：
1. 阅读现有代码，理解项目架构
2. 保持代码风格与现有代码一致
3. 测试修改后的功能
4. 确保打包后应用正常运行
## 许可证
MIT License

213
README.md Normal file
View File

@@ -0,0 +1,213 @@
# TinyPanda 🐼
专业的图片压缩工具，基于 Electron 和 Tinify API 构建。
![TinyPanda Logo](assets/icon.png)
## ✨ 功能特性
- ✅ **批量图片压缩** - 支持队列管理，可同时处理多张图片
- ✅ **实时进度显示** - 显示压缩进度和状态
- ✅ **压缩效果对比** - 显示压缩前后大小对比及节省比例
- ✅ **打包下载** - 支持将所有压缩后的图片打包为 ZIP 下载
- ✅ **拖拽上传** - 支持拖拽图片到上传区域
- ✅ **美观的现代化 UI** - Windows 11 Fluent Design 风格界面
- ✅ **自定义标题栏** - 无边框窗口设计，支持窗口控制
## 🖼️ 支持的图片格式
- JPG / JPEG
- PNG
- WebP
## 🚀 快速开始
### 环境要求
- Node.js >= 14.0.0
- npm >= 6.0.0
### 安装依赖
```bash
npm install
```
### 配置 API Key
1. 访问 [Tinify 官网](https://tinify.cn/) 注册账号
2. 获取您的 API Key
3. 在项目根目录创建 `.env` 文件，添加以下内容：
```env
TINIFY_API_KEY=your_api_key_here
```
### 运行应用
```bash
npm run dev
```
### 打包应用
```bash
# 打包为 Windows 应用
npm run build:win
# 打包为所有平台
npm run build
```
打包后的应用将输出到 `dist` 目录。
## 📖 使用说明
### 1. 验证 API Key
- 点击右上角设置按钮
- 输入您的 API Key
- 点击"验证"按钮确认有效性
- 点击"保存"保存配置
### 2. 添加图片
- **方法一**：点击"选择图片"按钮选择文件
- **方法二**：直接拖拽图片到上传区域
### 3. 压缩图片
- 添加图片后，点击"全部压缩"按钮
- 等待所有图片压缩完成
- 查看每张图片的压缩前后大小对比和节省比例
### 4. 下载结果
- **单张下载**：点击每张图片的"下载"按钮
- **批量下载**：点击"打包下载"按钮，选择保存位置
## 🛠️ 技术栈
- **Electron 32.0.0** - 桌面应用框架
- **Tinify API** - 专业图片压缩服务
- **JSZip 3.10.1** - 文件打包
- **Electron Store 8.2.0** - 配置持久化
- **原生 CSS** - Windows 11 Fluent Design 风格
## 📁 项目结构
```
TinyPanda/
├── src/
│ ├── main/
│ │ └── index.js # 主进程代码（窗口管理、IPC 通信）
│ └── renderer/
│ ├── index.html # 渲染进程 HTML
│ ├── styles.css # 样式文件
│ ├── app.js # 渲染进程逻辑
│ └── icons.js # 图标组件
├── assets/ # 资源文件（图标等）
├── .env # 环境变量配置
├── package.json # 项目配置
└── README.md # 项目说明
```
## 🔑 API Key 注意事项
- 每个账户每月有 **500 次**免费压缩额度
- API Key 请妥善保管，不要泄露
- 可以在 [Tinify 官网](https://tinify.cn/developers) 查看详细文档
- 压缩失败时请检查 API Key 是否有效、网络连接是否正常
## 🎨 UI 设计
TinyPanda 采用 **Windows 11 Fluent Design** 设计语言，提供：
- 流畅的动画效果
- 半透明毛玻璃效果
- 现代化的图标和按钮
- 响应式的布局设计
- 清晰的状态指示
## 📝 开发指南
### 代码风格
- 使用 ES6+ JavaScript 语法
- 主进程和渲染进程通过 IPC 通信
- 使用 `async/await` 处理异步操作
### IPC 通信协议
主进程提供以下 IPC 处理器：
- `get-api-key` - 获取当前 API Key
- `set-api-key` - 设置 API Key
- `validate-api-key` - 验证 API Key
- `compress-image` - 压缩单张图片
- `get-image-info` - 获取图片信息
- `save-compressed-image` - 保存压缩后的图片
- `create-zip` - 创建 ZIP 压缩包
- `select-save-directory` - 选择保存目录
- `select-files` - 选择文件
- `window-minimize/maximize/close` - 窗口控制
### 添加新功能
1. 在 `src/main/index.js` 中添加 IPC 处理器
2. 在 `src/renderer/app.js` 中调用相应的 IPC 方法
3. 在 `src/renderer/index.html` 中添加 UI 元素
4. 在 `src/renderer/styles.css` 中添加样式
## 🐛 常见问题
**Q: 压缩失败怎么办？**
A: 请检查以下项：
- API Key 是否有效
- 网络连接是否正常
- 文件格式是否支持（JPG、PNG、WebP）
- 查看控制台错误信息
**Q: 如何获取更多压缩额度？**
A: 访问 [Tinify 官网](https://tinify.cn/) 查看付费计划。
**Q: 可以离线使用吗？**
A: 不可以，压缩功能需要连接到 Tinify API 服务器。
**Q: 压缩后的图片质量如何？**
A: Tinify 使用智能压缩算法，在保持视觉质量的同时最大化压缩率，通常可以减少 50-80% 的文件大小。
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
## 📄 许可证
MIT License - 详见 [LICENSE](LICENSE) 文件
## 👥 作者
**Pandora Studio**
- 项目主页: https://git.pandorastudio.cn/product/TinyPanda.git
- 问题反馈: [Issues](https://git.pandorastudio.cn/product/TinyPanda.git/issues)
## 🙏 致谢
- [Electron](https://www.electronjs.org/) - 跨平台桌面应用框架
- [Tinify](https://tinify.cn/) - 专业图片压缩服务
- [JSZip](https://stuk.github.io/jszip/) - JavaScript ZIP 库
---
⭐ 如果这个项目对你有帮助，请给它一个 Star！