@tarojs/components 4.0.5-alpha.6 → 4.0.5-alpha.9

package/dist/cjs/taro-swiper-core_2.cjs.entry.js

@@ -42,7 +42,10 @@ const Swiper = class {
     this.onAnimationFinish = index.createEvent(this, "animationfinish", 7);
     _Swiper_id.set(this, INSTANCE_ID++);
     _Swiper_source.set(this, '');
-    _Swiper_swiperResetting.set(this, false);
+    _Swiper_swiperResetting.set(this, false
+    // dom 变化是否由外部引起，因为 swiper 的循环模式也会引起 dom 的变化。如果不是由外部引起的 dom 变化，就不需要重新初始化 swiper
+    );
+    // dom 变化是否由外部引起，因为 swiper 的循环模式也会引起 dom 的变化。如果不是由外部引起的 dom 变化，就不需要重新初始化 swiper
     _Swiper_domChangeByOutSide.set(this, false);
     _Swiper_lastSwiperActiveIndex.set(this, 0);
     this.handleSwiperSizeDebounce = index$1.debounce(() => {
@@ -60,7 +63,16 @@ const Swiper = class {
         __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
       }
     }, 50);
+    this.reset = () => {
+      __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
+      __classPrivateFieldSet(this, _Swiper_lastSwiperActiveIndex, this.swiper.realIndex, "f");
+      this.swiper.destroy();
+      this.handleInit(true);
+      __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
+    };
+    // 下面为方法函数
     this.getSlidersList = () => this.el.querySelectorAll('taro-swiper-item-core:not(.swiper-slide-duplicate)') || [];
+    // 获取是否需要手动修复 loop 的条件
     this.getNeedFixLoop = () => {
       const margins = this.parseMargin();
       const hasMargin = margins.filter(Boolean).length > 0;
@@ -71,13 +83,6 @@ const Swiper = class {
       const [, nextMargin] = /^(\d+)px/.exec(this.nextMargin) || [];
       return [parseInt(previousMargin) || 0, parseInt(nextMargin) || 0];
     };
-    this.reset = () => {
-      __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
-      __classPrivateFieldSet(this, _Swiper_lastSwiperActiveIndex, this.swiper.realIndex, "f");
-      this.swiper.destroy();
-      this.handleInit(true);
-      __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
-    };
     this.swiperWrapper = undefined;
     this.swiper = undefined;
     this.isWillLoadCalled = false;
@@ -183,39 +188,38 @@ const Swiper = class {
       return;
     if (!newVal)
       return;
+    const beforeDomOperation = () => {
+      __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
+      // 如果是由于外部子节点的变化引起的 dom 变化，需要重新初始化 swiper。
+      // 在初dom操作之前，需要调用 loopDestroy，把子节点的顺序恢复
+      this.swiper.loopDestroy();
+      this.swiper.params.loop = false;
+    };
     this.el.appendChild = (newChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.appendChild(newChild);
     };
     this.el.insertBefore = (newChild, refChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.insertBefore(newChild, refChild);
     };
     this.el.replaceChild = (newChild, oldChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.replaceChild(newChild, oldChild);
     };
     this.el.removeChild = (oldChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.removeChild(oldChild);
     };
@@ -270,9 +274,10 @@ const Swiper = class {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const that = this;
     const options = Object.assign(Object.assign({ pagination: { el: `.taro-swiper-${__classPrivateFieldGet(this, _Swiper_id, "f")} > .swiper-container > .swiper-pagination` }, direction: vertical ? 'vertical' : 'horizontal', loop: circular, slidesPerView: slidesPerView, initialSlide: initialSlide, loopAdditionalSlides: loopAdditionalSlides, speed: duration, observeParents: true, observer: true, centeredSlides: centeredSlides, zoom: this.zoom }, effectsProps), { on: {
-        slideChangeTransitionEnd(e) {
-          if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f"))
+        changeTransitionEnd(e) {
+          if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f") || __classPrivateFieldGet(that, _Swiper_lastSwiperActiveIndex, "f") === this.realIndex)
             return;
+          __classPrivateFieldSet(that, _Swiper_lastSwiperActiveIndex, this.realIndex, "f");
           that.getNeedFixLoop() && e.loopFix();
           that.autoplay && e.autoplay.start();
           const currentItemId = that.getCurrentItemId(e);
@@ -283,10 +288,12 @@ const Swiper = class {
           });
           __classPrivateFieldSet(that, _Swiper_source, 'autoplay', "f");
         },
+        touchMove() {
+          __classPrivateFieldSet(that, _Swiper_source, 'touch', "f");
+        },
         slideChange(e) {
           if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f") || __classPrivateFieldGet(that, _Swiper_lastSwiperActiveIndex, "f") === this.realIndex)
             return;
-          __classPrivateFieldSet(that, _Swiper_lastSwiperActiveIndex, this.realIndex, "f");
           const currentItemId = that.getCurrentItemId(e);
           that.onChange.emit({
             current: this.realIndex,
@@ -308,6 +315,9 @@ const Swiper = class {
         },
         autoplay(e) {
           // Note: 修复 autoplay 时，切换到其他页面再切回来，autoplay 会停止的问题
+          // autoplay 会调用 slideTo 方法，里面会判断是否 animating，如果 animating 为 true，就会被 return
+          // 参考源码：https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/slide/slideTo.mjs#27 27行
+          // https://github.com/nolimits4web/swiper/blob/v11.1.0/src/modules/autoplay/autoplay.mjs
           e.animating = false;
           __classPrivateFieldSet(that, _Swiper_source, 'autoplay', "f");
         }
@@ -320,7 +330,10 @@ const Swiper = class {
       };
     }
     this.swiper = new SwiperJS__default['default'](`.taro-swiper-${__classPrivateFieldGet(this, _Swiper_id, "f")} > .swiper-container`, options);
-    //Note: 注释
+    // Note: 这里是拦截了 swiper 的 minTranslate 和 maxTranslate 方法，手动修复了 loop 模式下的 margin 问题
+    // 因为这两个属性会影响滑动到哪个位置进行 fixloop
+    // 可参考源码：https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/events/onTouchMove.mjs
+    // https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/loop/loopFix.mjs
     if (this.getNeedFixLoop()) {
       // @ts-ignore
       const minTranslate = this.swiper.minTranslate.bind(this.swiper);
@@ -341,7 +354,8 @@ const Swiper = class {
     }
     this.swiperWrapper = this.swiper.wrapperEl;
   }
-  //Note: 注释
+  // Note: loop 的时候添加 additionalSlides 可以避免循环的时候由于 loopFix 不及时，出现空白的问题。但是并不是 additionalSlides 越多越好，因为 additionalSlides 越多，如果 swiper-item 的数量不够，会导致出现 bug。
+  // 目前的策略是 swiper-item 的数量小于等于 5 时，不添加 additionalSlides，大于 5 小于等于 7 时，添加 1 个 additionalSlides，大于 7 时，添加 2 个 additionalSlides。
   getLoopAdditionalSlides() {
     const slidersLength = (this.getSlidersList()).length;
     if (!this.el || !this.getNeedFixLoop() || slidersLength < ONE_ADDITIONAL_SLIDES_THRESHOLD)

package/dist/collection/components/swiper/swiper.js

@@ -25,7 +25,10 @@ export class Swiper {
   constructor() {
     _Swiper_id.set(this, INSTANCE_ID++);
     _Swiper_source.set(this, '');
-    _Swiper_swiperResetting.set(this, false);
+    _Swiper_swiperResetting.set(this, false
+    // dom 变化是否由外部引起，因为 swiper 的循环模式也会引起 dom 的变化。如果不是由外部引起的 dom 变化，就不需要重新初始化 swiper
+    );
+    // dom 变化是否由外部引起，因为 swiper 的循环模式也会引起 dom 的变化。如果不是由外部引起的 dom 变化，就不需要重新初始化 swiper
     _Swiper_domChangeByOutSide.set(this, false);
     _Swiper_lastSwiperActiveIndex.set(this, 0);
     this.handleSwiperSizeDebounce = debounce(() => {
@@ -43,7 +46,16 @@ export class Swiper {
         __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
       }
     }, 50);
+    this.reset = () => {
+      __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
+      __classPrivateFieldSet(this, _Swiper_lastSwiperActiveIndex, this.swiper.realIndex, "f");
+      this.swiper.destroy();
+      this.handleInit(true);
+      __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
+    };
+    // 下面为方法函数
     this.getSlidersList = () => this.el.querySelectorAll('taro-swiper-item-core:not(.swiper-slide-duplicate)') || [];
+    // 获取是否需要手动修复 loop 的条件
     this.getNeedFixLoop = () => {
       const margins = this.parseMargin();
       const hasMargin = margins.filter(Boolean).length > 0;
@@ -54,13 +66,6 @@ export class Swiper {
       const [, nextMargin] = /^(\d+)px/.exec(this.nextMargin) || [];
       return [parseInt(previousMargin) || 0, parseInt(nextMargin) || 0];
     };
-    this.reset = () => {
-      __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
-      __classPrivateFieldSet(this, _Swiper_lastSwiperActiveIndex, this.swiper.realIndex, "f");
-      this.swiper.destroy();
-      this.handleInit(true);
-      __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
-    };
     this.swiperWrapper = undefined;
     this.swiper = undefined;
     this.isWillLoadCalled = false;
@@ -166,39 +171,38 @@ export class Swiper {
       return;
     if (!newVal)
       return;
+    const beforeDomOperation = () => {
+      __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
+      // 如果是由于外部子节点的变化引起的 dom 变化，需要重新初始化 swiper。
+      // 在初dom操作之前，需要调用 loopDestroy，把子节点的顺序恢复
+      this.swiper.loopDestroy();
+      this.swiper.params.loop = false;
+    };
     this.el.appendChild = (newChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.appendChild(newChild);
     };
     this.el.insertBefore = (newChild, refChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.insertBefore(newChild, refChild);
     };
     this.el.replaceChild = (newChild, oldChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.replaceChild(newChild, oldChild);
     };
     this.el.removeChild = (oldChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.removeChild(oldChild);
     };
@@ -253,9 +257,10 @@ export class Swiper {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const that = this;
     const options = Object.assign(Object.assign({ pagination: { el: `.taro-swiper-${__classPrivateFieldGet(this, _Swiper_id, "f")} > .swiper-container > .swiper-pagination` }, direction: vertical ? 'vertical' : 'horizontal', loop: circular, slidesPerView: slidesPerView, initialSlide: initialSlide, loopAdditionalSlides: loopAdditionalSlides, speed: duration, observeParents: true, observer: true, centeredSlides: centeredSlides, zoom: this.zoom }, effectsProps), { on: {
-        slideChangeTransitionEnd(e) {
-          if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f"))
+        changeTransitionEnd(e) {
+          if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f") || __classPrivateFieldGet(that, _Swiper_lastSwiperActiveIndex, "f") === this.realIndex)
             return;
+          __classPrivateFieldSet(that, _Swiper_lastSwiperActiveIndex, this.realIndex, "f");
           that.getNeedFixLoop() && e.loopFix();
           that.autoplay && e.autoplay.start();
           const currentItemId = that.getCurrentItemId(e);
@@ -266,10 +271,12 @@ export class Swiper {
           });
           __classPrivateFieldSet(that, _Swiper_source, 'autoplay', "f");
         },
+        touchMove() {
+          __classPrivateFieldSet(that, _Swiper_source, 'touch', "f");
+        },
         slideChange(e) {
           if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f") || __classPrivateFieldGet(that, _Swiper_lastSwiperActiveIndex, "f") === this.realIndex)
             return;
-          __classPrivateFieldSet(that, _Swiper_lastSwiperActiveIndex, this.realIndex, "f");
           const currentItemId = that.getCurrentItemId(e);
           that.onChange.emit({
             current: this.realIndex,
@@ -291,6 +298,9 @@ export class Swiper {
         },
         autoplay(e) {
           // Note: 修复 autoplay 时，切换到其他页面再切回来，autoplay 会停止的问题
+          // autoplay 会调用 slideTo 方法，里面会判断是否 animating，如果 animating 为 true，就会被 return
+          // 参考源码：https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/slide/slideTo.mjs#27 27行
+          // https://github.com/nolimits4web/swiper/blob/v11.1.0/src/modules/autoplay/autoplay.mjs
           e.animating = false;
           __classPrivateFieldSet(that, _Swiper_source, 'autoplay', "f");
         }
@@ -303,7 +313,10 @@ export class Swiper {
       };
     }
     this.swiper = new SwiperJS(`.taro-swiper-${__classPrivateFieldGet(this, _Swiper_id, "f")} > .swiper-container`, options);
-    //Note: 注释
+    // Note: 这里是拦截了 swiper 的 minTranslate 和 maxTranslate 方法，手动修复了 loop 模式下的 margin 问题
+    // 因为这两个属性会影响滑动到哪个位置进行 fixloop
+    // 可参考源码：https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/events/onTouchMove.mjs
+    // https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/loop/loopFix.mjs
     if (this.getNeedFixLoop()) {
       // @ts-ignore
       const minTranslate = this.swiper.minTranslate.bind(this.swiper);
@@ -324,7 +337,8 @@ export class Swiper {
     }
     this.swiperWrapper = this.swiper.wrapperEl;
   }
-  //Note: 注释
+  // Note: loop 的时候添加 additionalSlides 可以避免循环的时候由于 loopFix 不及时，出现空白的问题。但是并不是 additionalSlides 越多越好，因为 additionalSlides 越多，如果 swiper-item 的数量不够，会导致出现 bug。
+  // 目前的策略是 swiper-item 的数量小于等于 5 时，不添加 additionalSlides，大于 5 小于等于 7 时，添加 1 个 additionalSlides，大于 7 时，添加 2 个 additionalSlides。
   getLoopAdditionalSlides() {
     const slidersLength = (this.getSlidersList()).length;
     if (!this.el || !this.getNeedFixLoop() || slidersLength < ONE_ADDITIONAL_SLIDES_THRESHOLD)

package/dist/components/taro-swiper-core.js

@@ -32,7 +32,10 @@ const Swiper = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
     this.onAnimationFinish = createEvent(this, "animationfinish", 7);
     _Swiper_id.set(this, INSTANCE_ID++);
     _Swiper_source.set(this, '');
-    _Swiper_swiperResetting.set(this, false);
+    _Swiper_swiperResetting.set(this, false
+    // dom 变化是否由外部引起，因为 swiper 的循环模式也会引起 dom 的变化。如果不是由外部引起的 dom 变化，就不需要重新初始化 swiper
+    );
+    // dom 变化是否由外部引起，因为 swiper 的循环模式也会引起 dom 的变化。如果不是由外部引起的 dom 变化，就不需要重新初始化 swiper
     _Swiper_domChangeByOutSide.set(this, false);
     _Swiper_lastSwiperActiveIndex.set(this, 0);
     this.handleSwiperSizeDebounce = debounce(() => {
@@ -50,7 +53,16 @@ const Swiper = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
         __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
       }
     }, 50);
+    this.reset = () => {
+      __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
+      __classPrivateFieldSet(this, _Swiper_lastSwiperActiveIndex, this.swiper.realIndex, "f");
+      this.swiper.destroy();
+      this.handleInit(true);
+      __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
+    };
+    // 下面为方法函数
     this.getSlidersList = () => this.el.querySelectorAll('taro-swiper-item-core:not(.swiper-slide-duplicate)') || [];
+    // 获取是否需要手动修复 loop 的条件
     this.getNeedFixLoop = () => {
       const margins = this.parseMargin();
       const hasMargin = margins.filter(Boolean).length > 0;
@@ -61,13 +73,6 @@ const Swiper = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
       const [, nextMargin] = /^(\d+)px/.exec(this.nextMargin) || [];
       return [parseInt(previousMargin) || 0, parseInt(nextMargin) || 0];
     };
-    this.reset = () => {
-      __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
-      __classPrivateFieldSet(this, _Swiper_lastSwiperActiveIndex, this.swiper.realIndex, "f");
-      this.swiper.destroy();
-      this.handleInit(true);
-      __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
-    };
     this.swiperWrapper = undefined;
     this.swiper = undefined;
     this.isWillLoadCalled = false;
@@ -173,39 +178,38 @@ const Swiper = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
       return;
     if (!newVal)
       return;
+    const beforeDomOperation = () => {
+      __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
+      // 如果是由于外部子节点的变化引起的 dom 变化，需要重新初始化 swiper。
+      // 在初dom操作之前，需要调用 loopDestroy，把子节点的顺序恢复
+      this.swiper.loopDestroy();
+      this.swiper.params.loop = false;
+    };
     this.el.appendChild = (newChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.appendChild(newChild);
     };
     this.el.insertBefore = (newChild, refChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.insertBefore(newChild, refChild);
     };
     this.el.replaceChild = (newChild, oldChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.replaceChild(newChild, oldChild);
     };
     this.el.removeChild = (oldChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.removeChild(oldChild);
     };
@@ -260,9 +264,10 @@ const Swiper = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const that = this;
     const options = Object.assign(Object.assign({ pagination: { el: `.taro-swiper-${__classPrivateFieldGet(this, _Swiper_id, "f")} > .swiper-container > .swiper-pagination` }, direction: vertical ? 'vertical' : 'horizontal', loop: circular, slidesPerView: slidesPerView, initialSlide: initialSlide, loopAdditionalSlides: loopAdditionalSlides, speed: duration, observeParents: true, observer: true, centeredSlides: centeredSlides, zoom: this.zoom }, effectsProps), { on: {
-        slideChangeTransitionEnd(e) {
-          if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f"))
+        changeTransitionEnd(e) {
+          if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f") || __classPrivateFieldGet(that, _Swiper_lastSwiperActiveIndex, "f") === this.realIndex)
             return;
+          __classPrivateFieldSet(that, _Swiper_lastSwiperActiveIndex, this.realIndex, "f");
           that.getNeedFixLoop() && e.loopFix();
           that.autoplay && e.autoplay.start();
           const currentItemId = that.getCurrentItemId(e);
@@ -273,10 +278,12 @@ const Swiper = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
           });
           __classPrivateFieldSet(that, _Swiper_source, 'autoplay', "f");
         },
+        touchMove() {
+          __classPrivateFieldSet(that, _Swiper_source, 'touch', "f");
+        },
         slideChange(e) {
           if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f") || __classPrivateFieldGet(that, _Swiper_lastSwiperActiveIndex, "f") === this.realIndex)
             return;
-          __classPrivateFieldSet(that, _Swiper_lastSwiperActiveIndex, this.realIndex, "f");
           const currentItemId = that.getCurrentItemId(e);
           that.onChange.emit({
             current: this.realIndex,
@@ -298,6 +305,9 @@ const Swiper = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
         },
         autoplay(e) {
           // Note: 修复 autoplay 时，切换到其他页面再切回来，autoplay 会停止的问题
+          // autoplay 会调用 slideTo 方法，里面会判断是否 animating，如果 animating 为 true，就会被 return
+          // 参考源码：https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/slide/slideTo.mjs#27 27行
+          // https://github.com/nolimits4web/swiper/blob/v11.1.0/src/modules/autoplay/autoplay.mjs
           e.animating = false;
           __classPrivateFieldSet(that, _Swiper_source, 'autoplay', "f");
         }
@@ -310,7 +320,10 @@ const Swiper = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
       };
     }
     this.swiper = new SwiperJS(`.taro-swiper-${__classPrivateFieldGet(this, _Swiper_id, "f")} > .swiper-container`, options);
-    //Note: 注释
+    // Note: 这里是拦截了 swiper 的 minTranslate 和 maxTranslate 方法，手动修复了 loop 模式下的 margin 问题
+    // 因为这两个属性会影响滑动到哪个位置进行 fixloop
+    // 可参考源码：https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/events/onTouchMove.mjs
+    // https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/loop/loopFix.mjs
     if (this.getNeedFixLoop()) {
       // @ts-ignore
       const minTranslate = this.swiper.minTranslate.bind(this.swiper);
@@ -331,7 +344,8 @@ const Swiper = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
     }
     this.swiperWrapper = this.swiper.wrapperEl;
   }
-  //Note: 注释
+  // Note: loop 的时候添加 additionalSlides 可以避免循环的时候由于 loopFix 不及时，出现空白的问题。但是并不是 additionalSlides 越多越好，因为 additionalSlides 越多，如果 swiper-item 的数量不够，会导致出现 bug。
+  // 目前的策略是 swiper-item 的数量小于等于 5 时，不添加 additionalSlides，大于 5 小于等于 7 时，添加 1 个 additionalSlides，大于 7 时，添加 2 个 additionalSlides。
   getLoopAdditionalSlides() {
     const slidersLength = (this.getSlidersList()).length;
     if (!this.el || !this.getNeedFixLoop() || slidersLength < ONE_ADDITIONAL_SLIDES_THRESHOLD)

package/dist/esm/taro-swiper-core_2.entry.js

@@ -34,7 +34,10 @@ const Swiper = class {
     this.onAnimationFinish = createEvent(this, "animationfinish", 7);
     _Swiper_id.set(this, INSTANCE_ID++);
     _Swiper_source.set(this, '');
-    _Swiper_swiperResetting.set(this, false);
+    _Swiper_swiperResetting.set(this, false
+    // dom 变化是否由外部引起，因为 swiper 的循环模式也会引起 dom 的变化。如果不是由外部引起的 dom 变化，就不需要重新初始化 swiper
+    );
+    // dom 变化是否由外部引起，因为 swiper 的循环模式也会引起 dom 的变化。如果不是由外部引起的 dom 变化，就不需要重新初始化 swiper
     _Swiper_domChangeByOutSide.set(this, false);
     _Swiper_lastSwiperActiveIndex.set(this, 0);
     this.handleSwiperSizeDebounce = debounce(() => {
@@ -52,7 +55,16 @@ const Swiper = class {
         __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
       }
     }, 50);
+    this.reset = () => {
+      __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
+      __classPrivateFieldSet(this, _Swiper_lastSwiperActiveIndex, this.swiper.realIndex, "f");
+      this.swiper.destroy();
+      this.handleInit(true);
+      __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
+    };
+    // 下面为方法函数
     this.getSlidersList = () => this.el.querySelectorAll('taro-swiper-item-core:not(.swiper-slide-duplicate)') || [];
+    // 获取是否需要手动修复 loop 的条件
     this.getNeedFixLoop = () => {
       const margins = this.parseMargin();
       const hasMargin = margins.filter(Boolean).length > 0;
@@ -63,13 +75,6 @@ const Swiper = class {
       const [, nextMargin] = /^(\d+)px/.exec(this.nextMargin) || [];
       return [parseInt(previousMargin) || 0, parseInt(nextMargin) || 0];
     };
-    this.reset = () => {
-      __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
-      __classPrivateFieldSet(this, _Swiper_lastSwiperActiveIndex, this.swiper.realIndex, "f");
-      this.swiper.destroy();
-      this.handleInit(true);
-      __classPrivateFieldSet(this, _Swiper_swiperResetting, false, "f");
-    };
     this.swiperWrapper = undefined;
     this.swiper = undefined;
     this.isWillLoadCalled = false;
@@ -175,39 +180,38 @@ const Swiper = class {
       return;
     if (!newVal)
       return;
+    const beforeDomOperation = () => {
+      __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
+      // 如果是由于外部子节点的变化引起的 dom 变化，需要重新初始化 swiper。
+      // 在初dom操作之前，需要调用 loopDestroy，把子节点的顺序恢复
+      this.swiper.loopDestroy();
+      this.swiper.params.loop = false;
+    };
     this.el.appendChild = (newChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.appendChild(newChild);
     };
     this.el.insertBefore = (newChild, refChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.insertBefore(newChild, refChild);
     };
     this.el.replaceChild = (newChild, oldChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.replaceChild(newChild, oldChild);
     };
     this.el.removeChild = (oldChild) => {
       __classPrivateFieldSet(this, _Swiper_swiperResetting, true, "f");
       if (!__classPrivateFieldGet(this, _Swiper_domChangeByOutSide, "f") && this.circular) {
-        __classPrivateFieldSet(this, _Swiper_domChangeByOutSide, true, "f");
-        this.swiper.loopDestroy();
-        this.swiper.params.loop = false;
+        beforeDomOperation();
       }
       return newVal.removeChild(oldChild);
     };
@@ -262,9 +266,10 @@ const Swiper = class {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const that = this;
     const options = Object.assign(Object.assign({ pagination: { el: `.taro-swiper-${__classPrivateFieldGet(this, _Swiper_id, "f")} > .swiper-container > .swiper-pagination` }, direction: vertical ? 'vertical' : 'horizontal', loop: circular, slidesPerView: slidesPerView, initialSlide: initialSlide, loopAdditionalSlides: loopAdditionalSlides, speed: duration, observeParents: true, observer: true, centeredSlides: centeredSlides, zoom: this.zoom }, effectsProps), { on: {
-        slideChangeTransitionEnd(e) {
-          if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f"))
+        changeTransitionEnd(e) {
+          if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f") || __classPrivateFieldGet(that, _Swiper_lastSwiperActiveIndex, "f") === this.realIndex)
             return;
+          __classPrivateFieldSet(that, _Swiper_lastSwiperActiveIndex, this.realIndex, "f");
           that.getNeedFixLoop() && e.loopFix();
           that.autoplay && e.autoplay.start();
           const currentItemId = that.getCurrentItemId(e);
@@ -275,10 +280,12 @@ const Swiper = class {
           });
           __classPrivateFieldSet(that, _Swiper_source, 'autoplay', "f");
         },
+        touchMove() {
+          __classPrivateFieldSet(that, _Swiper_source, 'touch', "f");
+        },
         slideChange(e) {
           if (__classPrivateFieldGet(that, _Swiper_swiperResetting, "f") || __classPrivateFieldGet(that, _Swiper_lastSwiperActiveIndex, "f") === this.realIndex)
             return;
-          __classPrivateFieldSet(that, _Swiper_lastSwiperActiveIndex, this.realIndex, "f");
           const currentItemId = that.getCurrentItemId(e);
           that.onChange.emit({
             current: this.realIndex,
@@ -300,6 +307,9 @@ const Swiper = class {
         },
         autoplay(e) {
           // Note: 修复 autoplay 时，切换到其他页面再切回来，autoplay 会停止的问题
+          // autoplay 会调用 slideTo 方法，里面会判断是否 animating，如果 animating 为 true，就会被 return
+          // 参考源码：https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/slide/slideTo.mjs#27 27行
+          // https://github.com/nolimits4web/swiper/blob/v11.1.0/src/modules/autoplay/autoplay.mjs
           e.animating = false;
           __classPrivateFieldSet(that, _Swiper_source, 'autoplay', "f");
         }
@@ -312,7 +322,10 @@ const Swiper = class {
       };
     }
     this.swiper = new SwiperJS(`.taro-swiper-${__classPrivateFieldGet(this, _Swiper_id, "f")} > .swiper-container`, options);
-    //Note: 注释
+    // Note: 这里是拦截了 swiper 的 minTranslate 和 maxTranslate 方法，手动修复了 loop 模式下的 margin 问题
+    // 因为这两个属性会影响滑动到哪个位置进行 fixloop
+    // 可参考源码：https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/events/onTouchMove.mjs
+    // https://github.com/nolimits4web/swiper/blob/v11.1.0/src/core/loop/loopFix.mjs
     if (this.getNeedFixLoop()) {
       // @ts-ignore
       const minTranslate = this.swiper.minTranslate.bind(this.swiper);
@@ -333,7 +346,8 @@ const Swiper = class {
     }
     this.swiperWrapper = this.swiper.wrapperEl;
   }
-  //Note: 注释
+  // Note: loop 的时候添加 additionalSlides 可以避免循环的时候由于 loopFix 不及时，出现空白的问题。但是并不是 additionalSlides 越多越好，因为 additionalSlides 越多，如果 swiper-item 的数量不够，会导致出现 bug。
+  // 目前的策略是 swiper-item 的数量小于等于 5 时，不添加 additionalSlides，大于 5 小于等于 7 时，添加 1 个 additionalSlides，大于 7 时，添加 2 个 additionalSlides。
   getLoopAdditionalSlides() {
     const slidersLength = (this.getSlidersList()).length;
     if (!this.el || !this.getNeedFixLoop() || slidersLength < ONE_ADDITIONAL_SLIDES_THRESHOLD)