从 IonSlides 迁移到 Swiper.js

IonSlides?寻找

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

¥IonSlides 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 Framework 应用中设置 Swiper for React。它还将介绍你从 IonSlides 迁移到官方 Swiper React 集成可能需要的任何迁移信息。

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

注意

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

¥Swiper's React 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 React component because it provides the most stable experience at the time of writing. Notably, React does not have strong support for Web Components yet.

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

¥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

注意

使用 Create React App 的开发者必须使用 react-scripts v5.0.0+以及最新版本的 Swiper。

¥Developers using Create React App must use react-scripts v5.0.0+ with the latest version of 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;

注意

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

¥Importing @ionic/react/css/ionic-swiper.css is not required to use Swiper.js with Ionic. This files is used for backward-compatibility with the IonSlides 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 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 选择器	滑动选择器
`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

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

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

¥IonSlides 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:

import React from 'react';


import { IonContent, IonPage } from '@ionic/react';


import { Swiper, SwiperSlide } from 'swiper/react';
import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper';

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

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

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;

注意

有关模块的完整列表，请参阅 https://swiperjs.com/react#usage。

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

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 设置的 properties 并确定你想要自定义哪些。

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

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

¥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';

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;

注意

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 提供，而不是通过 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` 属性。需要安装分页模块。
scrollbar	你可以继续使用 `scrollbar` 属性，只需确保先安装 Scrollbar 模块即可。

注意

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

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

事件

¥Events

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

Ionic 幻灯片事件	刷屏事件
`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`

注意

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

¥All events available in Swiper can be found at https://swiperjs.com/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:

Ionic 玻片法	注意
`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';
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';
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';
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;

注意

有关 Swiper 中效果的更多信息，请参阅 https://swiperjs.com/react#effects。

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

包起来

¥Wrap Up

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

新手上路​

样式滑动​

更新选择器​

预处理器（可选）​

使用组件​

使用模块​

IonicSlides 模块​

属性​

事件​

方法​

效果​

包起来​

常见问题​

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

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

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

目录