动画组件

admin

1. 我将查看动画组件的代码来生成详细的使用文档。
   
2. Read file: 动画组件.js
   
3. 让我基于代码内容为您编写一个详细的使用文档：
   
4. 
   
5. # 动画组件使用文档
   
6. 
   
7. ## 1. 组件概述
   
8. 
   
9. 动画组件是一个用于播放序列帧动画的PIXI.js组件，支持多方向、多动作的动画播放控制。
   
10. 
    
11. ### 主要特性
    
12. - 支持2/4/5/8方向动画
    
13. - 支持动作(action)、方向(dir)、状态切换
    
14. - 支持播放速度调整和进度控制
    
15. - 支持动态资源加载和内存管理
    
16. - 支持动作级和全局的镜像配置
    
17. - 支持自定义锚点设置
    
18. - 支持偏移(x.txt)文件
    
19. 
    
20. ## 2. 基础使用
    
21. 
    
22. ### 创建实例
    
23. ```javascript
    
24. const anim = new 动画组件();
    
25. ```
    
26. 
    
27. ### 初始化
    
28. ```javascript
    
29. anim.初始化(x, y, {
    
30.     路径: 'assets/role/{action}_{dir}_{frame}.png',
    
31.     动作列表: {
    
32.         stand: { 帧数: 6, fps: 6 },
    
33.         run: { 帧数: 8, fps: 10 },
    
34.         attack: { 帧数: 6, fps: 8 }
    
35.     },
    
36.     方向数: 8
    
37. });
    
38. ```
    
39. 
    
40. ### 添加到场景
    
41. ```javascript
    
42. scene.addChild(anim.获取容器());
    
43. ```
    
44. 
    
45. ### 播放动画
    
46. ```javascript
    
47. anim.播放('stand', 2, true); // 动作名, 方向, 是否循环
    
48. ```
    
49. 
    
50. ## 3. 配置参数说明
    
51. 
    
52. ### 全局配置
    
53. ```javascript
    
54. {
    
55.     路径: 'assets/role/{action}_{dir}_{frame}.png', // 必填，支持{action} {dir} {frame}占位符
    
56.     动作列表: Object,                               // 必填，动作配置对象
    
57.     方向数: 2|4|5|8,                               // 可选，默认8
    
58.     格式: 'png|jpg|webp',                          // 可选，默认'png'
    
59.     起始帧: 0,                                     // 可选，默认0
    
60.     锚点像素X: 256,                                // 可选，默认256
    
61.     锚点像素Y: 256,                                // 可选，默认256
    
62.     mirrorPairs: [[0,4], [1,3]]                    // 可选，全局镜像配置
    
63. }
    
64. ```
    
65. 
    
66. ### 动作配置
    
67. ```javascript
    
68. {
    
69.     帧数: number,           // 必填，动作总帧数
    
70.     fps: number,            // 可选，默认10
    
71.     方向: number,           // 可选，覆盖全局方向数
    
72.     起始帧: number,         // 可选，覆盖全局起始帧
    
73.     anchor: {x: number, y: number}, // 可选，动作级锚点
    
74.     mirrorPairs: [[0,4], [1,3]]    // 可选，动作级镜像配置
    
75. }
    
76. ```
    
77. 
    
78. ## 4. API参考
    
79. 
    
80. ### 核心方法
    
81. 
    
82. #### 初始化(x, y, 配置)
    
83. - 参数：
    
84.   - x: number - X坐标
    
85.   - y: number - Y坐标
    
86.   - 配置: Object - 动画配置对象
    
87. - 返回：Promise<void>
    
88. 
    
89. #### 播放(动作名, 方向, 循环)
    
90. - 参数：
    
91.   - 动作名: string - 要播放的动作名称
    
92.   - 方向: number - 动画方向(0-7)
    
93.   - 循环: boolean - 是否循环播放
    
94. - 返回：void
    
95. 
    
96. #### 暂停()
    
97. 暂停当前动画播放
    
98. 
    
99. #### 继续()
    
100. 继续播放当前动画
     
101. 
     
102. #### 停止()
     
103. 停止动画播放并重置到第一帧
     
104. 
     
105. ### 状态控制
     
106. 
     
107. #### 设置速度(speed)
     
108. - 参数：speed: number - 播放速度倍率，1为正常速度
     
109. 
     
110. #### 设置进度(progress)
     
111. - 参数：progress: number - 0到1之间的进度值
     
112. 
     
113. #### 跳转到(frame)
     
114. - 参数：frame: number - 目标帧序号
     
115. 
     
116. ### 事件监听
     
117. 
     
118. #### on(事件名, 回调函数)
     
119. 添加事件监听器
     
120. ```javascript
     
121. anim.on('complete', () => console.log('动画播放完成'));
     
122. ```
     
123. 
     
124. #### off(事件名, 回调函数)
     
125. 移除事件监听器
     
126. 
     
127. #### once(事件名, 回调函数)
     
128. 添加一次性事件监听器
     
129. 
     
130. ### 支持的事件
     
131. - 'complete' - 动画播放完成
     
132. - 'loop' - 动画循环播放
     
133. - 'frame' - 帧更新
     
