版本: v8

从 IonSlides 迁移到 Swiper.js

正在寻找 IonSlides？

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

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

注意

Swiper 的 React 组件将在 Swiper 的未来版本中删除，Swiper Element 将作为替换。但是，本指南展示了如何迁移到 React 组件，因为它在撰写本文时提供了最稳定的体验。值得注意的是，React 尚未对 Web 组件提供强大的支持。

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

入门

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

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

完成此操作后，在您的项目中安装 Swiper 依赖项

npm install swiper@latest

注意

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

以风格滑动

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

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

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;

注意

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

更新选择器

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

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

预处理器（可选）

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

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

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

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;

使用组件

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

这些组件从 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;

使用模块

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

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

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

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

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;

最后，我们可以使用相应的属性打开这些功能

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;

注意

请参阅 https://swiper.js.cn/react#usage，了解模块的完整列表。

IonicSlides 模块

对于 IonSlides，Ionic 自动自定义了数十个 Swiper 属性。这导致了一种在移动设备上滑动时感觉流畅的体验。我们建议您使用 IonicSlides 模块，以确保这些属性在直接使用 Swiper 时也会设置。但是，使用此模块 **不是** 在 Ionic 中使用 Swiper.js 所必需的。

建议您查看由 IonicSlides 设置的属性，并确定您要自定义哪些属性。

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

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;

注意

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

属性

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

假设在一个具有 IonSlides 的应用程序中，我们设置了 slidesPerView 和 loop 选项

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

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

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

注意

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

事件

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

假设在一个具有 IonSlides 的应用程序中，我们使用了 onIonSlideDidChange 事件

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

要迁移，我们将事件名称更改为 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 时，事件名称更改的完整列表

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`

注意

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

方法

大多数方法已被移除，取而代之的是直接访问 `Swiper` 属性。

访问这些属性可能很棘手，因为您需要访问 Swiper 实例本身的属性，而不是您的 React 组件。为了做到这一点，我们建议通过 `onSwiper` 获取 `Swiper` 实例的引用

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` 已经定义！

以下是将 `IonSlides` 迁移到 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` 属性。

效果

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

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;

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

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

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;

注意

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

总结

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

入门​

以风格滑动​

更新选择器​

预处理器（可选）​

使用组件​

使用模块​

IonicSlides 模块​

属性​

事件​

方法​

效果​

总结​

常见问题​

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

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

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

目录

入门