HarmonyOS6 ArkTS swiper

概述

Swiper 是 HarmonyOS6（API 11+）ArkUI 框架提供的滑块视图容器组件，核心用于实现子组件的滑动轮播展示，是开发轮播图、引导页、卡片滑动等场景的核心组件。该组件从 API Version 7 开始支持，HarmonyOS6 中对其属性、指示器定制、控制器能力进行了优化，支持自动播放、循环滚动、自定义指示器、手动控制翻页等核心能力，且适配多设备布局规范，是鸿蒙应用开发中高频使用的UI容器之一。

核心特性

1. 支持水平循环滑动，默认开启循环模式，实现无限轮播效果；
2. 提供自动播放能力，可自定义播放间隔和切换动画时长；
3. 内置DotIndicator 圆点指示器，支持自定义颜色、尺寸、选中样式；
4. 提供SwiperController 控制器，实现手动上一页、下一页、跳转到指定页；
5. 支持边缘露出（prevMargin/nextMargin），实现卡片堆叠的视觉效果；
6. 可自定义切换动画曲线（如缓入缓出、线性等），提升交互体验；
7. 提供索引变化事件（onChange），实时监听轮播页切换状态。

完整示例

// SwiperCompleteExample.ets @Entry @Component struct SwiperCompleteExample { private swiperController: SwiperController = new SwiperController(); private swiperData: string[] = [ "轮播项 1", "轮播项 2", "轮播项 3", "轮播项 4", "轮播项 5", "轮播项 6" ]; private bgColors: string[] = [ "#3878F3", "#F5A623", "#86909C", "#68B4FF", "#DDEBFF", "#FFEFC9" ]; @State currentIndex: number = 0; build() { Column({ space: 20 }) { Text('HarmonyOS Swiper 轮播组件') .fontSize(22) .fontWeight(FontWeight.Bold) .alignSelf(ItemAlign.Center); // ========== Swiper 轮播核心 ========== Swiper(this.swiperController) { ForEach(this.swiperData, (item: string, index: number) => { Stack() { Text(item) .fontSize(20) .fontColor("#fff") .fontWeight(FontWeight.Medium); Text(`${index + 1}/${this.swiperData.length}`) .fontSize(14) .fontColor("#ffffff80") .position({ right: 15, bottom: 15 }); } .width("100%") .height(220) .backgroundColor(this.bgColors[index]) .borderRadius(16); }, (item: string) => item); } .width("90%") .height(220) .autoPlay(true) .loop(true) .interval(3000) .duration(600) .curve(Curve.EaseInOut) .itemSpace(10) .prevMargin(25) .nextMargin(25) .indicator( new DotIndicator() .color("#ffffff60") .selectedColor("#ffffff") .itemWidth(8) .itemHeight(8) .selectedItemWidth(20) ) .onChange((index: number) => { this.currentIndex = index; }); // ========== 手动控制按钮组 ========== Row({ space: 15 }) { Button("上一页") .width(100) .backgroundColor("#3878F3") .onClick(() => this.swiperController.showPrevious()); Button("下一页") .width(100) .backgroundColor("#3878F3") .onClick(() => this.swiperController.showNext()); Button("跳转到第3页") .backgroundColor("#F5A623") .onClick(() => this.swiperController.changeIndex(2, true)); } .justifyContent(FlexAlign.Center) .width("100%"); // 当前索引展示 Text(`当前页：${this.currentIndex + 1} / ${this.swiperData.length}`) .fontSize(15) .fontColor("#666"); } .width("100%") .height("100%") .backgroundColor("#f5f5f5") .padding({ top: 30, bottom: 30 }); } }

运行效果如图：
可自动轮播

也可点击按钮跳转相应位置

核心API解析

1 组件构造器

Swiper(controller?:SwiperController)

• 参数：SwiperController为可选控制器，绑定后可通过控制器实现手动翻页，示例中通过new SwiperController()初始化并绑定，是实现手动控制的基础。

2 关键属性配置

示例中使用的核心属性均为 HarmonyOS6 官方推荐配置，对应官方API规范，各属性作用及取值说明如下：

3 指示器定制（DotIndicator）

HarmonyOS6 中 Swiper 内置DotIndicator圆点指示器，支持自定义样式，示例中核心配置项说明：

• color：未选中圆点的颜色，示例为半透明白（#ffffff60）；
• selectedColor：选中圆点的颜色，示例为纯白色（#ffffff）；
• itemWidth/itemHeight：未选中圆点的宽高，示例为8vp；
• selectedItemWidth：选中圆点的宽度，示例为20vp（实现拉长的选中效果）；

4 控制器（SwiperController）

SwiperController是 Swiper 组件的手动控制核心，示例中使用的3个核心方法覆盖所有手动翻页场景，均为 HarmonyOS6 官方支持方法：

1. showPrevious()：翻到上一页，示例中绑定“上一页”按钮点击事件；
2. showNext()：翻到下一页，示例中绑定“下一页”按钮点击事件；
3. changeIndex(index: number, useAnimation: boolean)：跳转到指定索引页，index为目标索引（从0开始），useAnimation为是否带动画，示例中跳转到第3页（索引2）并开启动画。

5 核心事件

onChange((index:number)=>void)

• 触发时机：轮播项切换完成，当前显示的索引发生变化时触发；
• 返回值：index为当前选中轮播项的索引（从0开始）；
• 示例作用：实时更新currentIndex状态，实现页面中“当前页”的实时展示，是监听轮播状态的核心事件。

核心使用要点

1 语法规范（HarmonyOS6 重点）

1. 布局属性链式调用：justifyContent、alignItems等Flex布局属性，不可写在Row/Column构造参数中，需通过链式调用实现（如示例中Row({ space: 15 }).justifyContent(FlexAlign.Center)），否则会报语法不兼容错误；
2. 长度单位取值：DotIndicator的space、bottom等属性，以及Swiper的prevMargin、nextMargin等，HarmonyOS6 中纯数字为默认合法取值（单位vp），无需添加字符串单位（如’6vp’），避免LengthMetrics类型报错；
3. ForEach 唯一标识：遍历轮播项时，ForEach第三个参数必须传入唯一标识（示例中为(item: string) => item），确保组件渲染稳定性，避免重复渲染或刷新异常。

2 功能使用注意

1. 循环轮播（loop）：开启loop: true时，轮播项数量建议≥3，避免滑动时出现空白或动画异常；
2. 自动播放（autoPlay）：开启后指示器默认支持点击切换，点击后自动播放不会中断，持续循环；
3. 边缘露出（prevMargin/nextMargin）：需配合itemSpace使用，且Swiper子组件需设置width: 100%，否则露出效果不生效；
4. 控制器绑定：SwiperController需先初始化，再传入Swiper构造器，否则手动控制方法调用会无响应。

总结

HarmonyOS6 ArkTS 中的 Swiper 组件在保持低版本兼容性的基础上，优化了指示器定制和语法规范，通过属性配置可快速实现基础轮播效果，结合SwiperController和onChange事件可实现复杂的手动控制和状态监听。开发时需严格遵循 HarmonyOS6 的语法规范（如布局属性链式调用、长度单位取值），避免常见语法报错，同时根据业务场景灵活调整循环、自动播放、边缘露出等属性，即可实现各类滑动轮播需求。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！