鸿蒙学习实战之路-Swiper 轮播组件全攻略

🥦 鸿蒙学习实战之路-Swiper 轮播组件全攻略

最近好多朋友问我：“鸿蒙里的轮播图怎么搞啊？是不是和前端的 Swiper 差不多？” 哎，这你可问对人了！作为一个把npm install炒成ohpm install的前端厨子^_，今天我就手把手带你搞定 HarmonyOS 里的 Swiper 轮播组件！

咱们今天的目标很明确：从 Swiper 的基本用法到高级定制，再到实际案例，包教包会！全程实操，没有虚的～

一、Swiper 组件是什么？

Swiper 组件提供滑动轮播显示的能力，本身是一个容器组件，当设置了多个子组件后，可以对这些子组件进行轮播显示。

你可以把它理解为前端的 Swiper 插件，但更原生、更贴合 HarmonyOS 的声明式 UI 体系。

看看这些常见的使用场景：

二、Swiper 基本用法

1. 设置轮播内容和尺寸

轮播内容很简单，直接作为 Swiper 的子组件即可。尺寸有两种设置方式：

• 设置 Swiper 的尺寸：内容会拉伸为和 Swiper 一致（优先级高）
• 设置内容尺寸：会将 Swiper 撑开

@Entry @Component struct SwiperBasic { build() { Column() { Text('Swiper基本使用') .fontSize(20) .fontWeight(900) .padding(10) Swiper() { Text('🥦 西兰花') .textAlign(TextAlign.Center) .backgroundColor(Color.Red) .fontColor(Color.White) .fontSize(30) Text('🍅 西红柿') .textAlign(TextAlign.Center) .backgroundColor(Color.Green) .fontColor(Color.White) .fontSize(30) Text('🥕 胡萝卜') .textAlign(TextAlign.Center) .backgroundColor(Color.Blue) .fontColor(Color.White) .fontSize(30) } .width('100%') .height(100) } .width('100%') .height('100%') } }

运行效果就是这样滴：

🥦西兰花小贴士：

建议优先设置 Swiper 的尺寸，这样可以更好地控制轮播区域的大小，避免内容撑开导致的布局问题。

三、Swiper 常用属性

设置了基础内容后，咱们来看看一些高频使用的属性：

咱们来试试这些属性的效果，把轮播图调整为：自动播放、4 秒间隔、纵向滑动：

