--- 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; 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** - 用途：在实现过程中探索现有组件复用、类型定义、国际化键值等 - 预期结果：充分复用现有代码，保持项目一致性