product/TinyPanda

Fork 0

Files

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

2026-01-30 14:01:32 +08:00

6.4 KiB

Raw Permalink Blame History

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

核心功能

批量图片压缩 - 支持队列管理，可同时处理多张图片
实时进度显示 - 显示压缩进度和状态
压缩效果对比 - 显示压缩前后大小对比及节省比例
打包下载 - 支持将所有压缩后的图片打包为 ZIP 下载
拖拽上传 - 支持拖拽图片到上传区域
自定义标题栏 - 无边框窗口，支持最小化、最大化、关闭

支持的图片格式： 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                 # 项目简要说明

构建和运行

安装依赖

npm install

开发模式运行

npm run dev

打包应用

# 仅打包 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"）

队列项结构：

{
  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

测试建议

手动测试清单：

API Key 验证功能
单张图片压缩
批量图片压缩
拖拽上传功能
压缩进度显示
压缩前后大小对比
单张下载功能
打包下载功能
窗口控制（最小化、最大化、关闭）
错误处理（无效 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 支持的格式。

贡献指南

如需修改代码，请遵循以下步骤：

阅读现有代码，理解项目架构
保持代码风格与现有代码一致
测试修改后的功能
确保打包后应用正常运行

许可证

MIT License

6.4 KiB Raw Permalink Blame History Unescape Escape