从 IonSlides 迁移到 Swiper.js

在找 IonSlides 吗？

IonSlides 在 v6.0.0 中已被弃用，并在 v7.0.0 中移除。我们建议直接使用 Swiper.js 库。迁移过程详述如下。

如果你需要一个现代的触摸滑块组件，我们推荐 Swiper.js 。本指南将介绍如何在你的Ionic Framework应用中设置Swiper for React。它还将介绍从IonSlides迁移到官方Swiper React集成所需的任何迁移信息。

note

Swiper 的 React 组件将在 Swiper 的未来版本中被移除，并将以 Swiper 元素作为替代。然而，本指南展示了如何迁移到 React 组件，因为在撰写本文时，它提供了最稳定的体验。值得注意的是，React 目前尚未对 Web 组件提供强有力的支持。

使用 Swiper 的 React 组件不是在 Ionic 框架中使用 Swiper.js 的必要条件。

🌐 Using Swiper's React 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/react@latest @ionic/react-router@latest

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

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

npm install swiper@latest

note

使用 Create React App 的开发者必须将 react-scripts 升级到 v5.0.0 及以上版本，并使用最新版本的 Swiper。

样式滑动

🌐 Swiping with Style

接下来，我们需要导入基础的 Swiper 样式。我们还将导入 Ionic 提供的样式，这将允许我们使用与 IonSlides 相同的 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 IonSlides.

我们建议在使用 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:

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    ...
  );
};
export default Home;

note

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

更新选择器

🌐 Updating Selectors

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

🌐 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 React:

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 React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    ...
  );
};
export default Home;

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

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    ...
  );
};
export default Home;

使用组件

🌐 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/react 导入的：

🌐 These components are imported from swiper/react:

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

使用模块

🌐 Using Modules

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

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

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

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

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';

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/react/css/ionic-swiper.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

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

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';

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/react/css/ionic-swiper.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper modules={[Autoplay, Keyboard, Pagination, Scrollbar, Zoom]}>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

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

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';

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/react/css/ionic-swiper.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper
          modules={[Autoplay, Keyboard, Pagination, Scrollbar, Zoom]}
          autoplay={true}
          keyboard={true}
          pagination={true}
          scrollbar={true}
          zoom={true}
        >
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

note

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

IonicSlides 模块

🌐 The IonicSlides Module

使用 IonSlides，Ionic 会自动自定义几十个 Swiper 属性。这使得在移动设备上滑动时体验非常流畅。我们建议使用 IonicSlides 模块，以确保在直接使用 Swiper 时这些属性也被设置。然而，使用此模块不是在 Ionic 中使用 Swiper.js 的必要条件。

🌐 With IonSlides, 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/react 导入 IonicSlides 模块，并将其作为 modules 数组中的最后一项传入来安装它：

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

import React from 'react';
import { IonContent, IonPage, IonicSlides } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';

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/react/css/ionic-swiper.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper
          modules={[Autoplay, Keyboard, Pagination, Scrollbar, Zoom, IonicSlides]}
          autoplay={true}
          keyboard={true}
          pagination={true}
          scrollbar={true}
          zoom={true}
        >
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

note

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

属性

🌐 Properties

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

🌐 Swiper options are provided as props directly on the <Swiper> component rather than via the options object in IonSlides.

假设在一个使用 IonSlides 的应用中，我们设置了 slidesPerView 和 loop 选项：

🌐 Let's say in an app with IonSlides we had the slidesPerView and loop options set:

const MyComponent: React.FC = () => {
  return (
    <IonSlides
      options={{
        slidesPerView: 3,
        loop: true,
      }}
    >
      <IonSlide>Slide 1</IonSlide>
      <IonSlide>Slide 2</IonSlide>
      <IonSlide>Slide 3</IonSlide>
    </IonSlides>
  );
};

要进行迁移，我们会将这些选项从 options 对象中移出，并直接作为属性放到 <Swiper> 组件上：

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

const MyComponent: React.FC = () => {
  return (
    <Swiper slidesPerView={3} loop={true}>
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
    </Swiper>
  );
};

以下是从 IonSlides 转到 Swiper React 时的完整属性更改列表：

🌐 Below is a full list of property changes when going from IonSlides to Swiper React:

名称	备注
options	将每个选项直接作为属性设置在 `<Swiper>` 组件上。
mode	根据模式的不同样式，你可以在 CSS 中使用 `.ios .swiper` 或 `.md .swiper` 来针对幻灯片。
pager	使用 `pagination` 属性代替。需要先安装 Pagination 模块。
scrollbar	你可以继续使用 `scrollbar` 属性，但请确保先安装 Scrollbar 模块。

note

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

事件

🌐 Events

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

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

假设在一个使用 IonSlides 的应用中，我们使用了 onIonSlideDidChange 事件：

🌐 Let's say in an app with IonSlides we used the onIonSlideDidChange event:

