pixuireactcomponents 1.5.59 → 1.5.60

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pixuireactcomponents",
-    "version": "1.5.59",
+    "version": "1.5.60",
     "description": "pixui react components",
     "main": "index.js",
     "sideEffects": false,

package/src/components/react/app/frameAnimation/FrameAnimation.d.ts

@@ -1,28 +1,58 @@
 import { h } from 'preact';
 /**
+ * 帧动画组件
  *
  * @param rootId 根节点id
  * @param rootClassName 根节点className
  * @param totalTime 动画总时长
  * @param width 组件宽度
  * @param height 组件高度
- * @param srcArr 图片url数组
+ * @param srcArr 图片 url 数组
  * @param onShow 每一帧显示时的回调
  * @param onFinish 动画结束时的回调
- * @param preloadCount 预加载节点的数量
+ * @param preloadCount 预加载节点的数量 (最少 3)
  * @param loop 是否循环播放
  * @param showLastFrame 播放结束后是否显示最后一帧
+ * @param cRef 外部组件引用（暴露 seek(frameIndex:number) 方法）
  */
-export declare let FrameAnimation: (props: {
-    rootId?: string | undefined;
-    rootClassName?: string | undefined;
+export interface FrameAnimationHandle {
+    /** 跳转到指定帧（从 0 开始计数） */
+    seek: (frameIndex: number) => void;
+    /** 开始播放（从当前已显示帧继续） */
+    play: () => void;
+    /** 暂停播放（不清理预加载） */
+    pause: () => void;
+}
+export interface FrameAnimationProps {
+    rootId?: string;
+    rootClassName?: string;
+    /** 动画总时长（毫秒） */
     totalTime: number;
+    /** 组件宽度，如 "500px" */
     width: string;
+    /** 组件高度，如 "300px" */
     height: string;
-    srcArr: string[];
-    onShow?: ((nowframe: number) => void) | undefined;
-    onFinish?: (() => void) | undefined;
-    preloadCount?: number | undefined;
-    loop?: boolean | undefined;
-    showLastFrame?: boolean | undefined;
-}) => h.JSX.Element;
+    /** 每帧图片 URL 数组（与 spriteClassArr 二选一） */
+    srcArr?: string[];
+    /** 每帧对应的样式类名数组（className），在样式中指定 background-image 等 */
+    spriteClassArr?: string[];
+    /** 每一帧显示的回调 */
+    onShow?: (nowframe: number) => void;
+    /** 动画结束回调 */
+    onFinish?: () => void;
+    /** 预加载节点数量，最少 3 */
+    preloadCount?: number;
+    /** 是否循环播放 */
+    loop?: boolean;
+    /** 播放结束后是否显示最后一帧 */
+    showLastFrame?: boolean;
+    /** 播放范围起始帧 (包含) */
+    rangeStart?: number;
+    /** 播放范围结束帧 (包含) */
+    rangeEnd?: number;
+    /** 外部组件引用，用于调用 seek 方法 */
+    cRef?: any;
+    /** 是否在初始化后自动播放（默认 true） */
+    autoplay?: boolean;
+}
+export declare const FrameAnimation: (props: FrameAnimationProps) => h.JSX.Element;

package/src/components/react/app/frameAnimation/FrameAnimation.js

@@ -1,96 +1,255 @@
 import { useEffect, useRef } from 'preact/hooks';
 import { createRef, h } from 'preact';
