从 ion-slides 迁移到 Swiper.js

正在寻找 ion-slides？

ion-slides 在 v6.0.0 中已弃用，并在 v7.0.0 中删除。我们建议直接使用 Swiper.js 库。迁移过程在下面详细介绍。

如果您需要一个现代触控滑块组件，我们推荐使用 Swiper.js。本指南将介绍如何在您的 Ionic Framework 应用程序中设置 Swiper for Vue。它还将介绍您可能需要从 ion-slides 迁移到官方 Swiper Vue 集成的任何迁移信息。

注意

Swiper 的 Vue 组件将在 Swiper 的未来版本中删除，并由 Swiper Element 替换。但是，本指南展示了如何迁移到 Vue 组件，因为它在撰写本文时提供了最稳定的体验。

使用 Swiper 的 Vue 组件**不是**使用 Swiper.js 与 Ionic Framework 所必需的。

入门

首先，更新到最新版本的 Ionic

npm install @ionic/vue@latest @ionic/vue-router@latest

我们建议升级到 Vue CLI 5 以获得与 Swiper 的更好兼容性

vue upgrade --next

完成之后，在您的项目中安装 Swiper 依赖项

npm install swiper@latest

有风格地滑动

接下来，我们需要导入基本 Swiper 样式。我们还将导入 Ionic 提供的样式，这将使我们能够使用与 ion-slides 相同的 CSS 变量来定制 Swiper 样式。

我们建议在使用 Swiper 的组件中导入样式。这确保了样式仅在需要时加载

<script>
  import { defineComponent } from 'vue';

  import 'swiper/css';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    ...
  });
</script>

注意

导入 @ionic/vue/css/ionic-swiper.css **不是**使用 Swiper.js 与 Ionic 所必需的。此文件用于与 ion-slides 组件的向后兼容性，如果您可以不使用样式表中提供的 CSS 变量，则可以安全地省略它。

更新选择器

之前，我们可以定位 ion-slides 和 ion-slide 来应用任何自定义样式。这些样式块的内容保持不变，但我们需要更新选择器。以下是从 ion-slides 到 Swiper Vue 的选择器更改列表

ion-slides 选择器	Swiper 选择器
ion-slides	.swiper
ion-slide	.swiper-slide

预处理器（可选）

对于使用 SCSS 或 Less 样式的开发人员，Swiper 还为这些文件提供导入。

对于 Less 样式，将 Swiper 导入路径中的 css 替换为 less

import 'swiper/less';
import '@ionic/vue/css/ionic-swiper.css';

对于 SCSS 样式，将 Swiper 导入路径中的 css 替换为 scss

import 'swiper/scss';
import '@ionic/vue/css/ionic-swiper.css';

使用组件

Swiper 导出两个组件：Swiper 和 SwiperSlide。Swiper 组件相当于 IonSlides，而 SwiperSlide 组件相当于 IonSlide。

这些组件是从 swiper/vue 导入的，并提供给您的 Vue 组件

<template>
  <ion-page>
    <ion-content>
      <swiper>
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>

<script>
  import { defineComponent } from 'vue';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage } from '@ionic/vue';

  import 'swiper/css';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: {
      Swiper,
      SwiperSlide,
      IonContent,
      IonPage,
    },
  });
</script>

使用模块

默认情况下，Swiper for Vue 不会导入任何额外的模块。要使用导航或分页等模块，您需要先导入它们。

ion-slides 自动包含了分页、滚动条、自动播放、键盘和缩放模块。本指南的这一部分将向您展示如何安装这些模块。

首先，我们需要从 swiper 包中导入模块及其相应的 CSS 文件

<template>
  <ion-page>
    <ion-content>
      <swiper>
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/autoplay';
  import 'swiper/css/keyboard';
  import 'swiper/css/pagination';
  import 'swiper/css/scrollbar';
  import 'swiper/css/zoom';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
  });
</script>

从这里，我们需要通过在 swiper 组件上使用 modules 属性来向 Swiper 提供这些模块

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/autoplay';
  import 'swiper/css/keyboard';
  import 'swiper/css/pagination';
  import 'swiper/css/scrollbar';
  import 'swiper/css/zoom';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [Autoplay, Keyboard, Pagination, Scrollbar, Zoom],
      };
    },
  });
