@eva/plugin-transition 2.0.1-beta.27 → 2.0.1-beta.28

package/dist/plugin-transition.cjs.js

@@ -134,14 +134,72 @@ class Animation {
     }
 }
 
+/**
+ * 过渡动画组件（基于 Tween.js）
+ *
+ * Transition 组件为游戏对象提供补间动画功能，可以平滑地改变组件属性。
+ * 它基于 Tween.js 实现，支持多种缓动函数、动画组、循环播放等高级功能。
+ *
+ * 主要功能：
+ * - 支持多个命名动画组
+ * - 可配置关键帧和缓动函数
+ * - 支持动画循环和迭代次数
+ * - 提供播放、暂停、停止控制
+ * - 支持动画完成和更新事件
+ *
+ * @example
+ * ```typescript
+ * const sprite = new GameObject('sprite');
+ * sprite.addComponent(new Transition({
+ *   group: {
+ *     fadeIn: [{
+ *       name: 'alpha',
+ *       component: sprite.getComponent('Sprite'),
+ *       values: [
+ *         { time: 0, value: 0, tween: 'ease-in' },
+ *         { time: 1000, value: 1 }
+ *       ]
+ *     }],
+ *     moveRight: [{
+ *       name: 'position.x',
+ *       component: sprite.getComponent('Transform'),
+ *       values: [
+ *         { time: 0, value: 0 },
+ *         { time: 2000, value: 500, tween: 'ease-out-quad' }
+ *       ]
+ *     }]
+ *   }
+ * }));
+ *
+ * // 播放动画
+ * const transition = sprite.getComponent('Transition');
+ * transition.play('fadeIn'); // 播放一次
+ * transition.play('moveRight', Infinity); // 无限循环
+ *
+ * // 监听动画事件
+ * transition.on('finish', (name) => {
+ *   console.log('动画完成:', name);
+ * });
+ * ```
+ */
 class Transition extends eva_js.Component {
     constructor() {
         super(...arguments);
+        /** 动画实例映射表 */
         this.animations = {};
+        /** 动画组配置，key 为动画名称，value 为动画配置数组 */
         this.group = {};
+        /** 当前时间戳 */
         this.currentTime = 0;
+        /** 待播放的动画队列 */
         this.needPlay = [];
     }
+    /**
+     * 初始化组件
+     *
+     * @param params - 初始化参数
+     * @param params.group - 动画组配置对象
+     */
     init({ group } = { group: {} }) {
         this.group = group;
         this.tweenGroup = new tween_js.Group();
@@ -151,6 +209,19 @@ class Transition extends eva_js.Component {
             this.newAnimation(name);
         }
     }
+    /**
+     * 播放动画
+     *
+     * @param name - 动画名称，如果不传则播放第一个动画
+     * @param iteration - 循环次数，默认 1，传 Infinity 为无限循环
+     *
+     * @example
+     * ```typescript
+     * transition.play('fadeIn'); // 播放一次
+     * transition.play('rotate', 3); // 循环播放 3 次
+     * transition.play('bounce', Infinity); // 无限循环
+     * ```
+     */
     play(name, iteration) {
         if (!name) {
             name = Object.keys(this.group)[0];
@@ -162,6 +233,17 @@ class Transition extends eva_js.Component {
             this.needPlay.push({ name, iteration });
         }
     }
+    /**
+     * 停止动画
+     *
+     * @param name - 动画名称，如果不传则停止所有动画
+     *
+     * @example
+     * ```typescript
+     * transition.stop('fadeIn'); // 停止指定动画
+     * transition.stop(); // 停止所有动画
+     * ```
+     */
     stop(name) {
         var _a, _b;
         if (!name) {
@@ -215,14 +297,28 @@ class Transition extends eva_js.Component {
         this.animations[name] = animation;
     }
 }
+/** 组件名称 */
 Transition.componentName = 'Transition';
 
+/**
+ * 过渡动画系统
+ *
+ * TransitionSystem 是一个轻量级系统，主要用于注册 Transition 插件到游戏中。
+ * 实际的动画逻辑由 Transition 组件自身的 update 方法处理。
+ *
+ * @example
+ * ```typescript
+ * game.addSystem(new TransitionSystem());
+ * ```
+ */
 class TransitionSystem extends eva_js.System {
     constructor() {
         super(...arguments);
+        /** 系统实例名称 */
         this.name = 'transition';
     }
 }
+/** 系统名称 */
 TransitionSystem.systemName = 'transition';
 
 exports.Transition = Transition;

package/dist/plugin-transition.d.ts

@@ -12,18 +12,102 @@ declare interface AnimationStruct {
     }[];
 }
 
+/**
+ * 过渡动画组件（基于 Tween.js）
+ *
+ * Transition 组件为游戏对象提供补间动画功能，可以平滑地改变组件属性。
+ * 它基于 Tween.js 实现，支持多种缓动函数、动画组、循环播放等高级功能。
+ *
+ * 主要功能：
+ * - 支持多个命名动画组
+ * - 可配置关键帧和缓动函数
+ * - 支持动画循环和迭代次数
+ * - 提供播放、暂停、停止控制
+ * - 支持动画完成和更新事件
+ *
+ * @example
+ * ```typescript
+ * const sprite = new GameObject('sprite');
+ * sprite.addComponent(new Transition({
+ *   group: {
+ *     fadeIn: [{
+ *       name: 'alpha',
+ *       component: sprite.getComponent('Sprite'),
+ *       values: [
+ *         { time: 0, value: 0, tween: 'ease-in' },
+ *         { time: 1000, value: 1 }
+ *       ]
+ *     }],
+ *     moveRight: [{
+ *       name: 'position.x',
+ *       component: sprite.getComponent('Transform'),
+ *       values: [
+ *         { time: 0, value: 0 },
+ *         { time: 2000, value: 500, tween: 'ease-out-quad' }
+ *       ]
+ *     }]
+ *   }
+ * }));
+ *
+ * // 播放动画
+ * const transition = sprite.getComponent('Transition');
+ * transition.play('fadeIn'); // 播放一次
+ * transition.play('moveRight', Infinity); // 无限循环
+ *
+ * // 监听动画事件
+ * transition.on('finish', (name) => {
+ *   console.log('动画完成:', name);
+ * });
+ * ```
+ */
 export declare class Transition extends Component<TransitionParams> {
+    /** 组件名称 */
     static componentName: string;
+    /** 动画实例映射表 */
     private animations;
+    /** Tween.js 动画组 */
     tweenGroup: Group;
+    /** 动画组配置，key 为动画名称，value 为动画配置数组 */
     group: Record<string, AnimationStruct[]>;
+    /** 当前时间戳 */
     private currentTime;
+    /** 待播放的动画队列 */
     private needPlay;
+    /**
+     * 初始化组件
+     *
+     * @param params - 初始化参数
+     * @param params.group - 动画组配置对象
+     */
     init({ group }?: {
         group: {};
     }): void;
     awake(): void;
+    /**
+     * 播放动画
+     *
+     * @param name - 动画名称，如果不传则播放第一个动画
+     * @param iteration - 循环次数，默认 1，传 Infinity 为无限循环
+     *
+     * @example
+     * ```typescript
+     * transition.play('fadeIn'); // 播放一次
+     * transition.play('rotate', 3); // 循环播放 3 次
+     * transition.play('bounce', Infinity); // 无限循环
+     * ```
+     */
     play(name: string, iteration?: number): void;
+    /**
+     * 停止动画
+     *
+     * @param name - 动画名称，如果不传则停止所有动画
+     *
+     * @example
+     * ```typescript
+     * transition.stop('fadeIn'); // 停止指定动画
+     * transition.stop(); // 停止所有动画
+     * ```
+     */
     stop(name: any): void;
     onPause(): void;
     onResume(): void;
@@ -36,8 +120,21 @@ declare interface TransitionParams {
     group: Record<string, AnimationStruct[]>;
 }
 
+/**
+ * 过渡动画系统
+ *
+ * TransitionSystem 是一个轻量级系统，主要用于注册 Transition 插件到游戏中。
+ * 实际的动画逻辑由 Transition 组件自身的 update 方法处理。
+ *
+ * @example
+ * ```typescript
+ * game.addSystem(new TransitionSystem());
+ * ```
+ */
 export declare class TransitionSystem extends System {
+    /** 系统名称 */
     static systemName: string;
+    /** 系统实例名称 */
     readonly name = "transition";
 }
 

package/dist/plugin-transition.esm.js

@@ -130,14 +130,72 @@ class Animation {
     }
 }
 
+/**
+ * 过渡动画组件（基于 Tween.js）
+ *
+ * Transition 组件为游戏对象提供补间动画功能，可以平滑地改变组件属性。
+ * 它基于 Tween.js 实现，支持多种缓动函数、动画组、循环播放等高级功能。
+ *
+ * 主要功能：
+ * - 支持多个命名动画组
+ * - 可配置关键帧和缓动函数
+ * - 支持动画循环和迭代次数
+ * - 提供播放、暂停、停止控制
+ * - 支持动画完成和更新事件
+ *
+ * @example
+ * ```typescript
+ * const sprite = new GameObject('sprite');
+ * sprite.addComponent(new Transition({
+ *   group: {
+ *     fadeIn: [{
+ *       name: 'alpha',
+ *       component: sprite.getComponent('Sprite'),
+ *       values: [
+ *         { time: 0, value: 0, tween: 'ease-in' },
+ *         { time: 1000, value: 1 }
+ *       ]
+ *     }],
+ *     moveRight: [{
+ *       name: 'position.x',
+ *       component: sprite.getComponent('Transform'),
+ *       values: [
+ *         { time: 0, value: 0 },
+ *         { time: 2000, value: 500, tween: 'ease-out-quad' }
+ *       ]
+ *     }]
+ *   }
+ * }));
+ *
+ * // 播放动画
+ * const transition = sprite.getComponent('Transition');
+ * transition.play('fadeIn'); // 播放一次
+ * transition.play('moveRight', Infinity); // 无限循环
+ *
+ * // 监听动画事件
+ * transition.on('finish', (name) => {
+ *   console.log('动画完成:', name);
+ * });
+ * ```
+ */
 class Transition extends Component {
     constructor() {
         super(...arguments);
+        /** 动画实例映射表 */
         this.animations = {};
+        /** 动画组配置，key 为动画名称，value 为动画配置数组 */
         this.group = {};
+        /** 当前时间戳 */
         this.currentTime = 0;
+        /** 待播放的动画队列 */
         this.needPlay = [];
     }
+    /**
+     * 初始化组件
+     *
+     * @param params - 初始化参数
+     * @param params.group - 动画组配置对象
+     */
     init({ group } = { group: {} }) {
         this.group = group;
         this.tweenGroup = new Group();
@@ -147,6 +205,19 @@ class Transition extends Component {
             this.newAnimation(name);
         }
     }
+    /**
+     * 播放动画
+     *
+     * @param name - 动画名称，如果不传则播放第一个动画
+     * @param iteration - 循环次数，默认 1，传 Infinity 为无限循环
+     *
+     * @example
+     * ```typescript
+     * transition.play('fadeIn'); // 播放一次
+     * transition.play('rotate', 3); // 循环播放 3 次
+     * transition.play('bounce', Infinity); // 无限循环
+     * ```
+     */
     play(name, iteration) {
         if (!name) {
             name = Object.keys(this.group)[0];
@@ -158,6 +229,17 @@ class Transition extends Component {
             this.needPlay.push({ name, iteration });
         }
     }
+    /**
+     * 停止动画
+     *
+     * @param name - 动画名称，如果不传则停止所有动画
+     *
+     * @example
+     * ```typescript
+     * transition.stop('fadeIn'); // 停止指定动画
+     * transition.stop(); // 停止所有动画
+     * ```
+     */
     stop(name) {
         var _a, _b;
         if (!name) {
@@ -211,14 +293,28 @@ class Transition extends Component {
         this.animations[name] = animation;
     }
 }
+/** 组件名称 */
 Transition.componentName = 'Transition';
 
+/**
+ * 过渡动画系统
+ *
+ * TransitionSystem 是一个轻量级系统，主要用于注册 Transition 插件到游戏中。
+ * 实际的动画逻辑由 Transition 组件自身的 update 方法处理。
+ *
+ * @example
+ * ```typescript
+ * game.addSystem(new TransitionSystem());
+ * ```
+ */
 class TransitionSystem extends System {
     constructor() {
         super(...arguments);
+        /** 系统实例名称 */
         this.name = 'transition';
     }
 }
+/** 系统名称 */
 TransitionSystem.systemName = 'transition';
 
 export { Transition, TransitionSystem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eva/plugin-transition",
-  "version": "2.0.1-beta.27",
+  "version": "2.0.1-beta.28",
   "description": "@eva/plugin-transition",
   "main": "index.js",
   "module": "dist/plugin-transition.esm.js",
@@ -18,7 +18,7 @@
   "license": "MIT",
   "homepage": "https://eva.js.org",
   "dependencies": {
-    "@eva/eva.js": "2.0.1-beta.27",
+    "@eva/eva.js": "2.0.1-beta.28",
     "@tweenjs/tween.js": "^18.6.4",
     "sprite-timeline": "^1.10.2"
   }