鸿蒙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

等等一些新增属性和不常用的属性。

 

二、使用场景

1. 图片轮播展示：电商APP的商品详情页顶部展示多张商品图片

2. 应用引导页：新用户首次打开APP时的功能介绍页面

3. 内容分页浏览：新闻类APP的文章分页阅读

4. 广告展示：首页顶部自动轮播的广告位

5. 相册浏览：全屏查看多张图片时可左右滑动切换

 

 三、基本用法介绍

 1. 基础Swiper实现

//创建一个BannerClass类
class BannerClass {
  id: string = '';
  img: ResourceStr = '';
  url: string = '';

  //添加构造函数
  constructor(id: string, img: ResourceStr, url: string) {
    this.id = id
    this.img = img
    this.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() {
      //使用for
      ForEach(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. 效果展示：