从 ion-slides 迁移到 Swiper.js
ion-slides?寻找ion-slides 在 v6.0.0 中已弃用，并在 v7.0.0 中删除。我们建议直接使用 Swiper.js 库。下面详细介绍迁移过程。
¥ion-slides 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。Swiper 9 引入了 滑动元素 作为其 Angular 组件的替代品，因此本指南将介绍如何在 Ionic Framework 应用中设置 Swiper Element。它还将详细介绍你从 ion-slides 迁移到 Swiper Element 可能需要的任何迁移信息。
¥We recommend Swiper.js if you need a modern touch slider component. Swiper 9 introduced Swiper Element as a replacement for its Angular component, so this guide will go over how to get Swiper Element set up in your Ionic Framework application. It will also go over any migration information you may need to move from ion-slides to 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({
...
})
...
从那里，我们只需用 swiper-container 替换 ion-slides 元素，用 swiper-slide 替换 ion-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://swiperjs.com/element#core-version-and-modules。本迁移指南的其余部分将假设你使用的是打包版本。
¥If you would like to use the Core version instead, which does not include additional modules automatically, see https://swiperjs.com/element#core-version-and-modules. The rest of this migration guide will assume you are using the bundled version.
样式滑动
¥Swiping with Style
要迁移 CSS，请首先更新选择器以定位新的自定义元素：
¥To migrate over your CSS, first update your selectors to target the new custom elements instead:
| ion-slides 选择器 | 滑动选择器 |
|---|---|
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 Element 使用 Shadow DOM 封装，因此需要将样式注入到 Shadow DOM 范围中。请参阅 https://swiperjs.com/element#injecting-styles 了解说明。
¥For additional custom CSS, because Swiper Element uses Shadow DOM encapsulation, styles will need to be injected into the Shadow DOM scope. See https://swiperjs.com/element#injecting-styles for instructions.
其他 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-color-step-200, #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 设置的 properties 并确定你想要自定义哪些。
¥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];
}
<!-- home.page.html -->
<swiper-container [modules]="swiperModules"> ... </swiper-container>
如果你使用的是 Swiper 的 Core 版本并安装了其他模块，请确保 IonicSlides 是数组中的最后一个模块。这将让它自动自定义分页、滚动条、缩放等模块的设置。
¥If you are using the Core version of Swiper and have installed additional modules, ensure that IonicSlides is 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-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 Element 时属性更改的完整列表：
¥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 属性。 |
Swiper Element 中可用的所有属性都可以在 https://swiperjs.com/swiper-api#parameters 中找到。
¥All properties available in Swiper Element can be found at https://swiperjs.com/swiper-api#parameters.
事件
¥Events
由于 Ionic Framework 不提供 swiper-container 组件，因此事 件名称不会有 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 事件 | 刷屏事件 |
|---|---|
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 |
Swiper Element 中可用的所有事件都可以在 https://swiperjs.com/swiper-api#events 中找到，并且应小写并以单词 swiper 为前缀。
¥All events available in Swiper Element can be found at https://swiperjs.com/swiper-api#events and should be lowercased and prefixed with the word 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:
<!-- slides.component.html -->
<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 Element 时方法更改的完整列表：
¥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 属性。 |
Swiper 实例上可用的所有方法和属性都可以在 https://swiperjs.com/swiper-api#methods-and-properties 中找到。
¥All methods and properties available on the Swiper instance can be found at https://swiperjs.com/swiper-api#methods-and-properties.
效果
¥Effects
只要你使用 Swiper 的打包版本，就可以在 Swiper Element 中使用 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>
有关 Swiper 中效果的更多信息，请参阅https://swiperjs.com/swiper-api#fade-effect。
¥For more information on effects in Swiper, please see https://swiperjs.com/swiper-api#fade-effect.
包起来
¥Wrap Up
现在你已经安装了 Swiper，有一整套新的 Swiper 功能供你使用。我们建议从 Swiper 元素文档 开始，然后参考 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 Element documentation 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