mini-game-ai/.codebuddy/plans/texture-atlas-browser-upgrade_c5a9c6ec.md

name, overview, design, todos

name	overview	design	todos
texture-atlas-browser-upgrade	重构合图工具页面，实现三栏布局（左侧文件列表、中间Canvas实时预览、右侧参数配置），支持文件夹拖拽上传，使用 Web Worker 在浏览器端完成合图处理，并新增精灵动画预览弹窗功能。	architecture styleKeywords fontSystem colorSystem framework react Professional Tool Dark Theme Three-Column Layout Glassmorphism Panels Minimal Borders fontFamily heading subheading body PingFang SC size weight 18px 600 size weight 14px 500 size weight 13px 400 primary background text functional #3B82F6 #2563EB #1D4ED8 #0A0A0B #18181B #27272A #FAFAFA #A1A1AA #71717A #22C55E #EF4444 #F59E0B	id content status atlas-store 创建atlasStore状态管理，定义精灵列表、配置、结果等状态及actions completed id content status browser-packer 使用 [skill:frontend-patterns] 迁移打包算法到浏览器端，创建atlas-packer.ts实现MaxRects和Shelf算法 completed id content status dependencies web-worker 创建atlas-worker.ts，实现Web Worker打包处理和消息通信协议 completed browser-packer id content status dependencies file-list-panel 使用 [skill:frontend-design] 开发左侧FileListPanel组件，支持文件夹拖拽上传和文件列表展示 completed atlas-store id content status dependencies canvas-preview 使用 [skill:frontend-design] 开发中间CanvasPreview组件，实现实时渲染、缩放平移功能 completed atlas-store web-worker id content status dependencies animation-dialog 使用 [skill:frontend-design] 开发AnimationPreviewDialog组件，实现精灵动画帧播放和帧率控制 completed canvas-preview id content status dependencies page-integration 使用 [skill:vercel-react-best-practices] 重构texture-atlas/page.tsx，整合三栏布局和所有功能组件 completed 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

技术架构

系统架构

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模块：浏览器端打包算法实现，处理图片合成
• 导出模块：复用现有导出格式逻辑，适配浏览器端

数据流

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 以适配浏览器环境。

// 浏览器端精灵类型
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与主线程之间的通信格式，支持打包计算和进度回调。

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