-// let requestAnimationFrame = (f) => {
-//     return setTimeout(f, 300);
-// };
-/**
- *
- * @param rootId 根节点id
- * @param rootClassName 根节点className
- * @param totalTime 动画总时长
- * @param width 组件宽度
- * @param height 组件高度
- * @param srcArr 图片url数组
- * @param onShow 每一帧显示时的回调
- * @param onFinish 动画结束时的回调
- * @param preloadCount 预加载节点的数量
- * @param loop 是否循环播放
- * @param showLastFrame 播放结束后是否显示最后一帧
- */
 export var FrameAnimation = function (props) {
-    var _a, _b;
+    // ------------------------------ 参数与前置处理 ------------------------------
     props.preloadCount = Math.max(props.preloadCount || 3, 3);
-    var totalTime = props.totalTime, width = props.width, height = props.height, srcArr = props.srcArr, onShow = props.onShow, preloadCount = props.preloadCount, loop = (_a = props.loop, _a === void 0 ? false : _a), onFinish = props.onFinish, showLastFrame = (_b = props.showLastFrame, _b === void 0 ? true : _b), rootId = props.rootId, rootClassName = props.rootClassName;
+    var totalTime = props.totalTime, width = props.width, height = props.height, _a = props.srcArr, srcArr = _a === void 0 ? [] : _a, spriteClassArr = props.spriteClassArr, onShow = props.onShow, preloadCount = props.preloadCount, _b = props.loop, loop = _b === void 0 ? false : _b, onFinish = props.onFinish, _c = props.showLastFrame, showLastFrame = _c === void 0 ? true : _c, rootId = props.rootId, rootClassName = props.rootClassName, rangeStart = props.rangeStart, rangeEnd = props.rangeEnd, cRef = props.cRef, _d = props.autoplay, autoplay = _d === void 0 ? true : _d;
+    // 模式判定：sprite 模式或图片模式
+    var useSprite = Array.isArray(spriteClassArr) && spriteClassArr.length > 0;
+    var frameCount = useSprite ? spriteClassArr.length : srcArr.length;
+    // 每帧耗时（保护除零）
+    var frameTime = frameCount > 0 ? totalTime / frameCount : 0;
+    // ------------------------------ 播放范围处理 ------------------------------
+    var startIndex = Math.max(0, Math.min(rangeStart != null ? rangeStart : 0, frameCount - 1));
+    var endIndex = Math.max(startIndex, Math.min(rangeEnd != null ? rangeEnd : frameCount - 1, frameCount - 1));
+    var rangeLen = endIndex - startIndex + 1;
+    // ------------------------------ DOM Ref 初始化 ------------------------------
     var cRefArr = useRef(Array.from({ length: preloadCount }, function () { return createRef(); })).current;
-    var imgEleArr = useRef(Array.from({ length: preloadCount }, function (v, i) {
-        return h("img", { ref: cRefArr[i], src: srcArr[i], style: { position: 'absolute', visibility: 'hidden', width: width, height: height } });
-    })).current;
+    var imgEleArr = useRef(Array.from({ length: preloadCount }, function (_, i) { return (h("img", { ref: cRefArr[i], src: srcArr[i], style: { position: 'absolute', visibility: 'hidden', width: width, height: height } })); })).current;
+    // sprite 模式所需的 div 预加载节点
+    var dRefArr = useRef(Array.from({ length: preloadCount }, function () { return createRef(); })).current;
+    var spriteEleArr = useRef(Array.from({ length: preloadCount }, function (_, i) { return (h("div", { ref: dRefArr[i], style: { position: 'absolute', visibility: 'hidden', width: width, height: height } })); })).current;
+    // ------------------------------ 状态引用 ------------------------------
+    var startTimeRef = useRef(0); // 当前动画起始时间
+    var showedFrameRef = useRef(0); // 已经展示的帧序号
+    var isPlayingRef = useRef(autoplay !== false); // 播放状态（仅初始化受 autoplay 影响）
+    var rootRef = useRef(null); // 根容器，用于判断是否真的卸载
+    // ------------------------------ seek 功能实现 ------------------------------
+    var seek = function (frameIndex) {
+        console.log('frame seek !!', frameIndex);
+        if (frameCount <= 0)
+            return;
+        if (frameIndex < 0 || frameIndex >= frameCount)
+            return;
+        // 1. 直接更新可见帧及预加载
+        var bufferLen = useSprite ? dRefArr.length : cRefArr.length;
+        var nowArrIndex = bufferLen > 0 ? frameIndex % bufferLen : 0;
+        if (useSprite) {
+            dRefArr.forEach(function (ref, i) {
+                var divNode = ref.current;
+                if (!divNode)
+                    return;
+                if (i === nowArrIndex) {
+                    divNode.style.visibility = 'visible';
+                    divNode.className = spriteClassArr[frameIndex];
+                }
+                else {
+                    divNode.style.visibility = 'hidden';
+                    var offset = (i + dRefArr.length - nowArrIndex) % dRefArr.length;
+                    var offsetFrame = startIndex + ((frameIndex - startIndex + offset) % rangeLen);
+                    divNode.className = spriteClassArr[offsetFrame];
+                }
+            });
+        }
+        else {
+            cRefArr.forEach(function (ref, i) {
+                var imgNode = ref.current;
+                if (!imgNode)
+                    return;
+                if (i === nowArrIndex) {
+                    imgNode.style.visibility = 'visible';
+                    imgNode.src = srcArr[frameIndex];
+                }
+                else {
+                    imgNode.style.visibility = 'hidden';
+                    var offset = (i + cRefArr.length - nowArrIndex) % cRefArr.length;
+                    var offsetFrame = startIndex + ((frameIndex - startIndex + offset) % rangeLen);
+                    imgNode.src = srcArr[offsetFrame];
+                }
+            });
+        }
+        // 2. 回调 & 状态同步
+        showedFrameRef.current = frameIndex;
+        onShow && onShow(frameIndex);
+        // 3. 调整起始时间，让主循环从下一帧继续
+        startTimeRef.current = Date.now() - frameIndex * frameTime;
+        if (isPlayingRef.current) {
+            nextFrame(startTimeRef.current, frameIndex);
+        }
+    };
+    // 开始/暂停控制
+    var play = function () {
+        if (isPlayingRef.current)
+            return;
+        isPlayingRef.current = true;
+        // 从当前帧继续播放
+        startTimeRef.current = Date.now() - showedFrameRef.current * frameTime;
+        nextFrame(startTimeRef.current, showedFrameRef.current);
+    };
+    var pause = function () {
+        // 不清理任何节点或预加载，仅停止后续调度
+        isPlayingRef.current = false;
+    };
+    // 对外暴露方法
+    if (cRef) {
+        cRef.current = {
+            seek: seek,
+            play: play,
+            pause: pause,
+        };
+    }
+    // ------------------------------ 主循环初始化 ------------------------------
     useEffect(function () {
-        var startTime = Date.now();
-        var onrFrameTime = totalTime / srcArr.length;
-        //设置第一帧
-        cRefArr[0].current.style.visibility = 'visible';
-        nextFrame(startTime, onrFrameTime, 0);
-    }, []);
-    //循环修改imgEleArr的src和visibility实现帧动画,，记录上一帧的序号防止跳帧
-    var nextFrame = function (startTime, v, showedFrame) {
-        var nowTime = Date.now();
-        //该显示第几帧
-        var nowFrame = Math.floor((nowTime - startTime) / v);
-        //使用第几个img元素
-        var nowArrIndex = nowFrame % preloadCount;
-        var showedArrIndex = showedFrame % preloadCount;
-        // console.log('nextFrame', nowFrame, 'nowArrIndex', nowArrIndex, 'nowFrame', nowFrame);
-        if (!cRefArr[0].current) {
-            //组件已经被卸载
-            onFinish && onFinish();
+        // 范围或模式或数据变化时，保证重新初始化并对齐到合法帧
+        var target = Math.max(startIndex, Math.min(showedFrameRef.current, endIndex));
+        seek(target);
+        // 卸载时无需特殊处理：nextFrame 在组件卸载时会检测到 ref 已为 null 并停止调度
+    }, [startIndex, endIndex, spriteClassArr, srcArr, useSprite]);
+    // 尺寸变化时，同步更新已挂载节点尺寸
+    useEffect(function () {
+        cRefArr.forEach(function (ref) {
+            if (ref.current) {
+                ref.current.style.width = width;
+                ref.current.style.height = height;
+            }
+        });
+        dRefArr.forEach(function (ref) {
+            if (ref.current) {
+                ref.current.style.width = width;
+                ref.current.style.height = height;
+            }
+        });
+    }, [width, height]);
+    // 时长或帧数变化时，若在播放中，重设起始时间以尽量平滑过渡
+    useEffect(function () {
+        if (!isPlayingRef.current)
+            return;
+        var v = frameCount > 0 ? totalTime / frameCount : 0;
+        if (v > 0) {
+            startTimeRef.current = Date.now() - showedFrameRef.current * v;
+        }
+    }, [totalTime, frameCount]);
+    // 循环开关变化时，重启主循环以应用最新逻辑
+    useEffect(function () {
+        if (!isPlayingRef.current)
+            return;
+        var v = frameCount > 0 ? totalTime / frameCount : 0;
+        startTimeRef.current = v > 0 ? Date.now() - showedFrameRef.current * v : Date.now();
+        nextFrame(startTimeRef.current, showedFrameRef.current);
+    }, [loop]);
+    // ------------------------------ 帧动画主循环 ------------------------------
+    var nextFrame = function (startTime, showedFrame) {
+        // 如果这不是最新的一轮动画，直接忽略
+        if (startTime !== startTimeRef.current)
+            return;
+        // 暂停状态下不再推进帧，也不调度下一轮
+        if (!isPlayingRef.current)
+            return;
+        var v = frameCount > 0 ? totalTime / frameCount : 0;
+        if (v <= 0)
             return;
+        var nowTime = Date.now();
+        var rawFrame = Math.floor((nowTime - startTime) / v); // 从动画开始以来的原始帧序号
+        // 计算在播放区间内的实际帧序号
+        var nowFrame = loop ? startIndex + ((((rawFrame - startIndex) % rangeLen) + rangeLen) % rangeLen) : rawFrame;
+        var bufferLen = useSprite ? dRefArr.length : cRefArr.length;
+        var nowArrIndex = bufferLen > 0 ? nowFrame % bufferLen : 0; // 使用第几个预加载元素
+        var showedArrIndex = bufferLen > 0 ? showedFrame % bufferLen : 0;
+        // 组件已卸载
+        if (useSprite) {
+            if (!dRefArr[0].current) {
+                // 若根容器仍在，说明正处于模式切换的挂载窗口期，等待下一帧重试
+                if (rootRef.current) {
+                    requestAnimationFrame(function () {
+                        if (isPlayingRef.current)
+                            nextFrame(startTime, showedFrame);
+                    });
+                    return;
+                }
+                onFinish && onFinish();
+                return;
+            }
+        }
+        else {
+            if (!cRefArr[0].current) {
+                if (rootRef.current) {
+                    requestAnimationFrame(function () {
+                        if (isPlayingRef.current)
+                            nextFrame(startTime, showedFrame);
+                    });
+                    return;
+                }
+                onFinish && onFinish();
+                return;
+            }
         }
-        if (nowFrame >= srcArr.length) {
+        // 动画结束（非循环情况下）
+        if (!loop && nowFrame > endIndex) {
             onFinish && onFinish();
-            if (!loop) {
-                cRefArr.forEach(function (ref, i) {
+            if (useSprite) {
+                dRefArr.forEach(function (ref) {
+                    if (ref.current)
+                        ref.current.style.visibility = 'hidden';
+                });
+                if (showLastFrame && dRefArr[0].current) {
+                    dRefArr[0].current.className = spriteClassArr[endIndex];
+                    dRefArr[0].current.style.visibility = 'visible';
+                }
+            }
+            else {
+                cRefArr.forEach(function (ref) {
                     ref.current.style.visibility = 'hidden';
                 });
                 if (showLastFrame) {
-                    //跳帧的话，最后一帧可能不是最后一张图片，设为最后一张图片
-                    cRefArr[0].current.src = srcArr[srcArr.length - 1];
+                    cRefArr[0].current.src = srcArr[endIndex];
                     cRefArr[0].current.style.visibility = 'visible';
                 }
-                return;
             }
-            //重置img标签的 src 和 visibility
-            cRefArr.forEach(function (ref, i) {
-                ref.current.style.visibility = 'hidden';
-                ref.current.src = srcArr[i];
-            });
-            startTime = Date.now();
-            cRefArr[0].current.style.visibility = 'visible';
-            requestAnimationFrame(function () {
-                nextFrame(startTime, v, 0);
-            });
             return;
         }
+        // 帧更新
         if (nowFrame !== showedFrame) {
-            cRefArr[nowArrIndex].current.style.visibility = 'visible';
-            //隐藏上一帧
-            cRefArr[showedArrIndex].current.style.visibility = 'hidden';
-            //可能跳帧，在所有其他的元素上预加载
-            cRefArr.forEach(function (ref, i) {
-                if (i !== nowArrIndex) {
-                    var offset = (i + cRefArr.length - nowArrIndex) % cRefArr.length;
-                    var offsetFrame = (nowFrame + offset) % srcArr.length;
-                    if (ref.current.src !== srcArr[offsetFrame]) {
-                        ref.current.src = srcArr[offsetFrame];
+            if (useSprite) {
+                dRefArr[nowArrIndex].current.style.visibility = 'visible';
+                dRefArr[showedArrIndex].current.style.visibility = 'hidden';
+                // 可能出现跳帧，为其余 div 做预加载（通过 className 触发 background 图片加载）
+                dRefArr.forEach(function (ref, i) {
+                    if (i !== nowArrIndex) {
+                        var offset = (i + dRefArr.length - nowArrIndex) % dRefArr.length;
+                        var offsetFrame = startIndex + ((nowFrame - startIndex + offset) % rangeLen);
+                        if (ref.current.className !== spriteClassArr[offsetFrame]) {
+                            ref.current.className = spriteClassArr[offsetFrame];
+                        }
                     }
-                }
-            });
+                });
+            }
+            else {
+                cRefArr[nowArrIndex].current.style.visibility = 'visible';
+                cRefArr[showedArrIndex].current.style.visibility = 'hidden';
+                // 可能出现跳帧，为其余 img 做预加载
+                cRefArr.forEach(function (ref, i) {
+                    if (i !== nowArrIndex) {
+                        var offset = (i + cRefArr.length - nowArrIndex) % cRefArr.length;
+                        var offsetFrame = startIndex + ((nowFrame - startIndex + offset) % rangeLen);
+                        if (ref.current.src !== srcArr[offsetFrame]) {
+                            ref.current.src = srcArr[offsetFrame];
+                        }
+                    }
+                });
+            }
             showedFrame = nowFrame;
+            showedFrameRef.current = nowFrame;
             onShow && onShow(nowFrame);
+            var curnode = useSprite ? dRefArr[nowArrIndex].current : cRefArr[nowArrIndex].current;
+            console.log('curnode', curnode === null || curnode === void 0 ? void 0 : curnode.getBoundingClientRect());
+        }
+        // 下一帧（仅在播放状态下调度）
+        if (isPlayingRef.current) {
+            requestAnimationFrame(function () {
+                nextFrame(startTime, showedFrame);
+            });
         }
-        requestAnimationFrame(function () {
-            nextFrame(startTime, v, showedFrame);
-        });
     };
-    return (h("div", { style: { width: width, height: height }, id: rootId, className: rootClassName }, imgEleArr));
+    // ------------------------------ 组件渲染 ------------------------------
+    return (h("div", { ref: rootRef, style: { width: width, height: height }, id: rootId, className: rootClassName }, useSprite ? spriteEleArr : imgEleArr));
 };