@shijiu/jsview-vue 2.1.200 → 2.1.340-test.0

package/utils/JsViewVueWidget/JsvSpriteAnim/JsvSpriteAnim.vue

@@ -5,421 +5,453 @@
  *          spriteInfo {object}  (必需)精灵图配置信息
  *               { frames: [
  *                   {
- *                       source:{w,h},
- *                       target:{w,h},
+ *                       source:{x, y, w, h},
+ *                       target:{x, y, w, h},
  *                   },
  *                   ...
  *                 ],
  *                 meta:{w,h}
  *               }
- *      viewSize {object}  (必需){w:0, h:0}
+ *      viewSize {object}  (可选){w:0, h:0}, 从SpriteInfo中提炼的最大子图内容显示尺寸
  *      imageUrl {string}  (必需)图片地址，另外，为了减小无效的解析处理，规定只有image的URL变更时才重新解析spriteInfo
  *      duration {float}  (动图必需)动图的时间
  *      onAnimEnd {function} 动图结束回调
  *      autostart {string} 启动动图，默认none,
- *                 传入为bool类型时，兼容老版本：true为start、false为none
- *                 自动启动模式：start:精灵图自动启动，结束后显示第一帧内容、
- *                             end:精灵图自动启动，结束后显示最后一帧内容，
+ *                 自动启动模式：true/start:精灵图自动启动
  *                             none：不自动启动
- *      loop {string或number} 动图的循环次数 infinite/数字，默认为infinite
- *      spriteName {string} 动图的名称，默认为null
+ *      loop {string或number} 动图的循环次数 infinite/数字，默认为单次
  *      controller {SpriteController} 控制动图start,stop的对象
  *
- *  SpriteController: 面向对象类，精灵图动作控制器
+ *  SpriteController/或者本组件的ref: 面向对象类，精灵图动作控制器
  *      功能函数：(参数说明见函数本体)
  *          start()
  *              功能: 启动精灵图动画
- *          stop(end_frame)
+ *              参数表:
+ *                indexArray : 帧数组/"all", 展示帧的序列 
+ *                endFrame : 取值"start"/"end", 动画的结束帧内容 
+ *                duration : 单次生效, 临时覆盖prop中设置的duration
+ *                loopSet : 单次生效, 临时覆盖prop中设置的loop, 次数或者infinite 
+ *                animateEnd : 单次回调, 另外prop的onAnimEnd仍然会触发
+ *
+ *          stop()
  *              功能: 停止精灵图动画，可选择静止在第一帧或最后一帧
+ *              参数表:
+ *                index : 目标帧index/"start"/"end" 
  -->
