从 ion-slides 迁移到 Swiper.js

在找 ion-slides 吗？

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

如果你需要一个现代的触摸滑块组件，我们推荐 Swiper.js 。Swiper 9 引入了 Swiper Element ，作为其 Angular 组件的替代品，所以本指南将介绍如何在你的 Ionic Framework 应用中设置 Swiper Element。它还将介绍从 ion-slides 迁移到 Swiper Element 可能需要的任何迁移信息。

新手上路

🌐 Getting Started

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

🌐 First, update to the latest version of Ionic:

npm install @ionic/angular@latest

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

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

npm install swiper@latest

接下来，我们需要添加 CUSTOM_ELEMENTS_SCHEMA，它告诉 Angular 我们将使用自定义元素。这可以在 app.module.ts 中完成，或者在你将使用 Swiper 的组件的模块文件中完成。

🌐 Next, we need to add the CUSTOM_ELEMENTS_SCHEMA, which tells Angular that we will be using custom elements. This can be done in either app.module.ts, or the module file for the component where you will be using Swiper.

import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [..., CUSTOM_ELEMENTS_SCHEMA]
});
...

最后，我们需要调用 Swiper 的 register 函数来全局注册 Swiper 的自定义元素。这只需执行一次，因此应将其放在 app.component.ts 中。

🌐 Finally, we need to call Swiper's register function to globally register Swiper's custom elements. This should only be done once, so place it in app.component.ts.

import { register } from 'swiper/element/bundle';

register();

@Component({
  ...
})
...

从那里，我们只需将 ion-slides 元素替换为 swiper-container，将 ion-slide 元素替换为 swiper-slide。请注意，这些自定义元素不需要导入，因为调用 register 会自行告诉 Angular 它们。

🌐 From there, we just have to replace ion-slides elements with swiper-container and ion-slide elements with swiper-slide. Note that these custom elements do not need to be imported, as calling register tells Angular about them on its own.

<swiper-container>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
</swiper-container>

打包版本与核心版本

🌐 Bundled vs. Core Versions

默认情况下，请确保从 swiper/element/bundle 导入 register 函数。这使用打包的 Swiper 版本，该版本会自动包含运行 Swiper 各种功能所需的所有模块和样式表。

🌐 By default, make sure you import the register function from swiper/element/bundle. This uses the bundled version of Swiper, which automatically includes all modules and stylesheets needed to run Swiper's various features.

如果你想使用仅包含核心版本，而不会自动包含额外模块的版本，请参见 https://swiper.nodejs.cn/element#core-version-and-modules。本迁移指南的其余部分将假设你正在使用打包版本。

样式滑动

🌐 Swiping with Style

要迁移 CSS，请首先更新选择器以定位新的自定义元素：

🌐 To migrate over your CSS, first update your selectors to target the new custom elements instead:

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

如果你正在使用 ion-slides 上的 CSS 自定义属性，下面是 Swiper 中使用的对应属性列表。

🌐 If you were using the CSS custom properties found on ion-slides, below is a list of corresponding properties used in Swiper.

`ion-slides` CSS 属性	`swiper-container` CSS 属性
`--bullet-background`	`--swiper-pagination-bullet-inactive-color`
`--bullet-background-active`	`--swiper-pagination-color`
`--progress-bar-background`	`--swiper-pagination-progressbar-bg-color`
`--progress-bar-background-active`	`--swiper-pagination-color`
`--scroll-bar-background`	`--swiper-scrollbar-bg-color`
`--scroll-bar-background-active`	`--swiper-scrollbar-drag-bg-color`

对于额外的自定义 CSS，由于 Swiper 元素使用了 Shadow DOM 封装，样式需要注入到 Shadow DOM 范围内。请参阅 https://swiper.nodejs.cn/element#injecting-styles 获取说明。

附加 `ion-slides` 样式

🌐 Additional ion-slides Styles

ion-slides 组件具有额外的样式，有助于创建本地化的外观和感觉。这些样式并非使用 Swiper.js 与 Ionic 所必需的，但如果你希望尽可能保持 ion-slides 的外观，请将以下 CSS 添加到你的 global.scss 中：

