从 ion-slides 迁移到 Swiper.js

ion-slides?寻找

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

¥ion-slides was deprecated in v6.0.0 and removed in v7.0.0. We recommend using the Swiper.js library directly. The migration process is detailed below.

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

¥We recommend Swiper.js if you need a modern touch slider component. This guide will go over how to get Swiper for Vue set up in your Ionic Framework application. It will also go over any migration information you may need to move from ion-slides to the official Swiper Vue integration.

注意

Swiper 的 Vue 组件将在 Swiper 的未来版本中删除，并以 滑动元素 作为替代品。然而，本指南展示了如何迁移到 Vue 组件，因为它在撰写本文时提供了最稳定的体验。

¥Swiper's Vue component is set to be removed in a future release of Swiper, with Swiper Element as the replacement. However, this guide shows how to migrate to the Vue component because it provides the most stable experience at the time of writing.

将 Swiper.js 与 Ionic Framework 一起使用不需要使用 Swiper 的 Vue 组件。

¥Using Swiper's Vue component is not required to use Swiper.js with Ionic Framework.

新手上路

¥Getting Started

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

¥First, update to the latest version of Ionic:

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

我们建议升级到 Vue CLI 5，以便更好地兼容 Swiper：

¥We recommend upgrading to Vue CLI 5 for better compatibility with Swiper:

vue upgrade --next

完成后，在你的项目中安装 Swiper 依赖：

¥Once that is done, install the Swiper dependency in your project:

npm install swiper@latest

样式滑动

¥Swiping with Style

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

¥Next, we need to import the base Swiper styles. We are also going to import the styles that Ionic provides which will let us customize the Swiper styles using the same CSS Variables that we used with ion-slides.

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

¥We recommend importing the styles in the component in which Swiper is being used. This ensures that the styles are only loaded when needed:

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

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

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

注意

将 Swiper.js 与 Ionic 结合使用时不需要导入 @ionic/vue/css/ionic-swiper.css。该文件用于与 ion-slides 组件向后兼容，如果你不想使用样式表中提供的 CSS 变量，可以安全地忽略该文件。

¥Importing @ionic/vue/css/ionic-swiper.css is not required to use Swiper.js with Ionic. This files is used for backward-compatibility with the ion-slides component and can be safely omitted if you prefer not to use the CSS Variables provided in the stylesheet.

更新选择器

¥Updating Selectors

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

¥Previously, we were able to target ion-slides and ion-slide to apply any custom styling. The contents of those style blocks remain the same, but we need to update the selectors. Below is a list of selector changes when going from ion-slides to Swiper Vue:

ion-slides 选择器	滑动选择器
ion-slides	.swiper
ion-slide	.swiper-slide

预处理器（可选）

¥Pre-processors (optional)

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

¥For developers using SCSS or Less styles, Swiper also provides imports for those files.

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

¥For Less styles, replace css with less in the Swiper import path:

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

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

¥For SCSS styles replace css with scss in the Swiper import path:

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

使用组件

¥Using Components

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

¥Swiper exports two components: Swiper and SwiperSlide. The Swiper component is the equivalent of IonSlides, and SwiperSlide is the equivalent of IonSlide.

这些组件从 swiper/vue 导入并提供给你的 Vue 组件：

¥These components are imported from swiper/vue and provided to your Vue component:

<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>

使用模块

¥Using Modules

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

¥By default, Swiper for Vue does not import any additional modules. To use modules such as Navigation or Pagination, you need to import them first.

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

¥ion-slides automatically included the Pagination, Scrollbar, Autoplay, Keyboard, and Zoom modules. This part of the guide will show you how to install these modules.

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

¥To begin, we need to import the modules and their corresponding CSS files from the swiper package:

<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 提供这些模块：

¥From here, we need to provide these modules to Swiper by using the modules property on the swiper component:

<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>

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

¥Finally, we can turn these features on by using the appropriate properties:

<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://swiperjs.com/vue#usage。

¥See https://swiperjs.com/vue#usage for a full list of modules.

IonicSlides 模块

¥The IonicSlides Module

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

¥With ion-slides, Ionic automatically customized dozens of Swiper properties. This resulted in an experience that felt smooth when swiping on mobile devices. We recommend using the IonicSlides module to ensure that these properties are also set when using Swiper directly. However, using this module is not required to use Swiper.js in Ionic.

建议查看 IonicSlides 设置的 properties 并确定你想要自定义哪些。

¥It is recommended to review the properties set by IonicSlides and determine which ones you would like to customize.

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

¥We can install the IonicSlides module by importing it from @ionic/vue and passing it in as the last item in the modules array:

<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 模块必须是数组中的最后一个模块。这将让它自动自定义分页、滚动条、缩放等模块的设置。