- <script setup>
- import { getKeyFramesGroup } from '../../JsViewVueTools/JsvDynamicKeyFrames.js'
- import { reactive, shallowRef, onUnmounted, watch } from 'vue';
- import {getsAnimationToken} from "./sAnimationToken.js"
- 
- const _getTransformInfo = (source_obj, target_obj, canvas_width, canvas_height) => {
-     const result = { csw: 1, csh: 1, cx: 0, cy: 0, sw: 1, sh: 1, x: 0, y: 0 };
- 
-     // Clip在Canvas div之内，以Canvas为基准进行缩放和平移
-     // 图形左上角远离原点后再缩放，所以需要进行缩放补偿
-     const clip_scale_w = target_obj.w / canvas_width;
-     const clip_scale_h = target_obj.h / canvas_height;
-     result.csw = clip_scale_w;
-     result.csh = clip_scale_h;
-     result.cx = target_obj.x / clip_scale_w;
-     result.cy = target_obj.y / clip_scale_h;
- 
-     // Image在Clip div之内，所以以Clip为基准进行缩放和平移, 对clip的缩放进行反处理以还原尺寸
-     // 将子图左上角对齐原点后再缩放，所以x,y不需要进行举例缩放补偿
-     result.sw = source_obj.w / target_obj.w / clip_scale_w;
-     result.sh = source_obj.h / target_obj.h / clip_scale_h;
-     result.x = -source_obj.x;
-     result.y = -source_obj.y;
- 
-     return result;
- }
- 
- const _createTransformStyle = (w_scale, h_scale, x, y) => {
-     let output = "";
-     output = `${output}scale3d(${parseFloat(w_scale).toPrecision(5)},${parseFloat(h_scale).toPrecision(5)},1) `
-         + `translate3d(${parseFloat(x).toPrecision(5)}px,${parseFloat(y).toPrecision(5)}px,0)`;
-     return output;
- }
- 
- const props = defineProps({
-     spriteInfo: Object,
-     viewSize: Object,
-     imageUrl: String,
-     duration: Number,
-     onAnimEnd: Function,
-     autostart: [Boolean, String],
-     loop: [String, Number],
-     spriteName: String,
-     controller: Object,
- })
- 
- 
- let stopFrame = shallowRef("start");
- let TRANSFORM_ORIGIN_LEFT_TOP = shallowRef("left top")
- let keyFrameNames = reactive({
-     clip: null,
-     image: null,
-     valid: false
- });
- let frozeFrameCache = reactive({
-     clipStyle: {},
-     transStyle: {},
-     imageStyle: {
-         backgroundImage: null,
-     }
- });
- let animateFrameCache = reactive({
-     clipStyle: {},
-     transStyle: {},
-     imageStyle: {
-         backgroundImage: null,
-     },
-     clipAnimName: null,
-     imageAnimName: null,
- });
- let keyFrameStyleSheet = getKeyFramesGroup(null);
- let innerId = shallowRef(0);
- let stopped = shallowRef(false);
- let spriteDuration = shallowRef(props.duration);
- let blinkAnim = shallowRef(null);
- let blinkAnimCache = reactive({});
- 
- const _removeKeyFrame = (names_array) => {
-     if (keyFrameStyleSheet) {
-         keyFrameStyleSheet.removeMultiRules(names_array);
-     }
- }
- 
- const _clearExpiredKeyFrames = () => {
-     if (keyFrameNames.valid) {
-         _removeKeyFrame([keyFrameNames.clip, keyFrameNames.image]);
-         keyFrameNames.valid = false;
-     }
- }
- 
- onUnmounted(() => {
-     _clearExpiredKeyFrames()
- })
- 
- const _getAnimNameBase = () => {
-     return props.spriteName ? props.spriteName : `sprite-anim-name-${getsAnimationToken()}`;
- }
- 
- const _updateFrozeFrameCache = (image_url, frame_info_list,
-     canvas_width, canvas_height,
-     source_width, source_height) => {
-     const cache = frozeFrameCache;
- 
-     const index = stopFrame.value === "start" ? 0 : frame_info_list.length - 1;
-     const tr = _getTransformInfo(
-         frame_info_list[index].source,
-         frame_info_list[index].target,
-         canvas_width,
-         canvas_height
-     );
- 
-     cache.clipStyle = {
-         transform: _createTransformStyle(tr.csw, tr.csh, tr.cx, tr.cy),
-         transformOrigin: TRANSFORM_ORIGIN_LEFT_TOP.value,
-         overflow: "hidden",
-         left: 0,
-         top: 0,
-         width: canvas_width,
-         height: canvas_height,
-     };
- 
-     cache.transStyle = {
-         transformOrigin: TRANSFORM_ORIGIN_LEFT_TOP.value,
-         transform: _createTransformStyle(tr.sw, tr.sh, tr.x, tr.y),
-         width: source_width,
-         height: source_height,
-     };
- 
-     cache.imageStyle = {
-         backgroundImage: image_url,
-         width: source_width,
-         height: source_height,
-     };
- }
- 
- const _updateAnimateFrameCache = (image_url, frame_info_list,
-     canvas_width, canvas_height,
-     source_width, source_height) => {
-     _clearExpiredKeyFrames();
- 
-     if (!frame_info_list) { return; }
-     const anim_name_base = _getAnimNameBase();
-     const frame_percent = 1 / (frame_info_list.length);
-     const anim_name_clip = `${anim_name_base}-clip`;
-     const anim_name_image = `${anim_name_base}-image`;
-     let image_keyframs = `@keyframes ${anim_name_image} {`;
-     let clip_keyframs = `@keyframes ${anim_name_clip} {`;
- 
-     for (let i = 0; i < frame_info_list.length + 1; i++) {
-         let item;
-         if (i !== frame_info_list.length) {
-             item = frame_info_list[i];
-         } else {
-             // 追加一个最后一帧以保证最后一帧可见
-             item = frame_info_list[frame_info_list.length - 1];
-         }
- 
-         // Header
-         let header;
-         if (i !== frame_info_list.length) {
-             header = `${parseFloat(frame_percent * i * 100).toFixed(2)}% {`;
-         } else {
-             header = '100% {';
-         }
-         image_keyframs += header;
-         clip_keyframs += header;
- 
-         if (item.source) {
-             const tr = _getTransformInfo(item.source, item.target, canvas_width, canvas_height);
-             const clip_trans = _createTransformStyle(tr.csw, tr.csh, tr.cx, tr.cy);
-             const image_trans = _createTransformStyle(tr.sw, tr.sh, tr.x, tr.y);
- 
-             let tr_str = "";
-             tr_str = `${tr_str}transform:${clip_trans};transform-origin:left top;`;
-             clip_keyframs += tr_str;
- 
-             tr_str = "";
-             tr_str = `${tr_str}transform:${image_trans};transform-origin:left top;`;
-             image_keyframs += tr_str;
-         }
- 
-         image_keyframs += '}';
-         clip_keyframs += '}';
-     }
- 
-     image_keyframs += '}';
-     clip_keyframs += '}';
- 
-     if (keyFrameStyleSheet) {
-         keyFrameStyleSheet.insertRule(image_keyframs);
-         keyFrameStyleSheet.insertRule(clip_keyframs);
- 
-         // 记录Keyframe设置，以便于界面关闭时进行清理
-         keyFrameNames.clip = anim_name_clip;
-         keyFrameNames.image = anim_name_image;
-         keyFrameNames.valid = true;
-     }
-     const cache = animateFrameCache;
- 
-     cache.clipAnimName = `${anim_name_base}-clip`;
-     cache.imageAnimName = `${anim_name_base}-image`;
- 
-     cache.clipStyle = {
-         overflow: "hidden",
-         width: canvas_width,
-         height: canvas_height,
-         transform: null, // 重置 transform，以免影响keyframe动画
-         transformOrigin: TRANSFORM_ORIGIN_LEFT_TOP.value,
-         animation: null, // 外部设置，需要时间和loop信息
-     };
- 
-     cache.transStyle = {
-         transform: null, // 重置 transform，以免影响keyframe动画
-         transformOrigin: TRANSFORM_ORIGIN_LEFT_TOP.value,
-         animation: null, // 外部设置，需要时间和loop信息
-         width: source_width,
-         height: source_height,
-     };
- 
-     cache.imageStyle = {
-         backgroundImage: image_url,
-         width: source_width,
-         height: source_height,
-     };
- }
- 
- const _IsAutoStart = () => {
-     let autoStart = false;
-     if (typeof props.autostart === "boolean") {
-         autoStart = props.autostart;
-     } if (typeof props.autostart === "string" && props.autostart !== "none") {
-         autoStart = true;
-     }
-     return autoStart;
- }
- 
- 
- const _AnalyzeProp = () => {
-     const used = props.controller && props.controller.Used;
-     if (props.spriteInfo.frames.length === 1 || (!used && !_IsAutoStart()) || stopped.value) {
-         // 单图模式
-         // 解析图片信息
-         _updateFrozeFrameCache(
-             props.imageUrl,
-             props.spriteInfo.frames,
-             props.viewSize.w,
-             props.viewSize.h,
-             props.spriteInfo.meta.size.w,
-             props.spriteInfo.meta.size.h
-         );
- 
-         return {
-             clipStyle: frozeFrameCache.clipStyle,
-             transStyle: frozeFrameCache.transStyle,
-             imageStyle: frozeFrameCache.imageStyle,
-         };
-     }
- 
- 
-     // 动画模式
-     if (animateFrameCache.imageStyle.backgroundImage !== props.imageUrl) {
-         // 解析图片信息
-         _updateAnimateFrameCache(
-             props.imageUrl,
-             props.spriteInfo.frames,
-             props.viewSize.w,
-             props.viewSize.h,
-             props.spriteInfo.meta.size.w,
-             props.spriteInfo.meta.size.h
-         );
-     }
- 
-     // 使用duration和loop信息更新动画设定
-     animateFrameCache.clipStyle.animation =
-         `${animateFrameCache.clipAnimName} ${spriteDuration.value}s steps(1,end) ${props.loop}`;
-     animateFrameCache.transStyle.animation =
-         `${animateFrameCache.imageAnimName} ${spriteDuration.value}s steps(1,end) ${props.loop}`;
- 
-     return {
-         clipStyle: animateFrameCache.clipStyle,
-         transStyle: animateFrameCache.transStyle,
-         imageStyle: animateFrameCache.imageStyle,
-     };
- }
- let transform_style = reactive(_AnalyzeProp());
- 
- watch(props, (n, o) => {
-     transform_style = _AnalyzeProp();
- })
- const onAnimEndDelegate = () => {
-     // 在onAnimEnd之前进行Stop，以防onAnimEnd内部继续发生别的操作
-     if (props.onAnimEnd) {
-         props.onAnimEnd();
-     }
- }
- 
- const onBlinkAnimEnd = () => {
-     // 在onAnimEnd之前进行Stop，以防onAnimEnd内部继续发生别的操作
-     blinkAnim.value = null;
- }
- 
- const op = {
-     start: (end_frame, duration) => {
-         if (props.spriteInfo.frames && props.spriteInfo.frames.length === 1) {
-             return;
-         }
-         innerId.value += 1;
-         stopped.value = false;
-         spriteDuration.value = duration || props.duration;
-         stopFrame.value = end_frame || stopFrame.value;
-     },
-     stop: (end_frame) => {
-         if (props.spriteInfo.frames && props.spriteInfo.frames.length === 1) {
-             return;
-         }
-         stopped.value = true;
-         stopFrame.value = end_frame || stopFrame.value;
-     },
-     blink: (alphas, duration, ease, delay, repeat) => {
-         // 注意：比较数组是否相同仅在此场景下使用toString，其他场景
-         if (!blinkAnimCache
-             || (blinkAnimCache.alphas.toString() !== alphas.toString()
-                 || blinkAnimCache.duration !== duration
-                 || blinkAnimCache.ease !== ease
-                 || blinkAnimCache.delay !== delay
-                 || blinkAnimCache.repeat !== repeat)) {
-             const anim_name_base = _getAnimNameBase();
-             const anim_name_blink = `${anim_name_base}-blink`;
-             let image_keyframs = `@keyframes ${anim_name_blink} {`;
-             const frame_percent = 1 / (alphas.length);
-             for (let i = 0; i < alphas.length; i++) {
-                 const alpha = alphas[i];
-                 let header;
-                 if (i !== alphas.length - 1) {
-                     header = `${parseFloat(frame_percent * i * 100).toFixed(2)}% {`;
-                 } else {
-                     header = '100% {';
-                 }
-                 image_keyframs += header;
- 
-                 if (alpha) {
-                     const tr_str = ` opacity:${alpha};`;
-                     image_keyframs += tr_str;
-                 }
- 
-                 image_keyframs += '}';
-                 image_keyframs += "\n";
-             }
-             image_keyframs += '}';
-             if (keyFrameStyleSheet) {
-                 keyFrameStyleSheet.insertRule(image_keyframs);
-             }
-             blinkAnimCache = {
-                 alphas,
-                 duration,
-                 ease,
-                 delay,
-                 repeat,
-                 blinkAnimName: anim_name_blink
-             };
-         }
- 
-         // 参数格式化
-         ease = ease || "";
-         delay = delay || 0;
-         repeat = (repeat === -1) ? "infinite" : (repeat || 1);
- 
-         const animName = `${blinkAnimCache.blinkAnimName} ${duration}s ${ease} ${delay}s ${repeat}`;
-         blinkAnim.value = animName;
-         stopped.value = true;
-     }
- 
- };
- //TODO:
- props.controller?._setSpriteImg(op);
- </script>
-  
- <template>
-     <div id="canvas">
-         <div id="clip" :style="{ ...transform_style.clipStyle }" :key="innerId">
-             <div id="trans" :style="{ ...transform_style.transStyle }" @animationend="onAnimEndDelegate" :key="innerId">
-                 <div id="image" :style="{ ...transform_style.imageStyle, animation: blinkAnim }" :key="innerId"
-                     @animationend="onBlinkAnimEnd"></div>
-             </div>
-         </div>
-     </div>
- </template>
-  
- <style scoped>
- @keyframes sprite-tag {}
- </style>
+<script setup>
+import { reactive, shallowRef, onUnmounted, watch, defineExpose } from "vue";
+import * as FBuilder from "./FrameBuidler";
+
+const props = defineProps({
+  spriteInfo: Object,
+  viewSize: Object,
+  imageUrl: String,
+  duration: { type: Number, default: 1 },
+  onAnimEnd: Function,
+  autostart: { type: [Boolean, String], default: false },
+  loop: { type: [String, Number], default: "" },
+  controller: Object,
+  spriteName: String, // 废弃(Deprecated)
+});
+
+// ******** 内部状态 ********
+let innerId = shallowRef(0);
+let spriteDuration = shallowRef(props.duration);
+let apiStartEndCallback = null;
+let canvasSize = { width: 0, height: 0 };
+// 直接影响div的做step动画的style
+let transformStyle = {
+  clipStyle: shallowRef({}),
+  transStyle: shallowRef({}),
+  imageStyle: shallowRef({}),
+};
+// 静态图的缓存
+let staticFrameCachedInfo = null;
+// 动态图的缓存
+let animFrameCachedInfo = null;
+// watch时的比较缓存
+let cachedProps = {
+  spriteInfo: props.spriteInfo,
+};
+
+// ******** private function ********
+const _IsAutoStart = () => {
+  let autoStart = false;
+  if (typeof props.autostart === "boolean") {
+    autoStart = props.autostart;
+  }
+  if (typeof props.autostart === "string" && props.autostart !== "none") {
+    autoStart = true;
+  }
+  return autoStart;
+};
+// 创建静态图
+const _BuildStaticFrame = (targetIndex) => {
+  if (!staticFrameCachedInfo) {
+    // 初始化静态图缓存
+    staticFrameCachedInfo = {
+      props: {
+        frameIndex: undefined,
+      },
+      result: null,
+    };
+  }
+
+  if (
+    staticFrameCachedInfo.result == null ||
+    staticFrameCachedInfo.props.frameIndex != targetIndex
+  ) {
+    // 缓存需要变化时，重算单图信息
+    let framesLength = props.spriteInfo.frames.length;
+    if (targetIndex < 0 || targetIndex >= framesLength) {
+      console.error(
+        `Error: static out of range idx=${targetIndex} len=${framesLength}`
+      );
+      targetIndex = 0;
+    }
+
+    // 解析图片信息
+    let spriteInfo = FBuilder.newFrozeFrame(
+      props.imageUrl,
+      props.spriteInfo.frames,
+      targetIndex,
+      canvasSize.width,
+      canvasSize.height,
+      props.spriteInfo.meta.size.w,
+      props.spriteInfo.meta.size.h
+    );
+
+    staticFrameCachedInfo.props.frameIndex = targetIndex;
+    staticFrameCachedInfo.result = spriteInfo;
+  }
+
+  return staticFrameCachedInfo.result;
+};
+// 创建动图
+const _BuildAnimateFrame = (indexArray) => {
+  if (props.spriteInfo.frames == 1) {
+    // 单帧内容，始终使用静态图
+    return _BuildStaticFrame(0);
+  }
+
+  if (!animFrameCachedInfo) {
+    // 初始化动态图缓存
+    animFrameCachedInfo = {
+      props: {
+        indexArray: "all",
+      },
+      result: null,
+    };
+  }
+
+  let arrayMatch = true;
+  if (animFrameCachedInfo.result == null) {
+    arrayMatch = false;
+  } else {
+    // 遍历比较indexArray
+    let originArray = animFrameCachedInfo.props.indexArray;
+    if (indexArray != originArray) {
+      if (typeof indexArray == "string" || typeof originArray == "string") {
+        // String区别则必定为不同
+        arrayMatch = false;
+      }
+      if (indexArray.length == originArray.length) {
+        for (let i = 0; i < indexArray.length; i++) {
+          if (indexArray[i] != originArray[i]) {
+            arrayMatch = false;
+            break;
+          }
+        }
+      } else {
+        arrayMatch = false;
+      }
+    }
+  }
+
+  if (!arrayMatch) {
+    // 解析图片信息
+    let newFramesArray;
+    if (indexArray == "all") {
+      // 全序列
+      newFramesArray = props.spriteInfo.frames;
+    } else {
+      newFramesArray = [];
+      let lastFrameIndex = 0;
+      let framesLength = props.spriteInfo.frames.length;
+      for (const frameIndex of indexArray) {
+        let targetIndex = frameIndex;
+        if (frameIndex < 0 || frameIndex >= framesLength) {
+          console.warn(`out of range ${frameIndex} of len=${framesLength}`);
+          targetIndex = lastFrameIndex; // 使用上一帧
+        }
+        newFramesArray.push(props.spriteInfo.frames[targetIndex]);
+      }
+    }
+
+    if (animFrameCachedInfo.result != null) {
+      // 清理残留的内容
+      FBuilder.expireAnimates(animFrameCachedInfo.result);
+      animFrameCachedInfo.result = null;
+    }
+
+    let spriteInfo = FBuilder.newAnimateFrames(
+      props.imageUrl,
+      newFramesArray,
+      canvasSize.width,
+      canvasSize.height,
+      props.spriteInfo.meta.size.w,
+      props.spriteInfo.meta.size.h
+    );
+
+    animFrameCachedInfo.props.indexArray = indexArray;
+    animFrameCachedInfo.result = spriteInfo;
+  }
+
+  return animFrameCachedInfo.result;
+};
+// 设置给div
+const _ApplySpriteInfo = (spriteInfo) => {
+  transformStyle.clipStyle.value = spriteInfo.clipStyle;
+  transformStyle.transStyle.value = spriteInfo.transStyle;
+  transformStyle.imageStyle.value = spriteInfo.imageStyle;
+  innerId.value += 1; // 通过key触发控制体刷新
+};
+
+// 重置内容处理
+const _OnReset = () => {
+  let spriteInfo;
+  if (_IsAutoStart()) {
+    // 启动动画
+    spriteInfo = _BuildAnimateFrame("all");
+    // 注入animation属性
+    spriteInfo.clipStyle.animation = `${spriteInfo.clipKeyFrameName} ${spriteDuration.value}s steps(1,end) ${props.loop}`;
+    spriteInfo.transStyle.animation = `${spriteInfo.transKeyFrameName} ${spriteDuration.value}s steps(1,end) ${props.loop}`;
+  } else {
+    // 展示静图
+    spriteInfo = _BuildStaticFrame(0);
+  }
+  _ApplySpriteInfo(spriteInfo);
+
+  // 更新缓存
+  cachedProps.spriteInfo = props.spriteInfo;
+};
+
+// ******** 初始化处理 ********
+// 获取viewSize
+if (props.viewSize) {
+  canvasSize.width = props.viewSize.w;
+  canvasSize.height = props.viewSize.h;
+} else {
+  // 从frame中提取canvasSize
+  let max_width = 0;
+  let max_height = 0;
+  for (let i = 0; i < props.spriteInfo.frames.length; i++) {
+    const target = props.spriteInfo.frames[i].target;
+    const sprite_with = target.x + target.w;
+    const sprite_height = target.y + target.h;
+    if (sprite_with > max_width) {
+      max_width = sprite_with;
+    }
+    if (sprite_height > max_height) {
+      max_height = sprite_height;
+    }
+  }
+  canvasSize.width = max_width;
+  canvasSize.height = max_height;
+}
+
+// 注册prop变化的内容重置
+watch(props, (newProps) => {
+  // 属性变化重置缓存
+  if (newProps.spriteInfo != cachedProps.spriteInfo) {
+    console.log("Sprite reset for spriteInfo changed");
+    _OnReset();
+  }
+});
+
+// 首次启动处理
+_OnReset();
+
+let blinkAnim = shallowRef(null);
+let blinkAnimCache = reactive({});
+
+onUnmounted(() => {
+  if (animFrameCachedInfo?.result != null) {
+    // 清理残留的内容
+    FBuilder.expireAnimates(animFrameCachedInfo.result);
+    animFrameCachedInfo.result = null;
+  }
+});
+
+const onAnimEndDelegate = () => {
+  // 在onAnimEnd之前进行Stop，以防onAnimEnd内部继续发生别的操作
+  if (props.onAnimEnd) {
+    props.onAnimEnd();
+  }
+
+  // 一次性临时回调
+  if (apiStartEndCallback) {
+    let cb = apiStartEndCallback;
+    apiStartEndCallback = null;
+    cb();
+  }
+};
+
+const onBlinkAnimEnd = () => {
+  // 在onAnimEnd之前进行Stop，以防onAnimEnd内部继续发生别的操作
+  blinkAnim.value = null;
+};
+
+const op = {
+  start: (
+    indexArray /* 帧数组/"all" */,
+    endFrame /* 取值"start"/"end" */,
+    duration /* 覆盖prop中设置的duration */,
+    loopSet /* 覆盖prop中设置的loop */,
+    animateEnd /* 单次回调 */
+  ) => {
+    if (props.spriteInfo.frames && props.spriteInfo.frames.length === 1) {
+      console.error(
+        `Error: start failed for frames not enough len=${props.spriteInfo.frames.length}`
+      );
+      return;
+    }
+
+    // 规范化入参
+    if (!indexArray) {
+      indexArray = "all"; // 默认为全展示
+    }
+    if (!loopSet) {
+      loopSet = "";
+    }
+    if (!duration) {
+      duration = props.duration;
+    }
+
+    // 设置回调处理
+    apiStartEndCallback = () => {
+      // 控制结束帧
+      let endIndex = 0;
+      if (indexArray instanceof Array) {
+        endIndex =
+          endFrame == "start"
+            ? indexArray[0]
+            : indexArray[indexArray.length - 1];
+      } else {
+        endIndex = endFrame == "start" ? 0 : props.spriteInfo.frames.length - 1;
+      }
+      let endSpriteInfo = _BuildStaticFrame(endIndex);
+      _ApplySpriteInfo(endSpriteInfo);
+
+      if (animateEnd) {
+        animateEnd();
+      }
+    };
+
+    let spriteInfo = _BuildAnimateFrame(indexArray);
+    // 注入animation属性
+    spriteInfo.clipStyle.animation = `${spriteInfo.clipKeyFrameName} ${duration}s steps(1,end) ${loopSet}`;
+    spriteInfo.transStyle.animation = `${spriteInfo.transKeyFrameName} ${duration}s steps(1,end) ${loopSet}`;
+
+    // 设置界面
+    _ApplySpriteInfo(spriteInfo);
+  },
+  stop: (index /* 目标帧index/"start"/"end" */) => {
+    // 清理start临时处理
+    apiStartEndCallback = null;
+
+    let targetIndex;
+    if (typeof index == "undefined") {
+      targetIndex = 0; // 默认停止在第一帧
+    } else if (typeof index == "string") {
+      // 停在首帧或者最后一帧
+      targetIndex = index == "start" ? 0 : props.spriteInfo.frames.length - 1;
+    } else {
+      targetIndex = index;
+    }
+
+    let spriteInfo = _BuildStaticFrame(targetIndex);
+    _ApplySpriteInfo(spriteInfo);
+  },
+
+  // 含有透明度的transform变化
+  blink: (alphas, duration, ease, delay, repeat) => {
+    // TODO: 暂时不做alpha变化的需求
+    // 注意：比较数组是否相同仅在此场景下使用toString，其他场景
+    // if (
+    //   !blinkAnimCache ||
+    //   blinkAnimCache.alphas.toString() !== alphas.toString() ||
+    //   blinkAnimCache.duration !== duration ||
+    //   blinkAnimCache.ease !== ease ||
+    //   blinkAnimCache.delay !== delay ||
+    //   blinkAnimCache.repeat !== repeat
+    // ) {
+    //   const anim_name_base = _getAnimNameBase();
+    //   const anim_name_blink = `${anim_name_base}-blink`;
+    //   let image_keyframs = `@keyframes ${anim_name_blink} {`;
+    //   const frame_percent = 1 / alphas.length;
+    //   for (let i = 0; i < alphas.length; i++) {
+    //     const alpha = alphas[i];
+    //     let header;
+    //     if (i !== alphas.length - 1) {
+    //       header = `${parseFloat(frame_percent * i * 100).toFixed(2)}% {`;
+    //     } else {
+    //       header = "100% {";
+    //     }
+    //     image_keyframs += header;
+    //     if (alpha) {
+    //       const tr_str = ` opacity:${alpha};`;
+    //       image_keyframs += tr_str;
+    //     }
+    //     image_keyframs += "}";
+    //     image_keyframs += "\n";
+    //   }
+    //   image_keyframs += "}";
+    //   if (keyFrameStyleSheet) {
+    //     keyFrameStyleSheet.insertRule(image_keyframs);
+    //   }
+    //   blinkAnimCache = {
+    //     alphas,
+    //     duration,
+    //     ease,
+    //     delay,
+    //     repeat,
+    //     blinkAnimName: anim_name_blink,
+    //   };
+    // }
+    // // 参数格式化
+    // ease = ease || "";
+    // delay = delay || 0;
+    // repeat = repeat === -1 ? "infinite" : repeat || 1;
+    // const animName = `${blinkAnimCache.blinkAnimName} ${duration}s ${ease} ${delay}s ${repeat}`;
+    // blinkAnim.value = animName;
+    // stopped.value = true;
+  },
+};
+
+// 兼容老版本的control控制处理
+props.controller?._setSpriteImg(op);
+
+defineExpose(op);
+</script>
+
+<template>
+  <div id="clip" :style="transformStyle.clipStyle.value" :key="innerId">
+    <div
+      id="trans"
+      :style="transformStyle.transStyle.value"
+      @animationend="onAnimEndDelegate"
+    >
+      <div
+        id="image"
+        :style="{ ...transformStyle.imageStyle.value, animation: blinkAnim }"
+        @animationend="onBlinkAnimEnd"
+      ></div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+@keyframes sprite-tag {
+}
+</style>