@yqg/aminofx-css-kit

v1.0.3

Published

9 days ago

YQG AminoFX CSS animation kit - Core animation utilities and effects

AminoFX CSS Kit

一个轻量级、高性能的 CSS 动画播放器 SDK，专为 Web 动画场景设计。

🚀 功能特性

CSS 动画渲染: 基于纯 CSS 实现的高性能动画播放
资源预加载: 智能的图片预加载机制，避免动画卡顿
多种加载方式: 支持 JSON Schema 直接传入或通过 URL 动态加载
动态数据替换: 支持模板变量替换，实现数据驱动的动画
循环播放: 内置自动循环播放功能
灵活布局: 支持多种垂直对齐方式
生命周期管理: 完整的初始化、播放、销毁流程
类型安全: 完整的 TypeScript 类型定义

📦 安装

npm install aminofx-css-kit

🏗️ 核心接口

IJsonSchema

JSON 数据格式接口，定义动画数据结构。

interface IJsonSchema {
  /** 动画总时长（毫秒） */
  duration: number;
  /** CSS 动画内容（包含样式和HTML结构） */
  content: string;
}

IPlayerOptions

播放器配置接口，定义创建播放器时的所有可选参数。

interface IPlayerOptions {
  /** 弹窗垂直对齐方式 */
  alignItems?: 'center' | 'flex-start' | 'flex-end';

  /** 直接传入 JSON Schema 数据 */
  jsonSchema?: IJsonSchema;

  /** 通过 URL 加载 JSON Schema（jsonSchema 优先级更高） */
  jsonUrl?: string;

  /** 需要预加载的图片列表 */
  preloadImgList?: string[];

  /** 是否自动循环播放 */
  autoLoop?: boolean;

  /** 动态数据，用于替换模板变量 */
  dynamicData?: Record<string, string | number | boolean>;
}

🎨 核心类

AnimationPlayer

动画播放器类，负责管理和控制动画的播放。

方法列表

| 方法 | 描述 | 参数 | 返回值 | | ----------------------- | ------------------------ | ------------------------- | --------------- | | play() | 开始播放动画 | - | Promise<void> | | ready() | 等待资源加载完成 | - | Promise<void> | | destroy() | 销毁播放器，清理资源 | - | void | | updateSchema(options) | 更新动画配置并重新初始化 | options: IPlayerOptions | void |

🏭 工厂函数

createCssAnimationPlayer

创建 CSS 动画播放器的工厂函数。

function createCssAnimationPlayer(
  containerId: string,
  options: IPlayerOptions,
): AnimationPlayer;

参数说明：

containerId: 容器元素的 ID
options: 播放器配置选项

返回值：

AnimationPlayer: 动画播放器实例

🎯 快速开始

基础示例（使用 jsonUrl）

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>AminoFX CSS Kit Demo</title>
    <script src="https://unpkg.com/aminofx-css-kit/dist/umd/aminofx-css-kit.min.js"></script>
  </head>
  <body>
    <div id="demo-container"></div>

    <script>
      const player = window.createCssAnimationPlayer('demo-container', {
        jsonUrl: 'https://example.com/animation.json',
        preloadImgList: [
          'https://example.com/image1.png',
          'https://example.com/image2.png',
        ],
        alignItems: 'flex-start',
      });

      player.play();
    </script>
  </body>
</html>

使用 jsonSchema 直接传入

import createCssAnimationPlayer from 'aminofx-css-kit';

const player = createCssAnimationPlayer('demo-container', {
  jsonSchema: {
    duration: 5720,
    content: `
      <style>
        .animation-box {
          width: 100px;
          height: 100px;
          background: #3b82f6;
          animation: slide 2s ease-in-out;
        }
        @keyframes slide {
          from { transform: translateX(0); }
          to { transform: translateX(200px); }
        }
      </style>
      <div class="animation-box"></div>
    `,
  },
  preloadImgList: ['https://example.com/bg.png'],
});

// 播放动画
player.play();

动态数据替换示例

const player = createCssAnimationPlayer('demo-container', {
  jsonSchema: {
    duration: 3000,
    content: `
      <style>
        .title { 
          font-size: 24px; 
          color: #1f2937;
          animation: fadeIn 1s;
        }
        @keyframes fadeIn {
          from { opacity: 0; }
          to { opacity: 1; }
        }
      </style>
      <div class="title">{{title}}</div>
    `,
  },
  dynamicData: {
    title: '欢迎使用 AminoFX CSS Kit',
  },
});

player.play();

循环播放示例

const player = createCssAnimationPlayer('demo-container', {
  jsonUrl: 'https://example.com/loop-animation.json',
  autoLoop: true, // 启用自动循环
  alignItems: 'center',
});

player.play();

🎪 高级用法

生命周期管理

// 创建播放器
const player = createCssAnimationPlayer('container', {
  jsonUrl: 'https://example.com/animation.json',
  preloadImgList: ['https://example.com/asset1.png'],
});

// 等待资源加载完成
await player.ready();
console.log('动画资源已准备完成');

