refactor: 重构纹理图集工具，实现浏览器端实时处理
将合图处理从服务端迁移到浏览器端，使用 Web Worker 实现高性能打包算法，新增三栏布局界面和精灵动画预览功能 - 新增 atlasStore 状态管理，实现文件、配置、结果的统一管理 - 新增 atlas-packer 打包算法库（MaxRects/Shelf），支持浏览器端快速合图 - 新增 atlas-worker Web Worker，实现异步打包处理避免阻塞 UI - 新增三栏布局组件：FileListPanel、CanvasPreview、AtlasConfigPanel - 新增 AnimationPreviewDialog 支持精灵动画帧预览和帧率控制 - 优化所有工具页面的响应式布局和交互体验 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
310
.codebuddy/plans/texture-atlas-browser-upgrade_c5a9c6ec.md
Normal file
310
.codebuddy/plans/texture-atlas-browser-upgrade_c5a9c6ec.md
Normal file
@@ -0,0 +1,310 @@
|
||||
---
|
||||
name: texture-atlas-browser-upgrade
|
||||
overview: 重构合图工具页面，实现三栏布局（左侧文件列表、中间Canvas实时预览、右侧参数配置），支持文件夹拖拽上传，使用 Web Worker 在浏览器端完成合图处理，并新增精灵动画预览弹窗功能。
|
||||
design:
|
||||
architecture:
|
||||
framework: react
|
||||
styleKeywords:
|
||||
- Professional Tool
|
||||
- Dark Theme
|
||||
- Three-Column Layout
|
||||
- Glassmorphism Panels
|
||||
- Minimal Borders
|
||||
fontSystem:
|
||||
fontFamily: PingFang SC
|
||||
heading:
|
||||
size: 18px
|
||||
weight: 600
|
||||
subheading:
|
||||
size: 14px
|
||||
weight: 500
|
||||
body:
|
||||
size: 13px
|
||||
weight: 400
|
||||
colorSystem:
|
||||
primary:
|
||||
- "#3B82F6"
|
||||
- "#2563EB"
|
||||
- "#1D4ED8"
|
||||
background:
|
||||
- "#0A0A0B"
|
||||
- "#18181B"
|
||||
- "#27272A"
|
||||
text:
|
||||
- "#FAFAFA"
|
||||
- "#A1A1AA"
|
||||
- "#71717A"
|
||||
functional:
|
||||
- "#22C55E"
|
||||
- "#EF4444"
|
||||
- "#F59E0B"
|
||||
todos:
|
||||
- id: atlas-store
|
||||
content: 创建atlasStore状态管理，定义精灵列表、配置、结果等状态及actions
|
||||
status: completed
|
||||
- id: browser-packer
|
||||
content: 使用 [skill:frontend-patterns] 迁移打包算法到浏览器端，创建atlas-packer.ts实现MaxRects和Shelf算法
|
||||
status: completed
|
||||
- id: web-worker
|
||||
content: 创建atlas-worker.ts，实现Web Worker打包处理和消息通信协议
|
||||
status: completed
|
||||
dependencies:
|
||||
- browser-packer
|
||||
- id: file-list-panel
|
||||
content: 使用 [skill:frontend-design] 开发左侧FileListPanel组件，支持文件夹拖拽上传和文件列表展示
|
||||
status: completed
|
||||
dependencies:
|
||||
- atlas-store
|
||||
- id: canvas-preview
|
||||
content: 使用 [skill:frontend-design] 开发中间CanvasPreview组件，实现实时渲染、缩放平移功能
|
||||
status: completed
|
||||
dependencies:
|
||||
- atlas-store
|
||||
- web-worker
|
||||
- id: animation-dialog
|
||||
content: 使用 [skill:frontend-design] 开发AnimationPreviewDialog组件，实现精灵动画帧播放和帧率控制
|
||||
status: completed
|
||||
dependencies:
|
||||
- canvas-preview
|
||||
- id: page-integration
|
||||
content: 使用 [skill:vercel-react-best-practices] 重构texture-atlas/page.tsx，整合三栏布局和所有功能组件
|
||||
status: completed
|
||||
dependencies:
|
||||
- file-list-panel
|
||||
- canvas-preview
|
||||
- animation-dialog
|
||||
---
|
||||
|
||||
## 产品概述
|
||||
|
||||
重构合图工具页面，从传统的两栏布局升级为三栏专业工作台布局。左侧文件列表面板显示上传的精灵图文件，中间Canvas实时预览合图结果，右侧参数配置面板调整合图参数。核心目标是将服务端处理迁移到浏览器端，使用 Web Worker 实现无阻塞的合图算法处理。
|
||||
|
||||
## 核心功能
|
||||
|
||||
1. **三栏工作台布局**：左侧文件树/列表、中间Canvas预览、右侧参数配置，支持面板宽度调整
|
||||
2. **文件夹拖拽上传**：支持 webkitdirectory 单层文件夹上传，图片平铺显示并按文件名排序
|
||||
3. **实时Canvas预览**：参数变更时自动触发合图计算，Canvas实时渲染结果，支持缩放和平移
|
||||
4. **Web Worker浏览器端处理**：将 MaxRects 和 Shelf 打包算法迁移到 Web Worker，实现非阻塞处理
|
||||
5. **精灵动画预览弹窗**：支持选择精灵帧按顺序播放动画，可调节帧率(FPS)，循环播放
|
||||
6. **导出下载**：支持导出合图图片和元数据文件(Cocos2d plist、Cocos Creator JSON、通用JSON)
|
||||
|
||||
## 技术栈
|
||||
|
||||
- 框架：Next.js 15 + React 19 + TypeScript
|
||||
- 样式：Tailwind CSS + CSS Variables
|
||||
- UI组件：Radix UI (Dialog已有) + Framer Motion
|
||||
- 状态管理：Zustand (扩展现有 uploadStore)
|
||||
- 国际化：现有 i18n 系统 (en.json / zh.json)
|
||||
- 图像处理：Canvas API + Web Worker + OffscreenCanvas
|
||||
|
||||
## 技术架构
|
||||
|
||||
### 系统架构
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph UI Layer
|
||||
A[FileListPanel] --> B[AtlasStore]
|
||||
C[CanvasPreview] --> B
|
||||
D[ConfigPanel] --> B
|
||||
E[AnimationDialog] --> B
|
||||
end
|
||||
|
||||
subgraph Processing Layer
|
||||
B --> F[Web Worker]
|
||||
F --> G[MaxRects Algorithm]
|
||||
F --> H[Shelf Algorithm]
|
||||
F --> I[Canvas Composite]
|
||||
end
|
||||
|
||||
subgraph Export Layer
|
||||
B --> J[Plist Exporter]
|
||||
B --> K[JSON Exporter]
|
||||
B --> L[Image Download]
|
||||
end
|
||||
```
|
||||
|
||||
### 模块划分
|
||||
|
||||
- **UI模块**：三栏布局组件、文件列表面板、Canvas预览组件、动画预览弹窗
|
||||
- **状态模块**：扩展现有Zustand store，管理文件列表、合图配置、处理状态
|
||||
- **Worker模块**：浏览器端打包算法实现，处理图片合成
|
||||
- **导出模块**：复用现有导出格式逻辑，适配浏览器端
|
||||
|
||||
### 数据流
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[文件夹拖拽上传] --> B[解析图片文件]
|
||||
B --> C[加载为ImageBitmap]
|
||||
C --> D[存入Store]
|
||||
D --> E[触发Worker处理]
|
||||
E --> F[执行打包算法]
|
||||
F --> G[返回布局数据]
|
||||
G --> H[Canvas渲染预览]
|
||||
H --> I[用户调整参数]
|
||||
I --> E
|
||||
```
|
||||
|
||||
## 实现细节
|
||||
|
||||
### 核心目录结构
|
||||
|
||||
```
|
||||
src/
|
||||
├── app/(dashboard)/tools/texture-atlas/
|
||||
│ └── page.tsx # 重构：三栏布局主页面
|
||||
├── components/tools/
|
||||
│ ├── atlas/
|
||||
│ │ ├── FileListPanel.tsx # 新增：左侧文件列表面板
|
||||
│ │ ├── CanvasPreview.tsx # 新增：中间Canvas预览组件
|
||||
│ │ ├── AtlasConfigPanel.tsx # 新增：右侧配置面板(基于ConfigPanel)
|
||||
│ │ └── AnimationPreviewDialog.tsx # 新增：动画预览弹窗
|
||||
│ └── FileUploader.tsx # 修改：支持文件夹上传
|
||||
├── lib/
|
||||
│ ├── atlas-worker.ts # 新增：Web Worker主文件
|
||||
│ ├── atlas-packer.ts # 新增：浏览器端打包算法(从texture-atlas.ts迁移)
|
||||
│ └── atlas-exporter.ts # 新增：导出格式生成器
|
||||
├── store/
|
||||
│ └── atlasStore.ts # 新增：合图专用状态管理
|
||||
└── types/
|
||||
└── index.ts # 修改：添加浏览器端类型定义
|
||||
```
|
||||
|
||||
### 关键代码结构
|
||||
|
||||
**浏览器端精灵类型定义**：用于存储加载的图片及其元信息，使用 ImageBitmap 代替 Buffer 以适配浏览器环境。
|
||||
|
||||
```typescript
|
||||
// 浏览器端精灵类型
|
||||
interface BrowserSprite {
|
||||
id: string;
|
||||
name: string;
|
||||
width: number;
|
||||
height: number;
|
||||
image: ImageBitmap;
|
||||
}
|
||||
|
||||
// 合图Store状态
|
||||
interface AtlasState {
|
||||
sprites: BrowserSprite[];
|
||||
config: TextureAtlasConfig;
|
||||
result: AtlasResult | null;
|
||||
isProcessing: boolean;
|
||||
previewScale: number;
|
||||
}
|
||||
```
|
||||
|
||||
**Web Worker消息协议**：定义Worker与主线程之间的通信格式，支持打包计算和进度回调。
|
||||
|
||||
```typescript
|
||||
// Worker消息协议
|
||||
interface WorkerMessage {
|
||||
type: 'pack' | 'cancel';
|
||||
sprites: { id: string; width: number; height: number }[];
|
||||
config: TextureAtlasConfig;
|
||||
}
|
||||
|
||||
interface WorkerResult {
|
||||
type: 'result' | 'progress' | 'error';
|
||||
placements?: Map<string, AtlasRect>;
|
||||
progress?: number;
|
||||
error?: string;
|
||||
}
|
||||
```
|
||||
|
||||
### 技术实现要点
|
||||
|
||||
1. **文件夹上传**
|
||||
|
||||
- 使用 `webkitdirectory` 属性支持文件夹选择
|
||||
- 过滤非图片文件，按文件名自然排序
|
||||
- 使用 `createImageBitmap` 异步加载图片
|
||||
|
||||
2. **Web Worker处理**
|
||||
|
||||
- 将 MaxRects 和 Shelf 算法迁移到 Worker
|
||||
- 仅传递尺寸数据到 Worker，图片保留在主线程
|
||||
- Worker 返回布局坐标，主线程执行 Canvas 合成
|
||||
|
||||
3. **Canvas实时预览**
|
||||
|
||||
- 使用 Canvas 2D Context 渲染合图结果
|
||||
- 支持鼠标滚轮缩放和拖拽平移
|
||||
- 配置变更触发防抖重新计算
|
||||
|
||||
4. **动画预览**
|
||||
|
||||
- 基于现有 Dialog 组件实现弹窗
|
||||
- 使用 requestAnimationFrame 控制帧率
|
||||
- 从合图结果中裁剪精灵帧序列播放
|
||||
|
||||
### 性能优化
|
||||
|
||||
- 使用防抖处理配置变更，避免频繁重计算
|
||||
- Worker 处理打包算法，不阻塞UI线程
|
||||
- ImageBitmap 高效图片加载和渲染
|
||||
- Canvas缓存合图结果，缩放时仅变换视图
|
||||
|
||||
## 设计风格
|
||||
|
||||
采用专业工具型界面设计，三栏工作台布局参考主流图形编辑软件(如TexturePacker、Figma)。整体风格延续项目现有的暗色主题设计，使用玻璃态面板分隔各功能区域。
|
||||
|
||||
## 页面规划
|
||||
|
||||
### 合图工作台页面 (单页面三栏布局)
|
||||
|
||||
**整体布局**
|
||||
|
||||
- 三栏横向布局，左中右比例约 240px : auto : 320px
|
||||
- 面板之间使用微妙的边框分隔，支持视觉层次区分
|
||||
- 中间预览区域占据主要空间，深色背景突出Canvas
|
||||
|
||||
**左侧文件列表面板**
|
||||
|
||||
- 顶部：文件夹名称显示、文件数量统计、清空按钮
|
||||
- 中部：文件列表区域，每项显示缩略图、文件名、尺寸信息
|
||||
- 底部：拖拽上传提示区域，支持点击选择文件夹
|
||||
- 支持列表项hover高亮，点击选中状态
|
||||
|
||||
**中间Canvas预览区域**
|
||||
|
||||
- 顶部工具栏：缩放比例显示、适应窗口按钮、动画预览按钮
|
||||
- 主体：深色棋盘格背景，Canvas居中显示合图结果
|
||||
- 支持鼠标滚轮缩放(10%-400%)、拖拽平移
|
||||
- 空状态：显示拖拽上传引导图标和文字
|
||||
|
||||
**右侧参数配置面板**
|
||||
|
||||
- 复用现有ConfigPanel组件样式
|
||||
- 分组展示：尺寸设置、布局设置、输出设置
|
||||
- 底部：生成按钮、下载按钮组
|
||||
|
||||
**动画预览弹窗**
|
||||
|
||||
- 居中弹窗，尺寸 640x480
|
||||
- 顶部：标题、关闭按钮
|
||||
- 中部：Canvas播放区域，深色背景
|
||||
- 底部：播放/暂停按钮、帧率滑块(1-60fps)、当前帧/总帧数显示
|
||||
|
||||
## Agent Extensions
|
||||
|
||||
### Skill
|
||||
|
||||
- **frontend-design**
|
||||
- 用途：设计三栏工作台布局、Canvas预览区域、动画预览弹窗等UI界面
|
||||
- 预期结果：生成专业、美观的合图工具界面，符合现有项目设计风格
|
||||
|
||||
- **frontend-patterns**
|
||||
- 用途：实现Web Worker通信、Canvas渲染、状态管理等前端模式
|
||||
- 预期结果：代码结构清晰，性能优化到位，符合React最佳实践
|
||||
|
||||
- **vercel-react-best-practices**
|
||||
- 用途：优化React组件性能，处理大量图片文件时的渲染优化
|
||||
- 预期结果：组件渲染高效，避免不必要的重渲染
|
||||
|
||||
### SubAgent
|
||||
|
||||
- **code-explorer**
|
||||
- 用途：在实现过程中探索现有组件复用、类型定义、国际化键值等
|
||||
- 预期结果：充分复用现有代码，保持项目一致性
|
||||
Reference in New Issue
Block a user