@yqg/aminofx-css-kit 1.0.0

package/README.md

@@ -0,0 +1,747 @@
+# 动画播放器 SDK
+
+一个强大、灵活的Web动画播放器SDK，支持基于关键帧的复杂动画制作和播放。
+
+## 🚀 功能特性
+
+- **关键帧动画**: 基于时间轴的关键帧动画系统
+- **模板引擎**: 支持`{{variable}}`语法的动态内容渲染
+- **事件系统**: 完整的动画生命周期和元素交互事件支持
+- **CSS变换**: 支持位移、缩放、旋转、透明度等动画属性
+- **缓动函数**: 内置多种缓动函数，包括弹性和弹跳效果
+- **状态管理**: 完整的播放、暂停、停止、跳转控制
+- **自适应时长**: 根据关键帧自动计算动画时长
+- **类型安全**: 完整的TypeScript类型定义
+
+## 📦 安装
+
+```bash
+npm install @yqg-max/click-gate
+```
+
+## 🏗️ 核心接口
+
+### IAnimationElement
+
+动画元素配置接口，定义了动画中每个元素的基本信息和样式。
+
+```typescript
+interface IAnimationElement {
+  /** 元素唯一标识符 */
+  id: string;
+  /** 元素关联的数据，用于模板渲染 */
+  data?: Record<string, any>;
+  /** 元素内容配置 */
+  content: {
+    /** HTML内容模板，支持 {{variable}} 语法 */
+    html?: string;
+    /** 自定义CSS样式 */
+    style?: Record<string, string | number>;
+  };
+}
+```
+
+### IPropertieCss
+
+CSS属性接口，定义了动画中常用的CSS变换属性。
+
+```typescript
+interface IPropertieCss {
+  /** X轴位置 (px) */
+  x: number;
+  /** Y轴位置 (px) */
+  y: number;
+  /** 宽度 (px) */
+  width: number;
+  /** 高度 (px) */
+  height: number;
+  /** 旋转角度 (deg) */
+  rotation: number;
+  /** 透明度 (0-1) */
+  opacity: number;
+  /** 缩放比例 */
+  scale: number;
+}
+```
+
+### IAnimationKeyframe
+
+动画关键帧接口，定义了某个时间点上元素的属性状态。
+
+```typescript
+interface IAnimationKeyframe {
+  /** 关键帧唯一标识符 */
+  id: string;
+  /** 关联的元素ID */
+  elementId: string;
+  /** 时间点 (毫秒) */
+  time: number;
+  /** 该时间点的CSS属性值 */
+  properties: Partial<IPropertieCss> & Record<string, any>;
+}
+```
+
+### IAnimationSchema
+
+动画配置模式接口，定义了完整的动画配置。
+
+```typescript
+interface IAnimationSchema {
+  /** 动画中的所有元素 */
+  elements: IAnimationElement[];
+  /** 动画中的所有关键帧 */
+  keyframes: IAnimationKeyframe[];
+  /** 全局数据，用于模板渲染 */
+  data?: Record<string, any>;
+}
+```
+
+### IAnimationInfo
+
+动画信息接口，提供动画的统计信息。
+
+```typescript
+interface IAnimationInfo {
+  /** 总时长 (毫秒) */
+  totalDuration: number;
+  /** 最大关键帧时间 */
+  maxKeyframeTime: number;
+  /** 关键帧数量 */
+  keyframeCount: number;
+  /** 元素数量 */
+  elementCount: number;
+  /** 是否自动计算时长 */
+  isAutoCalculated: boolean;
+}
+```
+
+## 🎭 类型定义
+
+### EasingFunction
+
+动画缓动函数类型。
+
+```typescript
+type EasingFunction =
+  | 'linear' // 线性
+  | 'ease-in' // 缓慢开始
+  | 'ease-out' // 缓慢结束
+  | 'ease-in-out' // 缓慢开始和结束
+  | 'ease-in-cubic' // 三次方缓入
+  | 'ease-out-cubic' // 三次方缓出
+  | 'bounce-out' // 弹跳结束
+  | 'elastic-out'; // 弹性结束
+```
+
+### AnimationState
+
+动画状态类型。
+
+```typescript
+type AnimationState = 'idle' | 'playing' | 'paused' | 'completed';
+```
+
+### ElementEventCallback
+
+事件监听器回调函数类型。
+
+```typescript
+type ElementEventCallback = (event: Event, element: HTMLElement) => void;
+```
+
+## 🎨 核心类
+
+### AnimationPlayer
+
+动画播放器主类，负责管理和控制动画的播放。
+
+#### 构造函数
+
+```typescript
+constructor(container: HTMLElement, schema: IAnimationSchema)
+```
+
+#### 播放控制方法
+
+| 方法                 | 描述                     | 参数                   | 返回值 |
+| -------------------- | ------------------------ | ---------------------- | ------ |
+| `play()`             | 开始播放动画             | -                      | `void` |
+| `pause()`            | 暂停动画                 | -                      | `void` |
+| `stop()`             | 停止动画并重置到初始状态 | -                      | `void` |
+| `seek(time: number)` | 跳转到指定时间           | `time`: 目标时间(毫秒) | `void` |
+
+#### 状态查询方法
+
+| 方法                 | 描述               | 返回值             |
+| -------------------- | ------------------ | ------------------ |
+| `getCurrentTime()`   | 获取当前播放时间   | `number`           |
+| `getDuration()`      | 获取动画总时长     | `number`           |
+| `getProgress()`      | 获取播放进度(0-1)  | `number`           |
+| `getState()`         | 获取当前状态       | `AnimationState`   |
+| `isPlaying()`        | 检查是否正在播放   | `boolean`          |
+| `getSchema()`        | 获取动画配置的副本 | `IAnimationSchema` |
+| `getAnimationInfo()` | 获取动画统计信息   | `IAnimationInfo`   |
+
+#### 数据更新方法
+
+| 方法                      | 描述         | 参数                    |
+| ------------------------- | ------------ | ----------------------- |
+| `updateData(newData)`     | 更新动画数据 | `newData`: 新数据对象   |
+| `updateSchema(newSchema)` | 更新动画配置 | `newSchema`: 新配置对象 |
+
+#### 事件监听方法
+
+| 方法                                       | 描述         | 参数                                        |
+| ------------------------------------------ | ------------ | ------------------------------------------- |
+| `onTimeChange(callback)`                   | 监听时间变化 | `callback`: (time: number) => void          |
+| `onAnimationComplete(callback)`            | 监听动画完成 | `callback`: () => void                      |
+| `onStateChange(callback)`                  | 监听状态变化 | `callback`: (state: AnimationState) => void |
+| `onListen(elementId, eventType, callback)` | 监听元素事件 | 详见下表                                    |
+
+##### onListen 参数详情
+
+| 参数        | 类型                   | 描述                             |
+| ----------- | ---------------------- | -------------------------------- |
+| `elementId` | `string`               | 元素ID                           |
+| `eventType` | `string`               | 事件类型('click', 'mouseover'等) |
+| `callback`  | `ElementEventCallback` | 事件回调函数                     |
+| **返回值**  | `() => void`           | 取消监听的函数                   |
+
+#### 事件管理方法
+
+| 方法                            | 描述                         | 参数                |
+| ------------------------------- | ---------------------------- | ------------------- |
+| `removeAllListeners(elementId)` | 移除指定元素的所有事件监听器 | `elementId`: 元素ID |
+| `removeAllElementListeners()`   | 移除所有事件监听器           | -                   |
+| `destroy()`                     | 销毁动画播放器               | -                   |
+
+### TemplateEngine
+
+模板引擎类，负责解析和渲染模板字符串。
+
+#### 静态方法
+
+| 方法                     | 描述           | 参数                                       | 返回值   |
+| ------------------------ | -------------- | ------------------------------------------ | -------- |
+| `render(template, data)` | 渲染模板字符串 | `template`: 模板字符串<br>`data`: 渲染数据 | `string` |
+
+### CSSAnimationGenerator
+
+CSS动画生成器类，负责生成CSS关键帧动画代码。
+
+#### 静态方法
+
+| 方法                                                | 描述              | 参数                                                              | 返回值   |
+| --------------------------------------------------- | ----------------- | ----------------------------------------------------------------- | -------- |
+| `generateKeyframes(elementId, keyframes)`           | 生成CSS关键帧动画 | `elementId`: 元素ID<br>`keyframes`: 关键帧数组                    | `string` |
+| `generateAnimationCSS(elementId, duration, easing)` | 生成元素动画CSS   | `elementId`: 元素ID<br>`duration`: 动画时长<br>`easing`: 缓动函数 | `string` |
+| `easingToCSSFunction(easing)`                       | 转换缓动函数为CSS | `easing`: 缓动函数名                                              | `string` |
+
+## 🏭 工厂函数
+
+### createAnimationPlayer
+
+根据容器ID创建动画播放器。
+
+```typescript
+function createAnimationPlayer(
+  containerId: string,
+  schema: IAnimationSchema,
+): AnimationPlayer;
+```
+
+### createAnimationPlayerFromElement
+
+直接使用DOM元素创建动画播放器。
+
+```typescript
+function createAnimationPlayerFromElement(
+  container: HTMLElement,
+  schema: IAnimationSchema,
+): AnimationPlayer;
+```
+
+## 🎯 快速开始
+
+### 基础示例
+
+```typescript
+import { createAnimationPlayer, IAnimationSchema } from '@yqg-max/click-gate';
+
+// 1. 定义动画配置
+const schema: IAnimationSchema = {
+  elements: [
+    {
+      id: 'box1',
+      content: {
+        html: '<div style="width: 100px; height: 100px; background: #3b82f6;"></div>',
+        style: {
+          borderRadius: '8px',
+        },
+      },
+    },
+  ],
+  keyframes: [
+    {
+      id: 'kf1',
+      elementId: 'box1',
+      time: 0,
+      properties: { x: 0, y: 0, opacity: 1, scale: 1 },
+    },
+    {
+      id: 'kf2',
+      elementId: 'box1',
+      time: 1000,
+      properties: { x: 200, y: 100, opacity: 0.5, scale: 1.5 },
+    },
+    {
+      id: 'kf3',
+      elementId: 'box1',
+      time: 2000,
+      properties: { x: 0, y: 0, opacity: 1, scale: 1, rotation: 360 },
+    },
+  ],
+};
+
+// 2. 创建播放器
+const player = createAnimationPlayer('animation-container', schema);
+
+// 3. 播放动画
+player.play();
+```
+
+### 模板渲染示例
+
+```typescript
+const schema: IAnimationSchema = {
+  data: {
+    title: '欢迎使用动画播放器',
+    subtitle: '强大而灵活的动画解决方案',
+  },
+  elements: [
+    {
+      id: 'text1',
+      data: {
+        content: '{{title}}',
+      },
+      content: {
+        html: '<h2>{{content}}</h2>',
+        style: {
+          color: '#1f2937',
+          fontFamily: 'Arial, sans-serif',
+        },
+      },
+    },
+    {
+      id: 'text2',
+      content: {
+        html: '<p>{{subtitle}}</p>',
+        style: {
+          color: '#6b7280',
+        },
+      },
+    },
+  ],
+  keyframes: [
+    // 标题动画
+    {
+      id: 'title-start',
+      elementId: 'text1',
+      time: 0,
+      properties: { x: -200, opacity: 0 },
+    },
+    {
+      id: 'title-end',
+      elementId: 'text1',
+      time: 800,
+      properties: { x: 0, opacity: 1 },
+    },
+    // 副标题动画
+    {
+      id: 'subtitle-start',
+      elementId: 'text2',
+      time: 400,
+      properties: { x: 200, opacity: 0 },
+    },
+    {
+      id: 'subtitle-end',
+      elementId: 'text2',
+      time: 1200,
+      properties: { x: 0, opacity: 1 },
+    },
+  ],
+};
+```
+
+### 事件监听示例
+
+```typescript
+// 创建播放器
+const player = createAnimationPlayer('container', schema);
+
+// 监听元素点击事件
+const removeClickListener = player.onListen(
+  'button1',
+  'click',
+  (event, element) => {
+    console.log('按钮被点击了！', element);
+    // 可以执行自定义逻辑
+    player.seek(1500); // 跳转到1.5秒
+  },
+);
+
+// 监听元素悬停事件
+player.onListen('image1', 'mouseover', (event, element) => {
+  element.style.transform = 'scale(1.1)';
+});
+
+player.onListen('image1', 'mouseout', (event, element) => {
+  element.style.transform = 'scale(1)';
+});
+
+// 监听动画状态变化
+player.onStateChange((state) => {
+  console.log('动画状态:', state);
+});
+
+// 监听播放进度
+player.onTimeChange((time) => {
+  console.log('当前时间:', time);
+});
+
+// 监听动画完成
+player.onAnimationComplete(() => {
+  console.log('动画播放完成！');
+});
+```
+
+### 动态数据更新示例
+
+```typescript
+// 创建包含动态数据的动画
+const schema: IAnimationSchema = {
+  data: {
+    username: 'User',
+    score: 0,
+  },
+  elements: [
+    {
+      id: 'scoreDisplay',
+      content: {
+        html: '<div class="score">{{username}}的分数: {{score}}</div>',
+      },
+    },
+  ],
+  keyframes: [
+    {
+      id: 'score-anim',
+      elementId: 'scoreDisplay',
+      time: 0,
+      properties: { scale: 1 },
+    },
+    {
+      id: 'score-bounce',
+      elementId: 'scoreDisplay',
+      time: 500,
+      properties: { scale: 1.2 },
+    },
+    {
+      id: 'score-normal',
+      elementId: 'scoreDisplay',
+      time: 1000,
+      properties: { scale: 1 },
+    },
+  ],
+};
+
+const player = createAnimationPlayer('container', schema);
+
+// 动态更新数据
+function updateScore(newScore: number) {
+  player.updateData({ score: newScore });
+  player.seek(0); // 重新播放动画
+  player.play();
+}
+
+// 使用示例
+updateScore(100);
+updateScore(250);
+```
+
+## 🎪 高级用法
+
+### 复杂动画序列
+
+```typescript
+const complexSchema: IAnimationSchema = {
+  elements: [
+    { id: 'circle', content: { html: '<div class="circle"></div>' } },
+    { id: 'square', content: { html: '<div class="square"></div>' } },
+    { id: 'triangle', content: { html: '<div class="triangle"></div>' } },
+  ],
+  keyframes: [
+    // 圆形动画序列
+    {
+      id: 'c1',
+      elementId: 'circle',
+      time: 0,
+      properties: { x: 0, y: 0, opacity: 0 },
+    },
+    {
+      id: 'c2',
+      elementId: 'circle',
+      time: 500,
+      properties: { x: 100, y: 0, opacity: 1 },
+    },
+    {
+      id: 'c3',
+      elementId: 'circle',
+      time: 1000,
+      properties: { x: 100, y: 100, rotation: 180 },
+    },
+    {
+      id: 'c4',
+      elementId: 'circle',
+      time: 1500,
+      properties: { x: 0, y: 100, scale: 1.5 },
+    },
+    {
+      id: 'c5',
+      elementId: 'circle',
+      time: 2000,
+      properties: { x: 0, y: 0, scale: 1, rotation: 360 },
+    },
+
+    // 方形动画序列（延迟启动）
+    {
+      id: 's1',
+      elementId: 'square',
+      time: 300,
+      properties: { x: 200, y: 0, opacity: 0 },
+    },
+    {
+      id: 's2',
+      elementId: 'square',
+      time: 800,
+      properties: { x: 300, y: 0, opacity: 1 },
+    },
+    {
+      id: 's3',
+      elementId: 'square',
+      time: 1300,
+      properties: { x: 300, y: 100, rotation: 90 },
+    },
+    {
+      id: 's4',
+      elementId: 'square',
+      time: 1800,
+      properties: { x: 200, y: 100, scale: 0.8 },
+    },
+
+    // 三角形动画序列（更晚启动）
+    {
+      id: 't1',
+      elementId: 'triangle',
+      time: 600,
+      properties: { x: 400, y: 50, opacity: 0 },
+    },
+    {
+      id: 't2',
+      elementId: 'triangle',
+      time: 1100,
+      properties: { x: 450, y: 50, opacity: 1 },
+    },
+    {
+      id: 't3',
+      elementId: 'triangle',
+      time: 1600,
+      properties: { x: 450, y: 100, rotation: 120 },
+    },
+    {
+      id: 't4',
+      elementId: 'triangle',
+      time: 2100,
+      properties: { x: 400, y: 100, scale: 1.2 },
+    },
+  ],
+};
+```
+
+### 自定义缓动函数
+
+```typescript
+// 使用不同的缓动函数创建丰富的动画效果
+const bounceSchema: IAnimationSchema = {
+  elements: [{ id: 'bouncer', content: { html: '<div class="ball"></div>' } }],
+  keyframes: [
+    {
+      id: 'bounce-start',
+      elementId: 'bouncer',
+      time: 0,
+      properties: { y: 0 },
+    },
+    {
+      id: 'bounce-drop',
+      elementId: 'bouncer',
+      time: 1000,
+      properties: { y: 200 }, // 使用 bounce-out 缓动
+    },
+    {
+      id: 'bounce-up',
+      elementId: 'bouncer',
+      time: 1500,
+      properties: { y: 50 }, // 弹起
+    },
+    {
+      id: 'bounce-settle',
+      elementId: 'bouncer',
+      time: 2000,
+      properties: { y: 200 }, // 最终落地
+    },
+  ],
+};
+```
+
+## 📝 API 参考
+
+### 动画播放器 API
+
+#### 播放控制
+
+- `play()` - 播放动画
+- `pause()` - 暂停动画
+- `stop()` - 停止动画
+- `seek(time: number)` - 跳转到指定时间
+
+#### 状态查询
+
+- `getCurrentTime(): number` - 当前播放时间
+- `getDuration(): number` - 动画总时长
+- `getProgress(): number` - 播放进度 (0-1)
+- `getState(): AnimationState` - 当前状态
+- `isPlaying(): boolean` - 是否正在播放
+
+#### 数据管理
+
+- `updateData(data: Record<string, any>)` - 更新动画数据
+- `updateSchema(schema: IAnimationSchema)` - 更新动画配置
+- `getSchema(): IAnimationSchema` - 获取当前配置
+- `getAnimationInfo(): IAnimationInfo` - 获取动画信息
+
+#### 事件监听
+
+- `onTimeChange(callback)` - 时间变化事件
+- `onAnimationComplete(callback)` - 动画完成事件
+- `onStateChange(callback)` - 状态变化事件
+- `onListen(elementId, eventType, callback)` - 元素事件监听
+
+#### 事件管理
+
+- `removeAllListeners(elementId)` - 移除指定元素的监听器
+- `removeAllElementListeners()` - 移除所有监听器
+- `destroy()` - 销毁播放器
+
+## 🔧 最佳实践
+
+### 1. 性能优化
+
+```typescript
+// 避免过多的关键帧
+// ❌ 不好的做法
+const badSchema = {
+  keyframes: [
+    { time: 0, properties: { x: 0 } },
+    { time: 10, properties: { x: 1 } },
+    { time: 20, properties: { x: 2 } },
+    // ... 每10ms一个关键帧
+  ],
+};
+
+// ✅ 好的做法
+const goodSchema = {
+  keyframes: [
+    { time: 0, properties: { x: 0 } },
+    { time: 500, properties: { x: 50 } },
+    { time: 1000, properties: { x: 100 } },
+  ],
+};
+```
+
+### 2. 内存管理
+
+```typescript
+// 在组件卸载时清理播放器
+const player = createAnimationPlayer('container', schema);
+
+// 在适当的时候销毁
+function cleanup() {
+  player.destroy(); // 清理所有事件监听器和DOM引用
+}
+
+// React 示例
+useEffect(() => {
+  return () => {
+    cleanup();
+  };
+}, []);
+```
+
+### 3. 错误处理
+
+```typescript
+try {
+  const player = createAnimationPlayer('container', schema);
+  player.play();
+} catch (error) {
+  console.error('动画初始化失败:', error);
+  // 处理错误情况
+}
+```
+
+## ⚠️ 注意事项
+
+1. **容器元素**: 确保容器元素存在且已挂载到DOM
+2. **唯一ID**: 元素ID和关键帧ID必须唯一
+3. **关键帧关联**: 所有关键帧必须关联到存在的元素
+4. **内存清理**: 使用完毕后调用`destroy()`方法清理资源
+5. **时间单位**: 所有时间参数使用毫秒为单位
+6. **CSS属性**: 支持的CSS属性有限，主要为变换属性
+
+## 🐛 常见问题
+
+### Q: 动画不播放？
+
+A: 检查以下几点：
+
+- 容器元素是否存在
+- 动画配置是否正确
+- 是否有关键帧数据
+- 检查浏览器控制台是否有错误
+
+### Q: 模板变量不显示？
+
+A: 确保：
+
+- 数据对象包含对应的属性
+- 模板语法正确使用`{{variableName}}`
+- 调用`updateData()`后重新渲染
+
+### Q: 事件监听器不工作？
+
+A: 检查：
+
+- 元素ID是否正确
+- 事件类型名称是否正确
+- 元素是否已创建并添加到DOM
+
+## 📄 许可证
+
+MIT License
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+---
+
+如有疑问，请查看源码注释或提交 Issue。