405 lines
14 KiB
Markdown
405 lines
14 KiB
Markdown
# 网页粒子系统 · 阶段九
|
||
|
||
> 阶段定位：**撤回与快捷键、编辑器配置持久化、可复用预设体系定版**
|
||
> 完成日期：2026-08-30
|
||
> 工程目录：`/Users/tianmokeji/Desktop/SpineParticle`
|
||
> 技术栈：Vue 3 + TypeScript + Pinia + PixiJS 7 + Spine Runtime 4.2 + Vite
|
||
|
||
---
|
||
|
||
## 一、阶段结论
|
||
|
||
阶段九在阶段八场景编辑、Spine 骨骼跟随和对象复制能力的基础上，补齐了编辑器日常使用所需的撤回、快捷键、工程保存、工程加载和预设加载流程。
|
||
|
||
编辑器现在可以把粒子系统、碰撞体、路径、Spine、系统设置、画布视图和动画归属等数据保存为可移植 JSON，并能把 Spine 骨架、Atlas 与多张纹理一并内嵌。配置重新加载后不需要再次选择 Spine 原始文件，画布、动画列表和骨骼树可以直接恢复。
|
||
|
||
本阶段主要完成：
|
||
|
||
1. 实现默认 20 步、最大 200 步的撤回历史；
|
||
2. 在系统设置中增加最大撤回次数设置；
|
||
3. 支持 `Ctrl/Cmd + Z` 撤回；
|
||
4. 增加画布工具、时间轴和保存配置快捷键；
|
||
5. 实现完整编辑器配置 JSON 下载保存；
|
||
6. 实现本地 JSON 配置加载和数据恢复；
|
||
7. 将 Spine 原始资源以内嵌 Data URL 形式纳入配置；
|
||
8. 修复 Spine 配置恢复后的运行时资源注册和渲染；
|
||
9. 实现 `public/Preset/` 预设目录与自动索引；
|
||
10. 实现预设列表、空状态和一键加载；
|
||
11. 建立纯粒子、路径、碰撞体、Spine 和空场景测试预设；
|
||
12. 修复包含 `+` 的预设文件名无法通过开发服务器读取的问题；
|
||
13. 为预设加载错误增加文件命名检查提示；
|
||
14. 修复同一配置第二次加载后停在第 0 帧的问题；
|
||
15. 完成普通配置和含 Spine 配置的保存—加载往返验证。
|
||
|
||
---
|
||
|
||
## 二、撤回功能
|
||
|
||
### 2.1 历史模型
|
||
|
||
编辑器通过快照记录可撤回数据。默认保留 20 步，用户可以在系统设置中修改，允许范围为 1～200 步。
|
||
|
||
快照覆盖：
|
||
|
||
- 全部粒子系统及其面板参数；
|
||
- 全部碰撞体；
|
||
- 全部路径与路径点；
|
||
- 全部 Spine 场景对象；
|
||
- 所属动画列表；
|
||
- 除撤回上限自身以外的系统设置；
|
||
- 对象显隐、背景图数据及背景偏移和透明度。
|
||
|
||
以下内容不作为普通撤回快照保存：
|
||
|
||
- 粒子逐帧录制缓存；
|
||
- PixiJS `Texture` 实例；
|
||
- 拖尾运行时纹理实例；
|
||
- 当前时间轴帧和正在播放状态；
|
||
- 撤回上限本身。
|
||
|
||
这些数据属于运行时缓存或撤回系统自身配置，恢复快照后由编辑器重新计算或重建。
|
||
|
||
### 2.2 操作合并
|
||
|
||
参数连续拖动或连续输入不会为每个微小变化创建独立历史。编辑器在最后一次变化后等待约 250ms，再把连续变化合并为一步操作。
|
||
|
||
该设计适用于：
|
||
|
||
- 滑块拖动；
|
||
- 数值连续输入；
|
||
- 曲线调整；
|
||
- 场景对象变换；
|
||
- 背景图偏移和透明度调整。
|
||
|
||
### 2.3 Spine 资源安全
|
||
|
||
Spine 场景对象的可序列化属性保存在快照中，已解析的 SkeletonData 和纹理通过资源注册表引用计数保留。
|
||
|
||
撤回删除、复制或资源替换操作时：
|
||
|
||
- 快照仍引用的 Spine 资源不会被提前销毁；
|
||
- 恢复快照时重新注册对应 Spine ID 的运行时资源；
|
||
- 超出撤回上限的旧快照会释放自己持有的资源引用；
|
||
- 粒子录制缓存清空并重新生成。
|
||
|
||
### 2.4 撤回后的状态修复
|
||
|
||
执行撤回后会：
|
||
|
||
1. 恢复场景对象和设置；
|
||
2. 修复当前选择，避免选择已不存在的对象；
|
||
3. 恢复粒子系统所属动画；
|
||
4. 清空旧录制帧；
|
||
5. 重新计算时间轴总长度；
|
||
6. 更新撤回按钮的剩余步数和可用状态。
|
||
|
||
当前阶段只实现“撤回”，尚未实现“重做”。
|
||
|
||
---
|
||
|
||
## 三、快捷键
|
||
|
||
### 3.1 快捷键表
|
||
|
||
| 快捷键 | 作用 | 生效范围 |
|
||
|---|---|---|
|
||
| `Ctrl/Cmd + Z` | 撤回上一步 | 全局 |
|
||
| `Ctrl/Cmd + S` | 下载保存当前编辑器配置 | 全局 |
|
||
| `Q` | 切换为画布拖动模式 | 画布已选中 |
|
||
| `W` | 切换位移工具 | 画布已选中 |
|
||
| `E` | 切换旋转工具 | 画布已选中 |
|
||
| `R` | 切换缩放工具 | 画布已选中 |
|
||
| `D` | 播放/暂停时间轴 | 全局非输入状态 |
|
||
| `S` | 回到时间轴第 0 帧 | 全局非输入状态 |
|
||
|
||
### 3.2 浏览器快捷键覆盖
|
||
|
||
`Ctrl/Cmd + S` 和 `Ctrl/Cmd + Z` 会阻止浏览器默认行为，分别交给编辑器保存和撤回，不再弹出浏览器网页保存或执行浏览器输入历史撤销。
|
||
|
||
### 3.3 输入控件保护
|
||
|
||
当焦点位于以下控件时，普通字母快捷键不会触发：
|
||
|
||
- `input`；
|
||
- `textarea`；
|
||
- `select`；
|
||
- `contenteditable` 内容。
|
||
|
||
因此输入名称、搜索骨骼或编辑参数时，可以正常键入 `q/w/e/r/d/s`。带 `Ctrl/Cmd` 的保存与撤回仍按编辑器全局快捷键处理。
|
||
|
||
---
|
||
|
||
## 四、编辑器配置保存
|
||
|
||
### 4.1 保存入口
|
||
|
||
场景对象面板上方增加：
|
||
|
||
- `保存配置`；
|
||
- `加载配置`；
|
||
- `选择预设`。
|
||
|
||
点击“保存配置”或按 `Ctrl/Cmd + S`，浏览器会下载：
|
||
|
||
```text
|
||
SpineParticle-YYYYMMDD-HHMMSS.json
|
||
```
|
||
|
||
### 4.2 文件格式
|
||
|
||
当前格式标识与版本：
|
||
|
||
```text
|
||
format: SpineParticle.EditorConfig
|
||
version: 1
|
||
```
|
||
|
||
顶层数据结构：
|
||
|
||
```text
|
||
editor 画布缩放与平移
|
||
settings 系统设置、背景图及撤回上限
|
||
timeline FPS、循环状态和所属动画列表
|
||
selection 当前场景对象类型与 ID
|
||
scene 粒子、碰撞体、路径和 Spine 数组
|
||
savedAt 保存时间
|
||
```
|
||
|
||
### 4.3 粒子与图片资源
|
||
|
||
粒子系统保存全部可编辑参数，包括：
|
||
|
||
- 发射模式、持续时间和延迟；
|
||
- 发射器形状和根变换；
|
||
- 生命周期、速度、缩放、旋转与曲线；
|
||
- 颜色、透明度、混合模式；
|
||
- 修改器；
|
||
- 碰撞、路径和骨骼跟随；
|
||
- 图片资源与拖尾资源；
|
||
- 对象显隐和所属动画。
|
||
|
||
PixiJS 纹理实例和粒子逐帧缓存不会写入 JSON。图片资源通过自身的预览 URL 或 Data URL 保存，配置加载时重新创建纹理。
|
||
|
||
### 4.4 Spine 原始资源内嵌
|
||
|
||
Spine 对象除属性、动画选择和骨骼元数据外，还保存原始资源副本：
|
||
|
||
```text
|
||
sourceBundle.skeleton
|
||
sourceBundle.atlas
|
||
sourceBundle.textures[]
|
||
```
|
||
|
||
每个资源同时保存原文件名和 Data URL。恢复时重新创建同名 `File`：
|
||
|
||
- JSON 使用原 JSON 文件名；
|
||
- SKEL 使用原二进制文件名；
|
||
- Atlas 保留原 Atlas 文件名和内容；
|
||
- 纹理保留 Atlas 中引用的准确文件名。
|
||
|
||
保持文件名一致是 Atlas 再次匹配多张纹理的关键。Data URL 只是文件内容载体，不会替代资源之间的文件名引用关系。
|
||
|
||
Spine 面板在首次加载成功后异步生成 `sourceBundle`，避免内嵌资源转换干扰当前画布中的实时 Spine 解析结果。
|
||
|
||
---
|
||
|
||
## 五、编辑器配置加载
|
||
|
||
### 5.1 校验
|
||
|
||
加载本地文件时只接受 `.json`，并依次检查：
|
||
|
||
1. 是否为有效 JSON；
|
||
2. `format` 是否为 `SpineParticle.EditorConfig`；
|
||
3. 配置版本是否为 1；
|
||
4. 场景是否包含粒子、碰撞体、路径和 Spine 数组。
|
||
|
||
失败时保持当前编辑器状态，并显示具体错误。
|
||
|
||
### 5.2 原子恢复流程
|
||
|
||
配置加载先在临时数据中完成资源准备：
|
||
|
||
1. 深度复制配置数据；
|
||
2. 补齐旧粒子参数默认值；
|
||
3. 重建粒子和拖尾纹理；
|
||
4. 还原 Spine 原始文件；
|
||
5. 解析骨架、Atlas 和多纹理；
|
||
6. 全部解析成功后再替换当前场景；
|
||
7. 注册新的 Spine 运行时资源；
|
||
8. 修复对象选择和所属动画；
|
||
9. 重新计算时间轴长度。
|
||
|
||
如果内嵌 Spine 资源解析失败，已临时创建的纹理会释放，不会把半完成场景覆盖到编辑器中。
|
||
|
||
### 5.3 Spine 运行时刷新
|
||
|
||
重复加载配置时，Spine 对象 ID 可能相同。加载流程会提升 `assetVersion`，确保运行时层识别为新资源并重新创建 Spine 显示对象，而不是继续使用旧实例。
|
||
|
||
资源加载完成后会恢复：
|
||
|
||
- Spine 画布渲染；
|
||
- 动画列表和动画时长；
|
||
- 当前选择的 Spine 动画；
|
||
- 骨骼层级树；
|
||
- 当前选中骨骼；
|
||
- 粒子系统保存的 Spine ID 与骨骼名称绑定。
|
||
|
||
### 5.4 加载后自动播放
|
||
|
||
配置和预设加载完成后统一执行：
|
||
|
||
```text
|
||
frame = 0
|
||
recorded = false
|
||
playing = true
|
||
```
|
||
|
||
因此首次加载和连续加载同一份配置都会从头自动播放，不再依赖场景深度监听是否检测到数据变化。
|
||
|
||
---
|
||
|
||
## 六、预设体系
|
||
|
||
### 6.1 预设目录
|
||
|
||
预设文件放置于：
|
||
|
||
```text
|
||
public/Preset/
|
||
```
|
||
|
||
每个预设都是与“保存配置”完全相同的 `SpineParticle.EditorConfig` JSON，因此预设和本地工程配置共用一套解析、校验和资源恢复流程。
|
||
|
||
### 6.2 自动索引
|
||
|
||
Vite 插件会扫描预设目录中的全部 `.json` 文件并自动生成：
|
||
|
||
```text
|
||
public/Preset/index.json
|
||
```
|
||
|
||
索引生成时：
|
||
|
||
- 排除 `index.json` 自身；
|
||
- 按中文文件名排序；
|
||
- 使用文件名去掉 `.json` 作为界面名称；
|
||
- 开发服务器监听文件新增和删除并刷新列表；
|
||
- 生产构建开始前重新生成索引。
|
||
|
||
目录中没有配置文件时，下拉框显示“无预设文件”并置灰。
|
||
|
||
### 6.3 当前预设
|
||
|
||
当前项目包含：
|
||
|
||
- `纯粒子.json`；
|
||
- `纯粒子-路径.json`；
|
||
- `纯粒子-碰撞.json`；
|
||
- `纯粒子-spine.json`；
|
||
- `空场景.json`；
|
||
- `默认粒子.json`。
|
||
|
||
带 Spine 的预设内嵌 `bingo.json`、`bingo.atlas`、`bingo.png` 和 `bingo_2.png`，加载后可直接显示 Spine、动画列表和骨骼树。
|
||
|
||
### 6.4 文件命名规则
|
||
|
||
阶段测试发现，文件名包含 `+` 时，经 URL 编码后开发服务器会返回应用 HTML，而不是目标 JSON，最终表现为“配置文件不是有效的 JSON”。
|
||
|
||
为确保开发环境和静态托管环境行为一致，组合预设统一使用连字符：
|
||
|
||
```text
|
||
推荐：纯粒子-路径.json
|
||
避免：纯粒子+路径.json
|
||
```
|
||
|
||
预设加载失败时，界面在原始错误后追加：
|
||
|
||
```text
|
||
请检查预设文件命名
|
||
```
|
||
|
||
---
|
||
|
||
## 七、代码结构
|
||
|
||
本阶段新增或重点调整：
|
||
|
||
| 文件 | 职责 |
|
||
|---|---|
|
||
| `src/editor/editorClone.ts` | 安全深度复制编辑器可序列化数据 |
|
||
| `src/editor/editorHistory.ts` | 撤回快照、合并、上限和 Spine 资源引用 |
|
||
| `src/editor/useEditorShortcuts.ts` | 全局快捷键、画布焦点和输入保护 |
|
||
| `src/editor/editorConfig.ts` | 配置创建、下载、校验、加载和资源恢复 |
|
||
| `src/spine/spineSourceBundle.ts` | Spine 原始文件 Data URL 内嵌与还原 |
|
||
| `src/spine/spineAssetRegistry.ts` | Spine 配置恢复和撤回所需的资源生命周期 |
|
||
| `src/views/ParticlePanel.vue` | 保存、加载、预设列表和结果提示 |
|
||
| `src/views/Stage.vue` | 快捷键接入、撤回按钮和加载后的运行时刷新 |
|
||
| `vite.config.ts` | 预设索引自动生成和 Spine 依赖去重 |
|
||
|
||
配置、历史与快捷键逻辑已从主画布和主属性面板中拆分，避免继续扩大单文件职责。
|
||
|
||
---
|
||
|
||
## 八、验证结果
|
||
|
||
已完成以下实际验证：
|
||
|
||
- `Ctrl/Cmd + S` 可以下载编辑器配置；
|
||
- 配置文件名按时间生成且 JSON 格式有效；
|
||
- 修改粒子名称后保存，再次修改并加载，名称恢复为保存值；
|
||
- 系统设置、背景图数据、画布视图和场景对象写入配置；
|
||
- 含 Spine 的配置保存后文件约 11MB，资源数据完整内嵌；
|
||
- 含 Spine 配置重新加载后，Spine 名称恢复；
|
||
- Spine 画布图像正常显示；
|
||
- 14 个 Spine 动画及“无”选项正常恢复；
|
||
- 骨骼层级树正常恢复；
|
||
- 页面未出现资源解析或渲染错误；
|
||
- `纯粒子.json` 加载成功；
|
||
- `纯粒子-路径.json` 加载成功，场景包含粒子与路径；
|
||
- `纯粒子-碰撞.json` 加载成功，场景包含粒子与碰撞体；
|
||
- `纯粒子-spine.json` 加载成功，场景包含粒子与 Spine；
|
||
- `空场景.json` 可以加载为零对象场景；
|
||
- `默认粒子.json` 加载成功；
|
||
- 同一 Spine 预设连续加载两次，两次都从第 0 帧自动播放；
|
||
- 第二次加载后帧数从 40 推进到 59，播放按钮保持“暂停”状态；
|
||
- 浏览器控制台无错误和警告；
|
||
- `npm run build` 生产构建通过。
|
||
|
||
构建仍存在 Vite 主产物超过 500kB 的提示，不影响功能和构建结果。
|
||
|
||
---
|
||
|
||
## 九、当前限制
|
||
|
||
1. 当前只支持单向撤回，尚未实现重做；
|
||
2. 撤回历史只存在于当前页面内存中，刷新页面后清空；
|
||
3. 撤回不保存当前播放帧、播放状态、画布选择和粒子录制缓存；
|
||
4. 配置格式当前为版本 1，尚未建立跨版本迁移器；
|
||
5. Spine 和本地图片使用 Data URL 内嵌，资源较大时配置文件体积明显增加；
|
||
6. 保存配置始终下载新文件，尚未提供覆盖保存、最近文件和自动保存；
|
||
7. 浏览器安全限制下无法记住原本地文件路径；
|
||
8. 预设依赖构建时生成的索引，纯静态部署后新增文件需要重新构建；
|
||
9. 预设命名目前通过规避 `+` 保证兼容，尚未建立完整的文件名字符校验；
|
||
10. 配置导入目前只接受 JSON，尚未支持 YAML；
|
||
11. 配置文件没有压缩，包含 Spine 多纹理时下载和解析成本较高；
|
||
12. 主包仍包含 Spine 运行时和主要编辑器模块，尚未动态拆包。
|
||
|
||
---
|
||
|
||
## 十、阶段十建议
|
||
|
||
1. 增加重做功能和 `Ctrl/Cmd + Shift + Z` 快捷键；
|
||
2. 增加配置格式迁移器，支持未来版本平滑升级；
|
||
3. 为预设文件名建立创建、校验和错误定位工具；
|
||
4. 提供自动保存、最近配置和页面异常恢复；
|
||
5. 支持压缩工程包，把 JSON 与 Spine、粒子图片资源拆分存储；
|
||
6. 增加配置导入前预览、差异对比和合并模式；
|
||
7. 为配置与预设建立自动化往返测试；
|
||
8. 对无效 ID、丢失骨骼、缺失纹理和旧字段提供迁移报告；
|
||
9. 增加工程名称、作者、备注和自定义元数据；
|
||
10. 开始设计正式导出结构，把所属动画、粒子系统和 Spine 骨骼绑定映射到导出数据；
|
||
11. 对 Spine 和编辑器主模块进行动态加载，降低初始包体积；
|
||
12. 增加配置资源大小统计和大文件保存提示。
|
||
|