🌐 The ion-slides component had additional styling that helped create a native look and feel. These styles are not required to use Swiper.js with Ionic, but if you would like to maintain the look of ion-slides as closely as possible, add the following CSS to your global.scss:

swiper-container {
  --swiper-pagination-bullet-inactive-color: var(--ion-text-color-step-800, #cccccc);
  --swiper-pagination-color: var(--ion-color-primary, #0054e9);
  --swiper-pagination-progressbar-bg-color: rgba(var(--ion-text-color-rgb, 0, 0, 0), 0.25);
  --swiper-scrollbar-bg-color: rgba(var(--ion-text-color-rgb, 0, 0, 0), 0.1);
  --swiper-scrollbar-drag-bg-color: rgba(var(--ion-text-color-rgb, 0, 0, 0), 0.5);
}

swiper-slide {
  display: flex;
  position: relative;

  flex-direction: column;
  flex-shrink: 0;
  align-items: center;
  justify-content: center;

  width: 100%;
  height: 100%;

  font-size: 18px;

  text-align: center;
  box-sizing: border-box;
}

swiper-slide img {
  width: auto;
  max-width: 100%;
  height: auto;
  max-height: 100%;
}

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.

我们可以通过导入 IonicSlides 模块并将其作为数组传递给 swiper-container 的 modules 属性来安装它：

🌐 We can install the IonicSlides module by importing and passing it to the modules property of swiper-container as an array:

Angular
Angular (Standalone)

// home.page.ts

import { IonicSlides } from '@ionic/angular';

@Component({
  ...
})
export class HomePage {
  swiperModules = [IonicSlides];
}

// home.page.ts

import { IonicSlides } from '@ionic/angular/standalone';

@Component({
  ...
})
export class HomePage {
  swiperModules = [IonicSlides];
}

<swiper-container [modules]="swiperModules"> ... </swiper-container>

note

如果你正在使用 Swiper 的核心版本并且已安装额外的模块，请确保 IonicSlides 是数组中的最后一个模块。这将允许它自动自定义分页、滚动条、缩放等模块的设置。

属性

🌐 Properties

Swiper 的选项应作为单独的属性直接提供在 <swiper-container> 组件上。

🌐 Swiper options should be provided as individual properties directly on the <swiper-container> component.

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

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

<ion-slides [options]="{ slidesPerView: 3, loop: true }">
  <ion-slide>Slide 1</ion-slide>
  <ion-slide>Slide 3</ion-slide>
  <ion-slide>Slide 3</ion-slide>
</ion-slides>

要将这些选项直接设置为 <swiper-container> 的属性，我们可以按如下方式操作：

🌐 To set these options as properties directly on <swiper-container> we would do the following:

<swiper-container [slidesPerView]="3" [loop]="true">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
</swiper-container>

以下是从 ion-slides 转到 Swiper 元素时的所有属性更改列表：

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

名称	备注
options	将每个选项直接作为属性设置在 `<swiper-container>` 组件上。
mode	根据模式的不同样式，你可以在 CSS 中使用 `.ios swiper-container` 或 `.md swiper-container` 来定位幻灯片。
pager	请改用 `pagination` 属性。

note

Swiper 元素中可用的所有属性可以在以下网址找到 https://swiper.nodejs.cn/swiper-api#parameters。

事件

🌐 Events

由于 swiper-container 组件不是由 Ionic Framework 提供的，事件名称将不会有 ionSlide 前缀。此外，所有事件名称应使用小写字母，而不是驼峰式命名。

🌐 Since the swiper-container component is not provided by Ionic Framework, event names will not have an ionSlide prefix to them. Additionally, all event names should be lowercase instead of camelCase.

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

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

<ion-slides (ionSlideDidChange)="onSlideChange()">
  <ion-slide>Slide 1</ion-slide>
  <ion-slide>Slide 3</ion-slide>
  <ion-slide>Slide 3</ion-slide>
</ion-slides>

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

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

<swiper-container (swiperslidechange)="onSlideChange()">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
</swiper-container>

以下是从 ion-slides 迁移到 Swiper Angular 时事件名称更改的完整列表：

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

ion-slides 事件	Swiper 事件
`ionSlideWillChange`	`swiperslidechangetransitionstart`
`ionSlideDidChange`	`swiperslidechange`
`ionSlideDoubleTap`	`swiperdoubletap`
`ionSlideDrag`	`swiperslidermove`
`ionSlideNextStart`	`swiperslidenexttransitionstart`
`ionSlideNextEnd`	`swiperslidenexttransitionend`
`ionSlidePrevStart`	`swiperslideprevtransitionstart`
`ionSlidePrevEnd`	`swiperslideprevtransitionend`
`ionSlideReachStart`	`swiperreachbeginning`
`ionSlideReachEnd`	`swiperreachend`
`ionSlideTap`	`swipertap`
`ionSlideTouchStart`	`swipertouchstart`
`ionSlideTouchEnd`	`swipertouchend`
`ionSlideTransitionStart`	`swipertransitionstart`
`ionSlideTransitionEnd`	`swipertransitionend`
`ionSlidesDidLoad`	`swiperinit`

note

Swiper 元素中可用的所有事件可以在 https://swiper.nodejs.cn/swiper-api#events 找到，并且应该小写并以单词 swiper 作为前缀。

方法

🌐 Methods

大多数方法已被移除，取而代之的是直接访问 Swiper 实例的属性。要访问 Swiper 实例，首先获取对 <swiper-container> 元素的引用（例如通过 ViewChild），然后访问其 swiper 属性：

🌐 Most methods have been removed in favor of directly accessing the properties of the Swiper instance. To access the Swiper instance, first get a reference to the <swiper-container> element (such as through ViewChild), then access its swiper prop:

<swiper-container #swiper>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
</swiper-container>

// slides.component.ts

import { ..., ElementRef, ViewChild } from '@angular/core';

@Component({
  ...
})
export class SlidesExample {
  @ViewChild('swiper')
  swiperRef: ElementRef | undefined;

  logActiveIndex() {
    console.log(this.swiperRef?.nativeElement.swiper.activeIndex);
  }
}

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

🌐 Below is a full list of method changes when going from ion-slides to Swiper Element:

ion-slides 方法	备注
`getActiveIndex()`	改用 `activeIndex` 属性。
`getPreviousIndex()`	改用 `previousIndex` 属性。
`getSwiper()`	使用 `swiper` 属性获取 Swiper 实例的引用。见上面的示例。
`isBeginning()`	改用 `isBeginning` 属性。
`isEnd()`	改用 `isEnd` 属性。
`length()`	改用 `slides` 属性。 (即 swiper.slides.length)
`lockSwipeToNext()`	改用 `allowSlidesNext` 属性。
`lockSwipeToPrev()`	改用 `allowSlidePrev` 属性。
`lockSwipes()`	改用 `allowSlideNext`、`allowSlidePrev` 和 `allowTouchMove` 属性。
`startAutoplay()`	改用 `autoplay` 属性。
`stopAutoplay()`	改用 `autoplay` 属性。

note

Swiper 实例上可用的所有方法和属性可以在 https://swiper.nodejs.cn/swiper-api#methods-and-properties 找到。

效果

🌐 Effects

只要使用 Swiper 的打包版本，Swiper 元素中就可以使用 Cube 或 Fade 等效果，而无需额外导入。例如，下面的代码将使幻灯片具有翻转过渡效果：

🌐 Effects such as Cube or Fade can be used in Swiper Element with no additional imports, as long as you are using the bundled version of Swiper. For example, the below code will cause the slides to have a flip transition effect:

<swiper-container effect="flip"> ... </swiper-container>

note

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

包起来

🌐 Wrap Up

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

新手上路​

打包版本与核心版本​

样式滑动​

附加 ion-slides 样式​

IonicSlides 模块​

属性​

事件​

方法​

效果​

包起来​

常见问题​

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

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

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

目录

新手上路

打包版本与核心版本

样式滑动

附加 `ion-slides` 样式

IonicSlides 模块

属性

事件

方法

效果

包起来

常见问题

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

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

我在哪里提交错误报告？