</script>

最后，我们可以通过使用适当的属性来打开这些功能

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules" :autoplay="true" :keyboard="true" :pagination="true" :scrollbar="true" :zoom="true">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/autoplay';
  import 'swiper/css/keyboard';
  import 'swiper/css/pagination';
  import 'swiper/css/scrollbar';
  import 'swiper/css/zoom';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [Autoplay, Keyboard, Pagination, Scrollbar, Zoom],
      };
    },
  });
</script>

注意

查看 https://swiper.js.cn/vue#usage 获取模块的完整列表。

IonicSlides 模块

对于 ion-slides，Ionic 自动定制了数十个 Swiper 属性。这使得在移动设备上滑动时体验流畅。我们建议使用 IonicSlides 模块来确保在直接使用 Swiper 时也设置了这些属性。但是，使用此模块**不是**在 Ionic 中使用 Swiper.js 所必需的。

建议您查看由 IonicSlides 设置的属性，并确定您想定制哪些属性。

我们可以通过从 @ionic/vue 导入 IonicSlides 模块，并将其作为 modules 数组中的最后一项传递进来，来安装 IonicSlides 模块

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules" :autoplay="true" :keyboard="true" :pagination="true" :scrollbar="true" :zoom="true">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage, IonicSlides } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/autoplay';
  import 'swiper/css/keyboard';
  import 'swiper/css/pagination';
  import 'swiper/css/scrollbar';
  import 'swiper/css/zoom';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [Autoplay, Keyboard, Pagination, Scrollbar, Zoom, IonicSlides],
      };
    },
  });
</script>

注意

IonicSlides 模块必须是数组中的最后一个模块。这将使它能够自动定制分页、滚动条、缩放等模块的设置。

属性

Swiper 选项作为道具直接提供给 <swiper> 组件，而不是通过 ion-slides 中的 options 对象提供。

假设在一个使用 ion-slides 的应用程序中，我们设置了 slidesPerView 和 loop 选项

<template>
  <ion-slides :options="{ slidesPerView: 3, loop: true }">
    <ion-slide>Slide 1</ion-slide>
    <ion-slide>Slide 2</ion-slide>
    <ion-slide>Slide 3</ion-slide>
  </ion-slides>
</template>

要迁移，我们将把这些选项从 options 对象中移出，并作为属性直接放在 <swiper> 组件上

<template>
  <swiper :slides-per-view="3" :loop="true">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
  </swiper>
</template>

以下是从 ion-slides 到 Swiper Vue 的属性更改的完整列表

名称	注释
options	将每个选项设置为 <swiper> 组件上的直接属性。
mode	对于基于模式的不同样式，您可以在 CSS 中使用 .ios .swiper 或 .md .swiper 来定位幻灯片。
pager	改为使用 pagination 属性。需要安装分页模块。
scrollbar	您可以继续使用 scrollbar 属性，只需先确保安装滚动条模块。

注意

所有在 Swiper Vue 中可用的属性都可以在 https://swiper.js.cn/vue#swiper-props 中找到。

事件

由于 Swiper 组件不是由 Ionic Framework 提供的，因此事件名称将不会有 ionSlide 前缀。

假设在一个使用 ion-slides 的应用程序中，我们使用了 ionSlideDidChange 事件

<template>
  <ion-slides @ionSlideDidChange="onSlideChange">
    <ion-slide>Slide 1</ion-slide>
    <ion-slide>Slide 2</ion-slide>
    <ion-slide>Slide 3</ion-slide>
  </ion-slides>
</template>

要迁移，我们将更改事件的名称为 slideChange

<template>
  <swiper @slideChange="onSlideChange">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
  </swiper>
</template>

以下是从 ion-slides 到 Swiper Vue 的事件名称更改的完整列表

ion-slides 事件	Swiper 事件
ionSlideWillChange	slideChangeTransitionStart
ionSlideDidChange	slideChangeTransitionEnd
ionSlideDoubleTap	doubleTap
ionSlideDrag	sliderMove
ionSlideNextStart	slideNextTransitionStart
ionSlideNextEnd	slideNextTransitionEnd
ionSlidePrevStart	slidePrevTransitionStart
ionSlidePrevEnd	slidePrevTransitionEnd
ionSlideReachStart	reachBeginning
ionSlideReachEnd	reachEnd
ionSlideTap	tap
ionSlideTouchStart	touchStart
ionSlideTouchEnd	touchEnd
ionSlideTransitionStart	transitionStart
ionSlideTransitionEnd	transitionEnd
ionSlidesDidLoad	init