¥The IonicSlides module must be the last module in the array. This will let it automatically customize the settings of modules such as Pagination, Scrollbar, Zoom, and more.

属性

¥Properties

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

¥Swiper options are provided as props directly on the <swiper> component rather than via the options object in ion-slides.

假设在带有 ion-slides 的应用中，我们设置了 slidesPerView 和 loop 选项：

¥Let's say in an app with ion-slides we had the slidesPerView and loop options set:

<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> 组件上：

¥To migrate, we would move these options out of the options object and onto the <swiper> component directly as properties:

<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 时属性更改的完整列表：

¥Below is a full list of property changes when going from ion-slides to Swiper Vue:

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

注意

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

¥All properties available in Swiper Vue can be found at https://swiperjs.com/vue#swiper-props.

事件

¥Events

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

¥Since the Swiper component is not provided by Ionic Framework, event names will not have an ionSlide prefix to them.

假设在 ion-slides 的应用中我们使用了 ionSlideDidChange 事件：

¥Let's say in an app with ion-slides we used the ionSlideDidChange event:

<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：

¥To migrate, we would change the name of the event to 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 时事件名称更改的完整列表：

¥Below is a full list of event name changes when going from ion-slides to Swiper Vue:

ion-slides 事件	刷屏事件
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://swiperjs.com/vue#swiper-events 中找到。

¥All events available in Swiper Vue can be found at https://swiperjs.com/vue#swiper-events.

方法

¥Methods

大多数方法已被删除，有利于直接访问 <swiper> 属性。此外，调用方法时不再需要先访问 $el。

¥Most methods have been removed in favor of accessing the <swiper> props directly. Additionally, you no longer need to access $el first when calling methods.

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

¥Accessing these properties can be tricky as you want to access the properties on the Swiper instance itself, not your Vue component. To do this, we recommend getting a reference to the Swiper instance via the @swiper event handler:

<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！

¥From here, if you wanted to access a property on the Swiper instance you would access slides.value. For example, if you wanted to check the isBeginning property, you could do: slides.value.isBeginning. Make sure slides.value is defined first though!

以下是从 ion-slides 到 Swiper Vue 时方法更改的完整列表：

¥Below is a full list of method changes when going from ion-slides to 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 属性。

效果

¥Effects

如果你使用 Cube 或 Fade 等效果，你可以像我们安装其他模块一样安装它们。在此示例中，我们将使用淡入淡出效果。首先，我们将从 swiper 导入 EffectFade 并将其提供到 modules 数组中：

¥If you are using effects such as Cube or Fade, you can install them just like we did with the other modules. In this example, we will use the fade effect. To start, we will import EffectFade from swiper and provide it in the modules array:

<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>

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

¥Next, we need to import the stylesheet associated with the effect:

<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" 来激活它：

¥After that, we can activate it by setting the effect property on swiper to "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://swiperjs.com/vue#effects。

¥For more information on effects in Swiper, please see https://swiperjs.com/vue#effects.

包起来

¥Wrap Up

现在你已经安装了 Swiper，有一整套新的 Swiper 功能供你使用。我们建议从 SwiperVue 介绍 开始，然后参考 Swiper API 文档。

¥Now that you have Swiper installed, there is a whole set of new Swiper features for you to enjoy. We recommend starting with the Swiper Vue Introduction and then referencing the Swiper API docs.

常见问题

¥FAQ

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

¥Where can I find an example of this migration?

你可以在 ion-slides 中找到示例应用，并在 https://github.com/ionic-team/slides-migration-samples 中找到等效的 Swiper 用法。

¥You can find a sample app with ion-slides and the equivalent Swiper usage at https://github.com/ionic-team/slides-migration-samples.

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

¥Where can I get help with this migration?

如果你在迁移时遇到问题，请在 Ionic 论坛 上创建帖子。

¥If you are running into issues with the migration, please create a post on the Ionic Forum.

我在哪里提交错误报告？

¥Where do I file bug reports?

在提出问题之前，请考虑在 Swiper 讨论区 或 Ionic 论坛 上创建帖子，看看社区是否可以解决你的问题。

¥Before opening an issue, please consider creating a post on the Swiper Discussion Board or the Ionic Forum to see if your issue can be resolved by the community.

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

¥If you are running into problems with the Swiper library, new bugs should be filed on the Swiper repo: https://github.com/nolimits4web/swiper/issues

如果你遇到 IonicSlides 模块的问题，应在 Ionic Framework 存储库上提交新的错误：https://github.com/ionic-team/ionic-framework/issues

¥If you are running into problems with the IonicSlides module, new bugs should be filed on the Ionic Framework repo: https://github.com/ionic-team/ionic-framework/issues