134. 
     
135. ## 5. 高级特性
     
136. 
     
137. ### 镜像配置
     
138. 支持两种级别的镜像配置：
     
139. 1. 全局镜像：在初始化配置中设置
     
140. 2. 动作级镜像：在具体动作配置中设置
     
141. ```javascript
     
142. {
     
143.     mirrorPairs: [[0,4], [1,3]], // 方向0镜像到4，方向1镜像到3
     
144. }
     
145. ```
     
146. 
     
147. ### 偏移支持
     
148. - 通过x.txt文件配置每帧的偏移量
     
149. - 格式：每行两个数字，分别表示x和y的偏移值
     
150. ```
     
151. 10 20
     
152. 15 25
     
153. 20 30
     
154. ```
     
155. 
     
156. ## 6. 注意事项
     
157. 
     
158. 1. 资源命名规范
     
159.    - 图片文件名必须符合路径模板格式
     
160.    - 偏移文件(x.txt)需要放在相同目录下
     
161. 
     
162. 2. 性能优化
     
163.    - 合理设置fps避免性能问题
     
164.    - 不使用时调用销毁()释放资源
     
165. 
     
166. 3. 方向说明
     
167.    - 8方向：0-7，从上开始顺时针
     
168.    - 5方向：自动镜像补全
     
169.    - 2/4方向：按需配置
     
170. 
     
171. 4. 内存管理
     
172.    - 组件会自动管理纹理资源
     
173.    - 使用销毁()方法清理资源
     
174. 
     
175. ## 7. 示例代码
     
176. 
     
177. ```javascript
     
178. // 创建并初始化动画组件
     
179. const anim = new 动画组件();
     
180. await anim.初始化(100, 200, {
     
181.     路径: 'assets/character/{action}_{dir}_{frame}.png',
     
182.     动作列表: {
     
183.         idle: {
     
184.             帧数: 8,
     
185.             fps: 10,
     
186.             anchor: {x: 256, y: 256},
     
187.             mirrorPairs: [[1,3]]
     
188.         },
     
189.         walk: {
     
190.             帧数: 8,
     
191.             fps: 12,
     
192.             方向: 4
     
193.         }
     
194.     },
     
195.     方向数: 8,
     
196.     锚点像素X: 256,
     
197.     锚点像素Y: 256
     
198. });
     
199. 
     
200. // 添加到场景
     
201. scene.addChild(anim.获取容器());
     
202. 
     
203. // 播放动画
     
204. anim.播放('idle', 0, true);
     
205. 
     
206. // 监听事件
     
207. anim.on('complete', () => {
     
208.     console.log('动画播放完成');
     
209. });
     
210. 
     
211. // 控制播放
     
212. anim.设置速度(1.5);
     
213. anim.暂停();
     
214. anim.继续();
     
215. ```
     
216. 
     
217. 这个文档涵盖了动画组件的所有主要功能和使用方法。如果您有任何具体的问题或需要更详细的说明，请随时询问。

复制代码

admin

让我检查代码中关于添加动作的API。
Ran tool
让我查看添加动作API的具体实现：
Read file: 动画组件.js
我为您补充添加动作API的文档说明：

## 4. API参考（补充）

### 动态添加动作

#### 添加动作(actionName, info)
在初始化后动态添加新的动作。

- 参数：
  - actionName: string - 动作名称
  - info: Object - 动作配置对象
    ```javascript
    {
        帧数: number,     // 必填，动作的总帧数
        fps: number,      // 可选，默认10，动画播放速率
        起始帧: number,   // 可选，默认使用全局配置的起始帧
        方向: number,     // 可选，覆盖全局方向数
        anchor: {         // 可选，动作级锚点设置
            x: number,    // 锚点X坐标（像素）
            y: number     // 锚点Y坐标（像素）
        },
        mirrorPairs: Array // 可选，动作级镜像配置，如 [[0,4], [1,3]]
    }
    ```
- 返回：Promise<void>
- 事件：
  - '动作已加载' - 当动作加载完成时触发
  - '加载错误' - 当加载过程中发生错误时触发

示例：
```javascript
// 添加新动作
await anim.添加动作('攻击', {
    帧数: 30,
    fps: 12,
    起始帧: 97,
    方向: 8,
    anchor: { x: 256, y: 256 },
    mirrorPairs: [[1,3], [2,6]]
});

// 监听加载完成
anim.on('动作已加载', (actionName) => {
    console.log(`动作 ${actionName} 加载完成`);
});
```

注意事项：
1. 动作名称不能重复，如果添加已存在的动作名会被忽略
2. 帧数参数是必须的，其他参数都是可选的
3. 动作级配置（方向数、锚点等）会覆盖全局配置
4. 资源路径使用初始化时配置的路径模板
5. 支持动态加载偏移文件(x.txt)
6. 添加动作是异步操作，建议等待加载完成后再使用

这个API允许您在初始化动画组件后，根据需要动态添加新的动作，非常适合按需加载资源的场景。每个新添加的动作都可以有自己的配置参数，包括帧数、播放速度、方向数、锚点位置等，使用方式与初始化时的动作配置完全一致。