// 播放动画
await player.play();
console.log('动画开始播放');

// 在适当的时候销毁
player.destroy();
console.log('播放器已销毁');

动态更新动画配置

const player = createCssAnimationPlayer('container', {
  jsonUrl: 'https://example.com/animation1.json',
});

// 播放第一个动画
await player.play();

// 切换到另一个动画
player.updateSchema({
  jsonUrl: 'https://example.com/animation2.json',
  autoLoop: true,
});

// 播放新动画
await player.play();

React 集成示例

import React, { useEffect, useRef, useState } from 'react';
import createCssAnimationPlayer, { AnimationPlayer } from 'aminofx-css-kit';

export const AnimationComponent: React.FC = () => {
  const containerRef = useRef<HTMLDivElement>(null);
  const playerRef = useRef<AnimationPlayer | null>(null);
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    if (!containerRef.current) return;

    // 创建播放器
    const player = createCssAnimationPlayer('animation-container', {
      jsonUrl: 'https://example.com/animation.json',
      preloadImgList: ['https://example.com/image.png'],
      alignItems: 'center',
    });

    playerRef.current = player;

    // 等待资源加载
    player
      .ready()
      .then(() => {
        // sdk初始化成功
        setIsReady(true);
        // 开始播放
        player.play();
      })
      .catch((error) => {
        console.error('sdk初始化失败', error);
      });

    // 清理
    return () => {
      player.destroy();
      playerRef.current = null;
    };
  }, []);

  return (
    <div>
      <div id='animation-container' ref={containerRef} />
      <button disabled={!isReady}>{isReady ? '播放动画' : '加载中...'}</button>
    </div>
  );
};

📝 API 参考

播放器实例方法

play()

开始播放动画。如果动画尚未准备就绪，会自动调用 ready() 方法。

await player.play();

ready()

等待所有资源（特别是图片）加载完成。此方法会：

预加载所有指定的图片
确保图片解码完成
返回 Promise，资源准备完成后 resolve

await player.ready();
console.log('所有资源已加载完成');

destroy()

销毁播放器，清理所有资源：

清除循环定时器
清空容器内容
重置内部状态

player.destroy();

updateSchema(options)

更新动画配置并重新初始化。会：

清理旧的定时器
重置播放器状态
加载新的动画配置

player.updateSchema({
  jsonUrl: 'https://example.com/new-animation.json',
  autoLoop: true,
});

🔧 最佳实践

1. 图片预加载

为了获得最佳的动画体验，建议提前声明所有需要的图片：

const player = createCssAnimationPlayer('container', {
  jsonUrl: 'https://example.com/animation.json',
  preloadImgList: [
    'https://example.com/bg.png',
    'https://example.com/icon1.png',
    'https://example.com/icon2.png',
  ],
});

// 等待所有图片加载完成
await player.ready();
player.play();

2. 资源清理

在组件卸载或页面离开时，务必销毁播放器：

// React
useEffect(() => {
  const player = createCssAnimationPlayer('container', options);

  return () => {
    player.destroy(); // 清理资源
  };
}, []);

// Vue
onUnmounted(() => {
  player.value?.destroy();
});

3. 性能优化

// ✅ 推荐：使用 jsonSchema 直接传入，避免网络请求
const player = createCssAnimationPlayer('container', {
  jsonSchema: animationData,
  preloadImgList: imageUrls,
});

// ⚠️ 注意：使用 jsonUrl 会产生额外的网络请求
const player = createCssAnimationPlayer('container', {
  jsonUrl: 'https://example.com/animation.json',
});

⚠️ 注意事项

容器元素：确保容器元素在调用 createCssAnimationPlayer 时已存在于 DOM 中
资源路径：预加载图片列表中的 URL 必须是完整的 HTTP/HTTPS 地址
优先级：当同时传入 jsonSchema 和 jsonUrl 时，jsonSchema 优先级更高
循环播放：启用 autoLoop 时，确保提供了 duration 属性
内存管理：使用完毕后务必调用 destroy() 方法清理资源
CORS：通过 URL 加载的资源需要正确配置 CORS 策略

🐛 常见问题

Q: 动画不显示？

A: 检查以下几点：

容器元素是否存在（document.getElementById(containerId) 不为 null）
JSON Schema 的 content 字段是否包含有效的 HTML 和 CSS
检查浏览器控制台是否有错误信息
确认图片 URL 是否可访问

Q: 图片加载失败？

检查图片 URL 是否正确
确认服务器是否配置了正确的 CORS 头
查看浏览器网络面板，确认图片请求状态
图片加载失败不会阻塞动画播放，但可能影响视觉效果

Q: 循环播放不工作？

确保 autoLoop 设置为 true
检查 jsonSchema.duration 是否正确设置
循环播放基于定时器实现，确保页面未被挂起

Q: 如何动态更改动画内容？

A: 使用 updateSchema() 方法：

player.updateSchema({
  jsonSchema: newAnimationData,
  dynamicData: { title: '新标题' },
});
player.play();