从 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集成所需的任何迁移信息。

note

Swiper 的 Vue 组件将在未来的 Swiper 版本中被移除，使用 Swiper Element 作为替代。然而，本指南展示了如何迁移到 Vue 组件，因为在撰写本文时它提供了最稳定的体验。

使用 Swiper 的 Vue 组件 并不是 在 Ionic Framework 中使用 Swiper.js 的必要条件。

🌐 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 setup lang="ts">
import 'swiper/css';
import '@ionic/vue/css/ionic-swiper.css';
</script>

note

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

更新选择器

🌐 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 选择器	Swiper 选择器
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 setup lang="ts">
import { Swiper, SwiperSlide } from 'swiper/vue';
import { IonContent, IonPage } from '@ionic/vue';

import 'swiper/css';
import '@ionic/vue/css/ionic-swiper.css';
</script>

使用模块

🌐 Using Modules

默认情况下，Vue 版本的 Swiper 不会导入任何额外的模块。要使用导航（Navigation）或分页（Pagination）等模块，你需要先导入它们。

🌐 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 自动包含了分页、滚动条、自动播放、键盘和缩放模块。本部分指南将向你展示如何安装这些模块。

首先，我们需要从 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 setup lang="ts">
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';
</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 { 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';

const 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 { 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';

const modules = [Autoplay, Keyboard, Pagination, Scrollbar, Zoom];
</script>

note

请参阅 https://swiper.nodejs.cn/vue#usage 以获取模块的完整列表。

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 设置的属性，并确定你希望自定义哪些属性。

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

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

🌐 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 setup lang="ts">
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';

const modules = [Autoplay, Keyboard, Pagination, Scrollbar, Zoom, IonicSlides];
</script>

note

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

属性

🌐 Properties

Swiper 的选项作为 props 直接提供在 <swiper> 组件上，而不是通过 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 属性代替。需要先安装 Pagination 模块。
scrollbar	你可以继续使用 scrollbar 属性，但请确保先安装 Scrollbar 模块。

note

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

事件

🌐 Events

由于 Swiper 组件不是由 Ionic Framework 提供的，事件名称将不会有 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 事件	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

note

Swiper Vue 中可用的所有事件可以在 https://swiper.nodejs.cn/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 setup lang="ts">
import { ref } from 'vue';

const slides = ref();
const setSwiperInstance = (swiper: any) => {
  slides.value = swiper;
};
</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 { 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';

const 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 { 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';

const 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 { 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';

const modules = [EffectFade, IonicSlides];
</script>

note

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

包起来

🌐 Wrap Up

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

常见问题

🌐 FAQ

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

🌐 Where can I find an example of this migration?

你可以在 https://github.com/ionic-team/slides-migration-samples 找到一个使用 ion-slides 和等效 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论坛 上发帖，以查看社区是否可以解决你的问题。

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

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