Swiper


Swiper

滑块视图容器,提供子组件滑动轮播显示的能力。

说明:

该组件从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

子组件

可以包含子组件。

说明:

子组件类型:系统组件和自定义组件,支持渲染控制类型(if/elseForEachLazyForEach)。

接口

Swiper(controller?: SwiperController)

参数:

参数名 参数类型 必填 参数描述
controller SwiperController 给组件绑定一个控制器,用来控制组件翻页。

属性

除支持通用属性外,还支持以下属性,不支持Menu控制

名称 参数类型 描述
index number 设置当前在容器中显示的子组件的索引值。
默认值:0
说明:
设置小于0或大于等于子组件数量时,按照默认值0处理。
autoPlay boolean 子组件是否自动播放。
默认值:false
说明:
loop为false时,自动轮播到最后一页时停止轮播。手势切换后不是最后一页时继续播放。
interval number 使用自动播放时播放的时间间隔,单位为毫秒。
默认值:3000
indicator10+ DotIndicator | DigitIndicator | boolean 设置可选导航点指示器样式。
- DotIndicator:圆点指示器样式。
- DigitIndicator:数字指示器样式。
- boolean:是否启用导航点指示器。
  默认值:true
  默认类型:DotIndicator
loop boolean 是否开启循环。
设置为true时表示开启循环,在LazyForEach懒循环加载模式下,加载的组件数量建议大于5个。
默认值:true
duration number 子组件切换的动画时长,单位为毫秒。
默认值:400
vertical boolean 是否为纵向滑动。
默认值:false
itemSpace number | string 设置子组件与子组件之间间隙。
默认值:0
说明:
不支持设置百分比。
displayMode SwiperDisplayMode 主轴方向上元素排列的模式,优先以displayCount设置的个数显示,displayCount未设置时本属性生效。
默认值:SwiperDisplayMode.Stretch
cachedCount8+ number 设置预加载子组件个数。
默认值:1
disableSwipe8+ boolean 禁用组件滑动切换功能。
默认值:false
curve8+ Curve | string 设置Swiper的动画曲线,默认为淡入淡出曲线,常用曲线参考Curve枚举说明,也可以通过插值计算模块提供的接口创建自定义的插值曲线对象。
默认值:Curve.Ease
indicatorStyle8+ {
left?: Length,
top?: Length,
right?: Length,
bottom?: Length,
size?: Length,
mask?: boolean,
color?: ResourceColor,
selectedColor?: ResourceColor
}
设置导航点样式:
- left: 设置导航点距离Swiper组件左边的距离。
- top: 设置导航点距离Swiper组件顶部的距离。
- right: 设置导航点距离Swiper组件右边的距离。
- bottom: 设置导航点距离Swiper组件底部的距离。
- size: 设置导航点的直径。
- mask: 设置是否显示导航点蒙层样式。
- color: 设置导航点的颜色。
- selectedColor: 设置选中的导航点的颜色。
displayCount8+ number|string 设置一页内元素显示个数。
默认值:1
说明:
字符串类型仅支持设置为'auto',显示效果同SwiperDisplayMode.AutoLinear。
使用number类型时,子组件按照主轴均分Swiper宽度(减去displayCount-1的itemSpace)的方式进行主轴拉伸(收缩)布局。
effectMode8+ EdgeEffect 滑动效果,目前支持的滑动效果参见EdgeEffect的枚举说明。
默认值:EdgeEffect.Spring
说明:
控制器接口调用时不生效回弹。
nextMargin10+
Length
后边距,用于露出后一项的一小部分。
默认值:0
说明:
>仅当SwiperDisplayMode为STRETCH模式时生效。当cachedCount设置值小于等于0时,此时会露出后一项的一小部分,但无法加载子组件。当displayCount设置为1时,此参数设置无效。
prevMargin10+
Length
前边距,用于露出前一项的一小部分。
默认值:0
说明:
仅当SwiperDisplayMode为STRETCH模式时生效。当cachedCount设置值小于等于0时,此时会露出前一项的一小部分,但无法加载子组件。当displayCount设置为1时,此参数设置无效。

SwiperDisplayMode枚举说明

名称 描述
Stretch Swiper滑动一页的宽度为Swiper组件自身的宽度。
AutoLinear Swiper滑动一页的宽度为子组件宽度中的最大值。

SwiperController

Swiper容器组件的控制器,可以将此对象绑定至Swiper组件,然后通过它控制翻页。

showNext

showNext(): void

翻至下一页。翻页带动效切换过程,时长通过duration指定。

showPrevious

showPrevious(): void

翻至上一页。翻页带动效切换过程,时长通过duration指定。

finishAnimation

finishAnimation(callback?: () => void): void

停止播放动画。

