SwiperController 编程式控制翻页与 showNext

前言

在 Swiper 轮播组件中，除了用户手势滑动翻页，还经常需要编程式控制翻页。SwiperController 提供了showNext()、showPrevious()等 API，用于在代码中控制轮播的切换。

“海风日记“的引导页通过 SwiperController 实现了“下一步“按钮的编程式翻页，以及“跳过“按钮的直接跳转。本文将从源码出发，深入讲解 SwiperController 的完整用法。

一、SwiperController 概述

1.1 创建控制器

private swiperController: SwiperController = new SwiperController()

1.2 绑定到 Swiper

Swiper(this.swiperController) { // 页面内容 }

1.3 API 方法

二、编程式翻页的三种方式

2.1 showNext / showPrevious

// 切换到下一页 Button('下一步') .onClick(() => { this.swiperController.showNext() }) // 切换到上一页 Button('上一步') .onClick(() => { this.swiperController.showPrevious() })

2.2 通过 onChange 同步状态

@State currentIndex: number = 0 Swiper(this.swiperController) .onChange((index: number) => { this.currentIndex = index // 同步当前索引 })

2.3 条件判断翻页

Button(this.currentIndex === 2 ? '立即开始' : '下一步') .onClick(() => { if (this.currentIndex === 2) { // 最后一页：跳转到首页 router.replaceUrl({ url: 'pages/Index' }) } else { // 翻到下一页 this.swiperController.showNext() } })

三、SwiperController 的完整交互

3.1 引导页的翻页逻辑

@Entry @Component struct OnboardingPage { @State currentIndex: number = 0 private swiperController: SwiperController = new SwiperController() build() { Stack() { Column() { Swiper(this.swiperController) { ForEach(PAGES, (page: OnboardingPageData, idx: number) => { this.buildPage(page, idx) }) } .layoutWeight(1) .indicator(false) .loop(false) .onChange((index: number) => { this.currentIndex = index }) // 底部固定区域 Column({ space: 16 }) { // 分页圆点 this.pageDots() // 底部按钮 Button(this.currentIndex === 2 ? '立即开始' : '下一步') .width('85%').height(52) .fontSize(17).fontColor('#FFFFFF').fontWeight(FontWeight.Bold) .backgroundColor(COLOR_PRIMARY).borderRadius(26) .onClick(() => { if (this.currentIndex === 2) { router.replaceUrl({ url: 'pages/Index' }) } else { this.swiperController.showNext() } }) } .padding({ top: 16, bottom: 40 }) .backgroundColor(PAGES[this.currentIndex].bg) } // 跳过按钮 Button('跳过') .position({ top: 52, right: 20 }) .onClick(() => { router.replaceUrl({ url: 'pages/Index' }) }) } } }

3.2 用户操作的所有可能路径

用户操作路径 1（正常流程）： 第 1 页 → 点击"下一步" → 第 2 页 → 点击"下一步" → 第 3 页 → 点击"立即开始" → 首页 用户操作路径 2（跳过）： 任意页 → 点击"跳过" → 首页

四、SwiperController 与手势的交互

4.1 手势与编程式控制的优先级

4.2 禁用手势

如果需要完全禁用用户手势，只允许编程式控制：

Swiper(this.swiperController) { // 页面内容 } .disableSwipe(true) // 禁用滑动

4.3 手势与编程式控制的对比

五、SwiperController 的典型应用场景

5.1 引导页

// 最后一页才显示"开始"按钮 Button(this.currentIndex === 2 ? '立即开始' : '下一步') .onClick(() => { if (this.currentIndex === 2) { router.replaceUrl({ url: 'pages/Index' }) } else { this.swiperController.showNext() } })

5.2 图片查看器

// 上一张 / 下一张按钮 Row() { Button('上一张') .onClick(() => { this.swiperController.showPrevious() }) Button('下一张') .onClick(() => { this.swiperController.showNext() }) }

5.3 表单分步

// 分步表单的下一步/上一步 Button('上一步') .enabled(this.currentIndex > 0) // 第一页禁用 .onClick(() => { this.swiperController.showPrevious() }) Button('下一步') .enabled(this.currentIndex < 2) // 最后一页禁用 .onClick(() => { this.swiperController.showNext() })

六、SwiperController 的动画控制

6.1 动画时长

Swiper(this.swiperController) .duration(400) // 切换动画时长 400ms

6.2 动画曲线

Swiper(this.swiperController) .curve(Curve.EaseInOut) // 缓入缓出曲线

6.3 动画完成回调

Swiper(this.swiperController) .onAnimationStart(() => { console.info('动画开始') }) .onAnimationEnd(() => { console.info('动画结束') })

七、常见问题与排查

7.1 showNext 不生效

问题：调用showNext()后页面没有切换。

原因：已经到达最后一页，且loop为false。

解决方案：在调用前检查当前索引：

if (this.currentIndex < totalPages - 1) { this.swiperController.showNext() }

7.2 控制器未绑定

问题：SwiperController 方法无效。

原因：控制器未传递给 Swiper 组件。

解决方案：

Swiper(this.swiperController) // 必须传递控制器

总结

本文通过“海风日记“引导页的源码，深入讲解了 SwiperController 的完整用法：

1. SwiperController 基础：创建、绑定、API 方法
2. 编程式翻页：showNext / showPrevious 的使用
3. 交互逻辑：条件判断、按钮文字切换、跳过功能
4. 手势控制：禁用滑动、手势与编程式控制的对比
5. 典型场景：引导页、图片查看器、分步表单
6. 动画控制：时长、曲线、回调

下一篇文章将深入讲解indicator 自定义分页圆点动画与交互，敬请期待。

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

相关资源：

• SwiperController API 文档
• Swiper 组件文档
• Router 路由文档
• 海风日记项目源码
• [HarmonyOS 开发者官网](https://atomgit.com/openharmony/docs
• 开源鸿蒙跨平台社区
• ArkUI 动画概述
• Curve 动画曲线