鸿蒙开发：Swiper轮播图
鸿蒙Swiper组件详解
一、Swiper组件概述
Swiper是鸿蒙(HarmonyOS)系统中提供的一个滑动容器组件，它允许用户通过手指滑动来切换子组件（通常是页面或图片），实现轮播图、引导页、图片浏览器等常见UI效果。
说明
该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
Swiper组件内包含了PanGesture拖动手势事件，用于滑动轮播子组件。disableSwipe属性设为true会取消内部的PanGesture事件监听。
子组件
可以包含子组件。
说明
子组件类型：系统组件和自定义组件，支持渲染控制类型（if/else、ForEach、LazyForEach和Repeat）。不建议子组件中混用懒加载组件（包括LazyForEach、Repeat）和非懒加载组件，或者子组件中使用多个懒加载组件，否则可能导致懒加载组件预加载能力失效等问题。不建议在组件动画过程中对数据源进行操作，否则会导致布局出现异常。
Swiper子组件的visibility属性设置为Visibility.None，且Swiper的displayCount属性设置为'auto'时，对应子组件在视窗内不占位，但不影响导航点个数；visibility属性设置为Visibility.None或者Visibility.Hidden时，对应子组件不显示，但依然会在视窗内占位。
当Swiper子组件设置了offset属性时，会按照子组件的层级进行绘制，层级高的子组件会覆盖层级低的子组件。例如，Swiper包含3个子组件，其中第3个子组件设置了offset({ x : 100 })，那么在横向循环滑动中，第3个子组件会覆盖第1个子组件，此时可设置第1个子组件的zIndex属性值大于第3个子组件，使第1个子组件层级高于第3个子组件。
接口
Swiper(controller?: SwiperController)
创建滑块视图容器。
卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| controller | SwiperController | 否 | 给组件绑定一个控制器，用来控制组件翻页。 |
属性
除支持通用属性外，还支持以下属性：
index
index(value: number)
设置当前在容器中显示的子组件的索引值。设置小于0或大于等于子组件数量时，按照默认值0处理。
从API version 10开始，该属性支持$$双向绑定变量。
卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | number | 是 | 当前在容器中显示的子组件的索引值。 默认值：0 说明： 设置的值小于0或大于最大页面索引时，取0。 |
autoPlay
autoPlay(value: boolean)
设置子组件是否自动播放。
loop为false时，自动轮播到最后一页时停止轮播。手势切换后不是最后一页时继续播放。当Swiper不可见时会停止轮播。
卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | boolean | 是 | 子组件是否自动播放。 默认值：false，不自动轮播。 |
interval
interval(value: number)
设置使用自动播放时播放的时间间隔。
卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | number | 是 | 自动播放时播放的时间间隔。当小于duration属性值时，翻页完成后会立即开始下一次轮播。 默认值：3000单位：毫秒取值范围：[0, +∞)，设置小于0的值时，按照默认值处理。 |
loop
loop(value: boolean)
设置是否开启循环。设置为true时表示开启循环，在LazyForEach懒循环加载模式下，加载的组件数量建议大于5个。
卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | boolean | 是 | 是否开启循环。true为开启循环，false为不开启循环。 默认值：true |
vertical
vertical(value: boolean)
设置是否为纵向滑动。
卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | boolean | 是 | 是否为纵向滑动。true为纵向滑动，false为横向滑动。 默认值：false |
等等一些新增属性和不常用的属性。
二、使用场景
-
图片轮播展示：电商APP的商品详情页顶部展示多张商品图片
-
应用引导页：新用户首次打开APP时的功能介绍页面
-
内容分页浏览：新闻类APP的文章分页阅读
-
广告展示：首页顶部自动轮播的广告位
-
相册浏览：全屏查看多张图片时可左右滑动切换
三、基本用法介绍
1. 基础Swiper实现
//创建一个BannerClass类
class BannerClass {id: string = '';img: ResourceStr = '';url: string = '';//添加构造函数constructor(id: string, img: ResourceStr, url: string) {this.id = idthis.img = imgthis.url = url}
}@Entry
@Component
struct Index {@State message: string = '快速入门';build() {Column() {Text(this.message).fontSize(24).fontWeight(700).width('100%').textAlign(TextAlign.Start) //文本对齐方式.padding({ left: 16 }).fontFamily('HarmonyHeiTi-Bold') //字体样式.lineHeight(33) //行高Banner()}.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]) //沉浸式开发.height('100%').width('100%').backgroundColor('#F1F3F5')}
}//Banner内容
@Preview
@Component
struct Banner {//构建了六个BannerClass实例@State bannerList: Array<BannerClass> = [new BannerClass('pic0', $r('app.media.banner_pic0'),'https://developer.huawei.com/consumer/cn/training/course/video/C101718352529709527'),new BannerClass('pic1', $r('app.media.banner_pic1'),'https://developer.huawei.com/consumer/cn/'),new BannerClass('pic2', $r('app.media.banner_pic2'),'https://developer.huawei.com/consumer/cn/deveco-studio/'),new BannerClass('pic3', $r('app.media.banner_pic3'),'https://developer.huawei.com/consumer/cn/arkts/'),new BannerClass('pic4', $r('app.media.banner_pic4'),'https://developer.huawei.com/consumer/cn/arkui/'),new BannerClass('pic5', $r('app.media.banner_pic5'),'https://developer.huawei.com/consumer/cn/sdk')];build() {Swiper() {//使用forForEach(this.bannerList, (item: BannerClass, id: number) => {Image(item.img).objectFit(ImageFit.Contain).width('100%').padding({ top: 11, left: 16, right: 16 }).borderRadius(16)})}.autoPlay(true)//自动播放 默认是不开启的.loop(true) //循环播放 ，默认是循环播放的.indicator(//调整Swiper组件指示器的位置Indicator.dot() //小圆点.color('#1a000000') //默认的颜色.selectedColor('#0A59F7') //选中的时候的颜色)}
}
2. 效果展示：