注意

Swiper Vue 中所有可用的事件可以在 https://swiper.js.cn/vue#swiper-events 中找到。

方法

大多数方法已被移除，取而代之的是直接访问 <swiper> 的属性。此外，调用方法时不再需要先访问 $el。

访问这些属性可能会很棘手，因为您希望访问 Swiper 实例本身的属性，而不是您的 Vue 组件。为此，我们建议通过 @swiper 事件处理程序获取对 Swiper 实例的引用

<template>
  <swiper @swiper="setSwiperInstance"> ... </swiper>
</template>

<script>
  import { defineComponent, ref } from 'vue';
  export default defineComponent({
    ...,
    setup() {
      const slides = ref();
      const setSwiperInstance = (swiper: any) => {
        slides.value = swiper;
      }
      return { setSwiperInstance };
    }
  });
</script>

从这里开始，如果您想访问 Swiper 实例上的属性，您可以访问 slides.value。例如，如果您想检查 isBeginning 属性，您可以执行以下操作：slides.value.isBeginning。确保 slides.value 首先已定义！

以下是将 ion-slides 迁移到 Swiper Vue 时方法更改的完整列表

ion-slides 方法	注释
getActiveIndex()	改用 activeIndex 属性。
getPreviousIndex()	改用 previousIndex 属性。
getSwiper()	使用 @swiper 获取对 Swiper 实例的引用。请参见上面的示例。
isBeginning()	改用 isBeginning 属性。
isEnd()	改用 isEnd 属性。
length()	改用 slides 属性。（即 swiperRef.slides.length）
lockSwipeToNext()	改用 allowSlideNext 属性。
lockSwipeToPrev()	改用 allowSlidePrev 属性。
lockSwipes()	改用 allowSlideNext、allowSlidePrev 和 allowTouchMove 属性。
startAutoplay()	改用 autoplay 属性。
stopAutoplay()	改用 autoplay 属性。

效果

如果您使用的是 Cube 或 Fade 等效果，您可以像我们对其他模块所做的那样安装它们。在本例中，我们将使用淡入淡出效果。首先，我们将从 swiper 中导入 EffectFade 并将其提供在 modules 数组中

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { EffectFade } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage, IonicSlides } from '@ionic/vue';

  import 'swiper/css';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [EffectFade, IonicSlides],
      };
    },
  });
</script>

接下来，我们需要导入与效果关联的样式表

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { EffectFade } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage, IonicSlides } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/effect-fade';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [EffectFade, IonicSlides],
      };
    },
  });
</script>

之后，我们可以通过将 swiper 上的 effect 属性设置为 "fade" 来激活它

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules" effect="fade">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { EffectFade } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage, IonicSlides } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/effect-fade';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [EffectFade, IonicSlides],
      };
    },
  });
</script>

注意

有关 Swiper 中效果的更多信息，请参见 https://swiper.js.cn/vue#effects。

总结

现在您已经安装了 Swiper，您可以享受一套全新的 Swiper 功能。我们建议您从 Swiper Vue 简介 开始，然后参考 Swiper API 文档。

常见问题解答

在哪里可以找到此迁移的示例？

您可以在 https://github.com/ionic-team/slides-migration-samples 中找到一个包含 ion-slides 和等效 Swiper 用法的示例应用程序。

在哪里可以获得有关此迁移的帮助？

如果您在迁移过程中遇到问题，请在 Ionic 论坛 上发帖。

在哪里提交错误报告？

在打开问题之前，请考虑在 Swiper 讨论板 或 Ionic 论坛 上发帖，看看您的问题是否可以由社区解决。

如果您在使用 Swiper 库时遇到问题，新的错误应该提交到 Swiper 仓库：https://github.com/nolimits4web/swiper/issues

如果您在使用 IonicSlides 模块时遇到问题，新的错误应该提交到 Ionic Framework 仓库：https://github.com/ionic-team/ionic-framework/issues