const MyComponent: React.FC = () => {
  return (
    <IonSlides onIonSlideDidChange={() => onSlideChange()}>
      <IonSlide>Slide 1</IonSlide>
      <IonSlide>Slide 2</IonSlide>
      <IonSlide>Slide 3</IonSlide>
    </IonSlides>
  );
};

要迁移，我们将把事件的名称更改为 onSlideChange：

🌐 To migrate, we would change the name of the event to onSlideChange:

const MyComponent: React.FC = () => {
  return (
    <Swiper onSlideChange={() => onSlideChange()}>
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
    </Swiper>
  );
};

以下是从 IonSlides 迁移到 Swiper React 时事件名称更改的完整列表：

🌐 Below is a full list of event name changes when going from IonSlides to Swiper React:

IonSlides 事件	Swiper 事件
`onIonSlideWillChange`	`onSlideChangeTransitionStart`
`onIonSlideDidChange`	`onSlideChangeTransitionEnd`
`onIonSlideDoubleTap`	`onDoubleTap`
`onIonSlideDrag`	`onSliderMove`
`onIonSlideNextStart`	`onSlideNextTransitionStart`
`onIonSlideNextEnd`	`onSlideNextTransitionEnd`
`onIonSlidePrevStart`	`onSlidePrevTransitionStart`
`onIonSlidePrevEnd`	`onSlidePrevTransitionEnd`
`onIonSlideReachStart`	`onReachBeginning`
`onIonSlideReachEnd`	`onReachEnd`
`onIonSlideTap`	`onTap`
`onIonSlideTouchStart`	`onTouchStart`
`onIonSlideTouchEnd`	`onTouchEnd`
`onIonSlideTransitionStart`	`onTransitionStart`
`onIonSlideTransitionEnd`	`onTransitionEnd`
`onIonSlidesDidLoad`	`onInit`

note

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

方法

🌐 Methods

大多数方法已被移除，改为直接访问 Swiper 属性。

🌐 Most methods have been removed in favor of accessing the Swiper props directly.

访问这些属性可能很棘手，因为你想访问的是 Swiper 实例本身的属性，而不是你的 React 组件的属性。为此，我们建议通过 onSwiper 获取 Swiper 实例的引用：

🌐 Accessing these properties can be tricky as you want to access the properties on the Swiper instance itself, not your React component. To do this, we recommend getting a reference to the Swiper instance via onSwiper:

import React, { useState } from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Swiper as SwiperInterface } from 'swiper';
...
const Home: React.FC = () => {
  const [swiperInstance, setSwiperInstance] = useState<SwiperInterface>();
  return (
    ...
    <Swiper
      onSwiper={(swiper) => setSwiperInstance(swiper)}
    >
      ...
    </Swiper>
  )
};
export default Home;

从这里，如果你想访问 Swiper 实例上的某个属性，你可以访问 swiperInstance。例如，如果你想检查 isBeginning 属性，你可以这样做：swiperInstance.isBeginning。不过，先确保 swiperInstance 已经定义了！

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

以下是从 IonSlides 迁移到 Swiper React 时方法变更的完整列表：

🌐 Below is a full list of method changes when going from IonSlides to Swiper React:

IonSlides 方法	备注
`getActiveIndex()`	请使用 `activeIndex` 属性代替。
`getPreviousIndex()`	请使用 `previousIndex` 属性代替。
`getSwiper()`	使用 `onSwiper` 获取 Swiper 实例的引用。参见上面的示例。
`isBeginning()`	请使用 `isBeginning` 属性代替。
`isEnd()`	请使用 `isEnd` 属性代替。
`length()`	请使用 `slides` 属性代替。（如 swiperRef.slides.length）
`lockSwipeToNext()`	请使用 `allowSlidesNext` 属性代替。
`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:

import React from 'react';
import { IonContent, IonPage, IonicSlides } from '@ionic/react';
import { EffectFade } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper modules={[EffectFade, IonicSlides]}>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

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

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

import React from 'react';
import { IonContent, IonPage, IonicSlides } from '@ionic/react';
import { EffectFade } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper modules={[EffectFade, IonicSlides]}>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

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

🌐 After that, we can activate it by setting the effect property on swiper to "fade":

import React from 'react';
import { IonContent, IonPage, IonicSlides } from '@ionic/react';
import { EffectFade } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper modules={[EffectFade, IonicSlides]} effect="fade">
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

note

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

包起来

🌐 Wrap Up

现在你已经安装了 Swiper，有一整套新的 Swiper 功能可供使用。我们建议从 Swiper React 入门开始，然后参考 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

新手上路​

样式滑动​

更新选择器​

预处理器（可选）​

使用组件​

使用模块​

IonicSlides 模块​

属性​

事件​

方法​

效果​

包起来​

常见问题​

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

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

我在哪里提交错误报告？​

目录

新手上路

样式滑动

更新选择器

预处理器（可选）

使用组件

使用模块

IonicSlides 模块

属性

事件

方法

效果

包起来

常见问题

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

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

我在哪里提交错误报告？