mstf-kit/dist/types/utils/lottie.d.ts

一个现代化的 JavaScript/TypeScript 工具库，提供了丰富的常用工具函数

/**
 * Lottie动画工具
 * 支持加载、渲染和控制Lottie动画
 */
/**
 * Lottie动画状态
 */
export type LottiePlayerState = 'loading' | 'playing' | 'paused' | 'stopped' | 'destroyed' | 'error';
/**
 * Lottie动画渲染模式
 */
export type LottieRenderMode = 'svg' | 'canvas' | 'html';
/**
 * Vue3 ref类型 (简化版)
 */
interface Ref<T> {
    value: T;
}
/**
 * Lottie库来源
 */
export type LottieLibSource = 'built-in' | 'cdn' | 'external';
/**
 * Lottie库配置选项
 */
export interface LottieLibOptions {
    /**
     * Lottie库来源
     * - 'built-in': 使用内置的dotlottie-web库（默认）
     * - 'cdn': 从CDN加载
     * - 'external': 使用外部提供的库实例
     */
    source?: LottieLibSource;
    /**
     * 自定义CDN地址
     * 当source为'cdn'时使用
     * 默认使用 'https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-web/+esm'
     */
    cdnURL?: string;
    /**
     * 外部lottie库实例
     * 当source为'external'时使用
     */
    externalLib?: any;
}
/**
 * Lottie动画播放器选项
 */
export interface LottiePlayerOptions {
    /**
     * 容器元素或选择器或Vue ref
     * 动画将在此容器内渲染
     */
    container: HTMLElement | string | Ref<HTMLElement>;
    /**
     * 渲染模式
     * - 'svg': 使用SVG渲染(默认)，矢量质量最佳，适合大多数场景
     * - 'canvas': 使用Canvas渲染，性能好但不支持某些交互功能
     * - 'html': 使用HTML渲染，功能完整但性能较低
     */
    renderer?: LottieRenderMode;
    /** 是否循环播放动画 */
    loop?: boolean | number;
    /** 是否自动播放 */
    autoplay?: boolean;
    /** 初始播放速度 (1.0为正常速度) */
    speed?: number;
    /** 是否反向播放 */
    direction?: 1 | -1;
    /**
     * 动画质量 (0-1)
     * 更低的值可提高性能，但会降低精度
     */
    quality?: number;
    /** 初始帧，用于设置动画的起始位置 */
    initialSegment?: [number, number];
    /**
     * Lottie库配置选项
     * 控制如何加载lottie库
     */
    libOptions?: LottieLibOptions;
    /** 加载成功回调 */
    onLoad?: () => void;
    /** 播放完成回调 */
    onComplete?: () => void;
    /** 循环完成回调 */
    onLoopComplete?: () => void;
    /** 帧绘制回调 */
    onFrame?: (frame: number) => void;
    /** 播放开始回调 */
    onPlay?: () => void;
    /** 播放暂停回调 */
    onPause?: () => void;
    /** 播放停止回调 */
    onStop?: () => void;
    /** 错误回调 */
    onError?: (error: Error) => void;
    /** 销毁回调 */
    onDestroy?: () => void;
}
/**
 * Lottie动画播放器接口
 */
export interface LottiePlayer {
    /** 加载动画 */
    load(source: string | object): Promise<void>;
    /** 播放动画 */
    play(): void;
    /** 暂停动画 */
    pause(): void;
    /** 停止动画（回到起始帧） */
    stop(): void;
    /** 跳转到指定帧 */
    goToFrame(frame: number): void;
    /** 跳转到并播放 */
    goToAndPlay(frame: number): void;
    /** 跳转到并停止 */
    goToAndStop(frame: number): void;
    /** 设置播放速度 */
    setSpeed(speed: number): void;
    /** 设置播放方向 (1: 正向, -1: 反向) */
    setDirection(direction: 1 | -1): void;
    /** 设置循环 */
    setLoop(loop: boolean | number): void;
    /** 获取当前帧 */
    getCurrentFrame(): number;
    /** 获取总帧数 */
    getTotalFrames(): number;
    /** 获取动画时长(毫秒) */
    getDuration(): number;
    /** 获取动画播放状态 */
    getState(): LottiePlayerState;
    /** 是否正在播放 */
    isPlaying(): boolean;
    /** 设置动画段落 */
    setSegment(startFrame: number, endFrame: number): void;
    /**
     * 设置动画品质
     * @param quality 值在0-1之间，1为最高品质
     */
    setQuality(quality: number): void;
    /** 获取动画实例对象 */
    getAnimationInstance(): any;
    /** 调整动画尺寸 */
    resize(): void;
    /** 销毁动画，释放资源 */
    destroy(): void;
}
/**
 * 创建Lottie动画播放器
 * @param options 播放器选项
 * @returns Lottie动画播放器对象
 * @example
 * ```typescript
 * // 创建Lottie播放器（使用内置库 - 默认）
 * const lottiePlayer = await createLottiePlayer({
 *   container: '#animation-container',
 *   renderer: 'svg',
 *   loop: true,
 *   autoplay: true
 * });
 *
 * // 使用Vue ref作为容器
 * const animContainer = ref<HTMLElement | null>(null);
 * const lottiePlayer = await createLottiePlayer({
 *   container: animContainer,
 *   renderer: 'svg',
 *   loop: true
 * });
 *
 * // 使用自定义外部lottie库
 * import customLottieLib from 'custom-lottie-lib';
 * const lottiePlayer = await createLottiePlayer({
 *   container: '#animation-container',
 *   libOptions: {
 *     source: 'external',
 *     externalLib: customLottieLib
 *   }
 * });
 *
 * // 或者使用CDN加载
 * const lottiePlayer = await createLottiePlayer({
 *   container: '#animation-container',
 *   libOptions: {
 *     source: 'cdn',
 *     cdnURL: 'https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-web/+esm'
 *   }
 * });
 *
 * // 加载动画
 * await lottiePlayer.load('https://assets.lottiefiles.com/packages/lf20_UJNc2t.json');
 *
 * // 控制动画
 * lottiePlayer.pause();
 * lottiePlayer.setSpeed(2.0);
 * lottiePlayer.play();
 * ```
 */
export declare function createLottiePlayer(options: LottiePlayerOptions): Promise<LottiePlayer>;
/**
 * 简易加载并播放Lottie动画的快捷方法
 * @param url Lottie JSON文件URL或动画数据对象
 * @param container 容器元素、选择器或Vue ref
 * @param options 额外选项
 * @returns Lottie动画播放器对象
 * @example
 * ```typescript
 * // 快速加载并播放Lottie动画 (使用内置库 - 默认)
 * const player = await playLottie(
 *   'https://assets.lottiefiles.com/packages/lf20_UJNc2t.json',
 *   '#animation-container',
 *   { loop: true, speed: 1.5 }
 * );
 *
 * // 使用Vue ref作为容器
 * const animContainer = ref<HTMLElement | null>(null);
 * const player = await playLottie(
 *   'https://assets.lottiefiles.com/packages/lf20_UJNc2t.json',
 *   animContainer,
 *   { loop: true }
 * );
 * ```
 */
export declare function playLottie(url: string | object, container: HTMLElement | string | Ref<HTMLElement>, options?: Partial<Omit<LottiePlayerOptions, 'container'>>): Promise<LottiePlayer>;
export {};