参数:

参数名 参数类型 必填项 参数描述
callback () => void 动画结束的回调。

Indicator10+对象说明

设置导航点距离Swiper组件距离。

参数名 参数类型 必填项 参数描述
left Length 设置导航点距离Swiper组件左边的距离。
top Length 设置导航点距离Swiper组件顶部的距离。
right Length 设置导航点距离Swiper组件右边的距离。
bottom Length 设置导航点距离Swiper组件底部的距离。

DotIndicator

圆点指示器属性及功能继承自Indicator。

参数名 参数类型 必填项 参数描述
itemWidth Length 设置Swiper组件圆点导航指示器的宽。
默认值:6
单位:vp
itemHeight Length 设置Swiper组件圆点导航指示器的高。
默认值:6
单位:vp
selectedItemWidth Length 设置选中Swiper组件圆点导航指示器的宽。
默认值:6
单位:vp
selectedItemHeight Length 设置选中Swiper组件圆点导航指示器的高。
默认值:6
单位:vp
mask boolean 设置是否显示Swiper组件圆点导航指示器的蒙版样式。
默认值:false
color ResourceColor 设置Swiper组件圆点导航指示器的颜色。
默认值:'#007DFF'
selectedColor ResourceColor 设置选中Swiper组件圆点导航指示器的颜色。
默认值:'#182431'(10%透明度)

DigitIndicator

数字指示器属性及功能继承自Indicator。

参数名 参数类型 必填项 参数描述
fontColor ResourceColor 设置Swiper组件数字导航点的字体颜色。
默认值:'#ff182431'
selectedFontColor ResourceColor 设置选中Swiper组件数字导航点的字体颜色。
默认值:'#ff182431'
digitFont {
size?:Length
weight?:number | FontWeight | string
}
设置Swiper组件数字导航点的字体样式:
- size:数字导航点指示器的字体大小。
默认值:14vp
- weight:数字导航点指示器的字重。
selectedDigitFont {
size?:Length
weight?:number | FontWeight | string
}
设置选中Swiper组件数字导航点的字体样式:
- size:数字导航点选中指示器的字体大小。
默认值:14vp
- weight:数字导航点选中指示器的字重。

事件

除支持通用事件外,还支持以下事件:

名称 功能描述
onChange(event: (index: number) => void) 当前显示的子组件索引变化时触发该事件,返回值为当前显示的子组件的索引值。
- index:当前显示元素的索引。
说明:
Swiper组件结合LazyForEach使用时,不能在onChange事件里触发子页面UI的刷新。
onAnimationStart9+(event: (index: number) => void) 切换动画开始时触发该回调。
- index:当前显示元素的索引。
说明:
参数为动画开始前的index值(不是最终结束动画的index值),多列Swiper时,index为最左侧组件的索引。
onAnimationEnd9+(event: (index: number) => void) 切换动画结束时触发该回调。
- index:当前显示元素的索引。
说明:
当Swiper切换动效结束时触发,包括动画过程中手势中断,通过SwiperController调用finishAnimatio。参数为动画结束后的index值,多列Swiper时,index为最左侧组件的索引。

示例

// xxx.ets
class MyDataSource implements IDataSource {
  private list: number[] = []
  private listener: DataChangeListener

  constructor(list: number[]) {
    this.list = list
  }

  totalCount(): number {
    return this.list.length
  }

  getData(index: number): any {
    return this.list[index]
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    this.listener = listener
  }

  unregisterDataChangeListener() {
  }
}

@Entry
@Component
struct SwiperExample {
  private swiperController: SwiperController = new SwiperController()
  private data: MyDataSource = new MyDataSource([])

  aboutToAppear(): void {
    let list = []
    for (var i = 1; i <= 10; i++) {
      list.push(i.toString());
    }
    this.data = new MyDataSource(list)
  }

  build() {
    Column({ space: 5 }) {
      Swiper(this.swiperController) {
        LazyForEach(this.data, (item: string) => {
          Text(item).width('90%').height(160).backgroundColor(0xAFEEEE).textAlign(TextAlign.Center).fontSize(30)
        }, item => item)
      }
      .cachedCount(2)
      .index(1)
      .autoPlay(true)
      .interval(4000)
      .indicator(true)
      .loop(true)
      .duration(1000)
      .itemSpace(0)
      .curve(Curve.Linear)
      .onChange((index: number) => {
        console.info(index.toString())
      })

      Row({ space: 12 }) {
        Button('showNext')
          .onClick(() => {
            this.swiperController.showNext()
          })
        Button('showPrevious')
          .onClick(() => {
            this.swiperController.showPrevious()
          })
      }.margin(5)
    }.width('100%')
    .margin({ top: 5 })
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

swiper