@Entry @Component struct SwiperAttributes { build() { Column() { Text('Swiper常用属性') .fontSize(20) .fontWeight(900) .padding(10) Swiper() { Text('0') .textAlign(TextAlign.Center) .backgroundColor(Color.Red) .fontColor(Color.White) .fontSize(30) Text('1') .textAlign(TextAlign.Center) .backgroundColor(Color.Green) .fontColor(Color.White) .fontSize(30) Text('2') .textAlign(TextAlign.Center) .backgroundColor(Color.Blue) .fontColor(Color.White) .fontSize(30) } .width('100%') .height(160) .loop(false) // 是否开启循环 .autoPlay(true) // 自动播放 .interval(4000) // 4秒切换一次 .vertical(true) // 纵向滑动 } .width('100%') .height('100%') } }

效果如下：

🥦西兰花警告：

当 loop 为 false 时，自动轮播到最后一页会停止；但如果用户手动滑动后，只要不是最后一页，就会继续自动播放哦！别问我怎么知道的，都是泪…

四、导航点的调整

默认的导航点可能不符合你的设计需求，没关系，咱们可以自定义！

导航点的调整主要分两类：

1. 显示或隐藏
2. 导航点类型：
   • 圆点指示器（重点掌握）
   • 数字指示器（了解即可）

1. 基础控制

Swiper() { // 轮播内容 } // .indicator(false) // 关闭导航点 // .indicator(Indicator.dot()) // 圆点指示器（默认） // .indicator(Indicator.digit()) // 数字指示器

2. 自定义圆点导航点

日常开发中最常用的就是圆点指示器，咱们重点掌握如何调整它：

位置属性：

• left/top/right/bottom：设置导航点距离 Swiper 边缘的距离

样式属性：

• itemWidth/itemHeight：默认指示器的宽高
• selectedItemWidth/selectedItemHeight：选中指示器的宽高
• color：默认指示器颜色
• selectedColor：选中指示器颜色

来个实际例子：

@Entry @Component struct SwiperIndicator { build() { Column() { Text('Swiper导航点自定义') .fontSize(20) .fontWeight(900) .padding(10) Swiper() { Text('0') .textAlign(TextAlign.Center) .backgroundColor(Color.Red) .fontColor(Color.White) .fontSize(30) Text('1') .textAlign(TextAlign.Center) .backgroundColor(Color.Green) .fontColor(Color.White) .fontSize(30) Text('2') .textAlign(TextAlign.Center) .backgroundColor(Color.Blue) .fontColor(Color.White) .fontSize(30) } .width('100%') .height(160) .indicator( Indicator.dot() .left(10) // 左侧距离 .bottom(10) // 底部距离 .itemWidth(20) // 默认指示器宽度 .itemHeight(20) // 默认指示器高度 .selectedItemWidth(30) // 选中指示器宽度 .selectedItemHeight(30) // 选中指示器高度 .selectedColor(Color.Yellow) // 选中颜色 .color(Color.Blue) // 默认颜色 ) } .width('100%') .height('100%') } }

调整后的效果：

🥦西兰花小贴士：

导航点的位置属性可以组合使用，不需要全部设置。比如想把导航点放在右下角，只需要设置.right(10)和.bottom(10)就可以啦！

五、实战案例-小米有品轮播图

光说不练假把式，咱们来实现一个小米有品首页的轮播效果：

代码中的图片素材可以替换为任意的内容

需求分析

1. 宽高：100%、160
2. 循环播放、自动轮播，间隔 4 秒
3. 圆点指示器：
   • 选中颜色：白色
   • 选中宽高：30、4
   • 默认宽高：10、4

实现代码

@Entry @Component struct SwiperXiaomiCase { build() { Column() { Text('Swiper案例-小米有品') .fontSize(20) .fontWeight(900) .padding(10) Swiper() { // 注意：这里的图片资源需要在你的项目中添加 Image($r('app.media.ic_swiper_xmyp01')) Image($r('app.media.ic_swiper_xmyp02')) Image($r('app.media.ic_swiper_xmyp03')) Image($r('app.media.ic_swiper_xmyp04')) } .width('100%') .height(160) .loop(true) // 开启循环 .autoPlay(true) // 自动播放 .interval(4000) // 4秒间隔 .indicator( Indicator.dot() .bottom(10) // 距离底部10vp .selectedColor(Color.White) // 选中颜色白色 .selectedItemWidth(30) // 选中宽度30vp .selectedItemHeight(4) // 选中高度4vp .itemWidth(10) // 默认宽度10vp .itemHeight(4) // 默认高度4vp .color('#88FFFFFF') // 默认颜色半透明白色 ) } .width('100%') .height('100%') } }

实现效果：

🥦西兰花警告：

别忘记在你的项目资源文件夹里添加对应的轮播图片哦！可以去小米有品官网找几张样图，或者用自己的图片代替。

六、总结与技巧

重点回顾

1. 基本用法：Swiper 作为容器组件，子组件即为轮播内容
2. 核心属性：loop（循环）、autoPlay（自动播放）、interval（间隔）、vertical（方向）
3. 导航点：支持圆点和数字两种类型，可自定义位置和样式
4. 实战案例：通过小米有品轮播图掌握综合应用

高级技巧

• 懒加载：结合 LazyForEach 使用，可以高效加载大量轮播内容
• 事件监听：可以监听 change 事件，实现轮播切换时的联动效果
• 手势控制：支持触摸滑动，用户体验更好

🥦西兰花小贴士：

当轮播内容很多时，记得使用 LazyForEach 懒加载，这样可以提高性能，避免一次性加载所有内容导致的卡顿！

👉 下一步行动

今天咱们搞定了 Swiper 轮播组件，是不是超简单？o(╯□╰)o 其实鸿蒙里的很多组件都和前端有相似之处，只要掌握了规律，学习起来并不难～

📚推荐资料：

• 官方文档：Swiper 组件
• 组件参考：Swiper API

我是盐焗西兰花，
不教理论，只给你能跑的代码和避坑指南。
下期见！🥦