鸿蒙5.0开发进阶:UI框架-ArkTS组件(Swiper)

鸿蒙Harmony应用开发—ArkTS声明式开发(容器组件:Swiper) ArkTS声明式开发(容器组件:Swiper) 阅读详情

往期鸿蒙全套实战文章必看:(文中附带全栈鸿蒙学习资料)


Swiper

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

说明

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

  • Swiper组件通用属性clip的默认值为true。

  • Swiper组件内包含了PanGesture拖动手势事件,用于滑动轮播子组件。disableSwipe属性设为true会取消内部的PanGesture事件监听。

子组件

可以包含子组件。

说明

  • 子组件类型:系统组件和自定义组件,支持渲染控制类型(if/else、ForEach、LazyForEach和Repeat)。不建议子组件中混用懒加载组件(包括LazyForEach、Repeat)和非懒加载组件,或者子组件中使用多个懒加载组件,否则可能导致懒加载组件预加载能力失效等问题。

  • Swiper子组件的visibility属性设置为None,Swiper的displayCount属性设置为'auto'时,对应子组件在视窗内不占位,但不影响导航点个数。

  • Swiper子组件的visibility属性设置为None,或者visibility属性设置为Hidden时,对应子组件不显示,但依然会在视窗内占位。

  • 当Swiper子组件个数小于等于Swiper组件内容区内显示的节点总个数(totalDisplayCount = DisplayCount + prevMargin? (1 : 0) + nextMargin? (1 : 0))时,一般按照非循环模式布局处理,此时,前后边距对应子组件不显示,但依然会在视窗内占位。Swiper组件按照totalDisplayCount个数判断测算规格。例外情况如下:

    • 当Swiper子组件个数等于Swiper组件内容区内显示的节点总个数且prevMargin和nextMargin都生效时,设置loop为true支持循环。

    • 当Swiper子组件个数等于Swiper组件DisplayCount数 + 1,且prevMargin和nextMargin至少一个生效时,设置loop为true会生成截图占位组件(如果使用图片异步加载等显示耗时较长的组件可能不能正确生成截图,不建议在该场景开启循环),支持循环。

  • 当Swiper子组件设置了offset属性时,会按照子组件的层级进行绘制,层级高的子组件会覆盖层级低的子组件。例如,Swiper包含3个子组件,其中第3个子组件设置了offset({ x : 100 }),那么在横向循环滑动中,第3个子组件会覆盖第1个子组件,此时可设置第1个子组件的zIndex属性值大于第3个子组件,使第1个子组件层级高于第3个子组件。

  • 当使用渲染控制类型(if/else、ForEach、LazyForEach和Repeat)时,不要在组件动画过程中对数据源进行操作,否则会导致布局出现异常。

接口

Swiper(controller?: SwiperController)

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
controllerSwiperController否给组件绑定一个控制器,用来控制组件翻页。

属性

除支持通用属性外,还支持以下属性:

index

index(value: number)

设置当前在容器中显示的子组件的索引值。设置小于0或大于等于子组件数量时,按照默认值0处理。

从API version 10开始,该属性支持$$双向绑定变量。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valuenumber是

当前在容器中显示的子组件的索引值。

默认值:0

说明:

设置的值小于0或大于最大页面索引时,取0。

autoPlay

autoPlay(value: boolean)

设置子组件是否自动播放。

loop为false时,自动轮播到最后一页时停止轮播。手势切换后不是最后一页时继续播放。当Swiper不可见时会停止轮播。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueboolean是

子组件是否自动播放。

默认值:false

interval

interval(value: number)

设置使用自动播放时播放的时间间隔。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valuenumber是

自动播放时播放的时间间隔。

默认值:3000

单位:毫秒

indicator

indicator(value: DotIndicator | DigitIndicator | boolean)

设置可选导航点指示器样式。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueDotIndicator10+ | DigitIndicator10+ | boolean是

可选导航点指示器样式。

- DotIndicator:圆点指示器样式。

- DigitIndicator:数字指示器样式。

- boolean:是否启用导航点指示器。设置为true启用,false不启用。

默认值:true

默认类型:DotIndicator

loop

loop(value: boolean)

设置是否开启循环。设置为true时表示开启循环,在LazyForEach懒循环加载模式下,加载的组件数量建议大于5个。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueboolean是

是否开启循环。

默认值:true

duration

duration(value: number)

设置子组件切换的动画时长。

duration需要和curve一起使用。

curve默认曲线为interpolatingSpring,此时动画时长只受曲线自身参数影响,不再受duration的控制。不受duration控制的曲线可以查阅插值计算模块,比如,springMotion

、responsiveSpringMotion和interpolatingSpring类型的曲线不受duration控制。如果希望动画时长受到duration控制,需要给curve设置其他曲线。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valuenumber是

子组件切换的动画时长。

默认值:400

单位:毫秒

vertical

vertical(value: boolean)

设置是否为纵向滑动。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueboolean是

是否为纵向滑动。true为纵向滑动,false为横向滑动。

默认值:false

itemSpace

itemSpace(value: number | string)

设置子组件与子组件之间间隙。不支持设置百分比。

类型为number时,默认单位vp。类型为string时,需要显式指定像素单位,如'10px';未指定像素单位时,如'10',单位为vp。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valuenumber | string是

子组件与子组件之间间隙。

默认值:0

displayMode

displayMode(value: SwiperDisplayMode)

设置主轴方向上元素排列的模式,优先以displayCount设置的个数显示,displayCount未设置时本属性生效。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueSwiperDisplayMode是

主轴方向上元素排列的模式。

默认值:SwiperDisplayMode.STRETCH

cachedCount8+

cachedCount(value: number)

设置预加载子组件个数,以当前页面为基准,加载当前显示页面的前后个数。例如cachedCount=1时,会将当前显示的页面的前面一页和后面一页的子组件都预加载。如果设置为按组翻页,即displayCount的swipeByGroup参数设为true,预加载时会以组为基本单位。例如cachedCount=1,swipeByGroup=true时,会将当前组的前面一组和后面一组的子组件都预加载。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valuenumber是

预加载子组件个数。

默认值:1

disableSwipe8+

disableSwipe(value: boolean)

设置禁用组件滑动切换功能。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueboolean是

禁用组件滑动切换功能。设置为true禁用,false不禁用。

默认值:false

curve8+

curve(value: Curve | string | ICurve)

设置Swiper的动画曲线,默认为弹簧插值曲线,常用曲线参考Curve枚举说明,也可以通过插值计算模块提供的接口创建自定义的插值曲线对象。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueCurve | string | ICurve10+是

Swiper的动画曲线。

默认值:interpolatingSpring(-1, 1, 328, 34)

indicatorStyle(deprecated)

indicatorStyle(value?: IndicatorStyle)

设置导航点样式。

从API version 8开始支持,从API version 10开始不再维护,建议使用indicator代替。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueIndicatorStyle否导航点样式。

displayCount8+

displayCount(value: number | string | SwiperAutoFill, swipeByGroup?: boolean)

设置Swiper视窗内元素显示个数。

字符串类型仅支持设置为'auto'。

使用number类型且设置小于等于0时,按默认值1显示。

使用number类型时,子组件按照主轴均分Swiper宽度(减去displayCount-1个itemSpace)的方式进行主轴拉伸(收缩)布局。

使用SwiperAutoFill类型时,通过设置一个子组件最小宽度值minSize,会根据Swiper当前宽度和minSize值自动计算并更改一页内元素显示个数。当minSize为空或者小于等于0时,Swiper显示1列。

当按组进行翻页时,如果最后一组的子元素数量小于displayCount时,会使用占位子元素补齐。占位子元素只是用于布局占位,不显示任何内容。在占位子元素的位置会直接显示Swiper自身的背景样式。

在按组翻页时,判断翻页的拖拽距离阈值条件,会更新为Swiper自身宽度的一半。(按子元素翻页时,该阈值为子元素自身宽度的一半)。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valuenumber | string | SwiperAutoFill10+是

视窗内显示的子元素个数。

默认值:1

swipeByGroup11+boolean否

是否按组进行翻页。如果设为true,在翻页时会按组进行翻页,每组内子元素的数量为displayCount value的值;如果为false,则为默认翻页行为,即按照子元素进行翻页。

默认值:false

effectMode8+

effectMode(value: EdgeEffect)

设置边缘滑动效果,loop = false时生效。 目前支持的滑动效果参见EdgeEffect的枚举说明。控制器接口调用时不生效回弹。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueEdgeEffect是

边缘滑动效果。

默认值:EdgeEffect.Spring

displayArrow10+

displayArrow(value: ArrowStyle | boolean, isHoverShow?: boolean)

设置导航点箭头样式。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueArrowStyle | boolean是

支持设置箭头和底板样式,异常场景使用ArrowStyle对象中的默认值。设置为false不显示箭头和底板,true显示默认的箭头和底板样式。

默认值:false

isHoverShowboolean否

设置鼠标悬停时是否显示箭头。

默认值:false

说明:

isHoverShow为false时,常驻显示箭头,支持点击翻页。

isHoverShow为true时,只有在鼠标悬停时才会显示箭头,并支持点击翻页。

nextMargin10+

nextMargin(value: Length, ignoreBlank?:boolean)

设置后边距,用于露出后一项的一小部分。仅当Swiper子组件的布局方式为拉伸时生效,主要包括两种场景:1、displayMode属性设置为SwiperDisplayMode.STRETCH;2、displayCount属性设置为number类型。

当主轴方向为横向布局时,nextMargin/prevMargin中任意一个大于子组件测算的宽度,nextMargin和prevMargin均不显示。

当主轴方向为纵向布局时,nextMargin/prevMargin中任意一个大于子组件测算的高度,nextMargin和prevMargin均不显示。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueLength是

后边距。

默认值:0

ignoreBlank12+boolean否

非loop场景下尾页不显示nextMargin。在非loop场景下,设置为true时,尾页不显示空白的nextMargin,尾页的右边缘与Swiper视窗右边缘对齐;设置false时,尾页显示空白nextMargin,尾页的右边缘与Swiper视窗右边缘的距离为nextMargin。

默认值:false

说明:

尾页场景下,prevMargin和nextMargin的值相加作为左边边距显示前一个页面。

prevMargin10+

prevMargin(value: Length, ignoreBlank?:boolean)

设置前边距,用于露出前一项的一小部分。仅当Swiper子组件的布局方式为拉伸时生效,主要包括两种场景:1、displayMode属性设置为SwiperDisplayMode.STRETCH;2、displayCount属性设置为number类型。

当主轴方向为横向布局时,nextMargin/prevMargin中任意一个大于子组件测算的宽度,nextMargin和prevMargin均不显示。

当主轴方向为纵向布局时,nextMargin/prevMargin中任意一个大于子组件测算的高度,nextMargin和prevMargin均不显示。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueLength是

前边距。

默认值:0

ignoreBlank12+boolean否

非loop场景下首页不显示prevMargin。在非loop场景下,设置为true时,首页不显示空白的prevMargin,首页的左边缘与Swiper视窗左边缘对齐;设置false时,首页显示空白prevMargin,首页的左边缘与Swiper视窗左边缘的距离为prevMargin。

默认值:false

说明:

首页场景下,prevMargin和nextMargin的值相加作为右边边距显示后一个页面。

nestedScroll11+

nestedScroll(value: SwiperNestedScrollMode)

设置Swiper组件和父组件的嵌套滚动模式。loop为true时Swiper组件没有边缘,不会触发父组件嵌套滚动。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueSwiperNestedScrollMode是

Swiper组件和父组件的嵌套滚动模式。

默认值:SwiperNestedScrollMode.SELF_ONLY

说明

由于Swiper的抛滑动画逻辑和其它滚动类组件不同(Swiper一次只能滑动一页,抛滑时做翻页动画),当Swiper内嵌套其它滚动组件时,如果Swiper的翻页动画已经启动,将无法接受子节点上传的滚动偏移量。这时Swiper的翻页动画和子节点的边缘效果动画会同时执行。

indicatorInteractive12+

indicatorInteractive(value: boolean)

设置禁用组件导航点交互功能。设置为true时表示导航点可交互。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
valueboolean是

导航点是否可交互。

默认值:true

IndicatorStyle(deprecated)对象说明

从API version 8开始支持,从API version 10开始不再维护,建议使用indicator代替。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
leftLength否

设置导航点左侧相对于Swiper的位置。

未设置left和right时,进行自适应大小布局,按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐

设置为0时:按照0位置布局计算

优先级:高于right属性

取值范围:[0,Swiper宽度-导航点区域宽度],超出该范围时,取最近的的边界值。

topLength否

设置导航点顶部相对于Swiper的位置。

未设置top和bottom时,进行自适应大小布局,按照指示器本身大小和Swiper的大小,在交叉轴方向上,位于底部,效果与设置bottom=0一致

设置为0时:按照0位置布局计算

优先级:高于bottom属性

取值范围:[0,Swiper高度-导航点区域高度],超出该范围时,取最近的边界值。

rightLength否

设置导航点右侧相对于Swiper的位置。

未设置left和right时,进行自适应大小布局,按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐

设置为0时:按照0位置布局计算

优先级:低于left属性

取值范围:[0,Swiper宽度-导航点区域宽度],超出该范围时,取最近的边界值。

bottomLength否

设置导航点底部相对于Swiper的位置。

未设置top和bottom时,进行自适应大小布局,按照指示器本身大小和Swiper的大小,在交叉轴方向上,位于底部,效果与设置bottom=0一致

设置为0时:按照0位置布局计算

优先级:低于top属性

取值范围:[0,Swiper高度-导航点区域高度],超出该范围时,取最近的边界值。

sizeLength否

设置导航点的直径,不支持设置百分比。

默认值:6vp

maskboolean否设置是否显示导航点蒙层样式。
colorResourceColor否设置导航点的颜色。
selectedColorResourceColor否设置选中的导航点的颜色。

SwiperDisplayMode枚举说明

Swiper在主轴上的尺寸大小模式枚举。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称描述
Stretch(deprecated)

Swiper滑动一页的宽度为Swiper组件自身的宽度。

从API version 10开始不再维护,建议使用STRETCH代替。

卡片能力: 从API version 7开始,该接口支持在ArkTS卡片中使用。

AutoLinear(deprecated)

Swiper滑动一页的宽度为子组件宽度中的最大值。

从API version 10开始不再维护,建议使用Scroller.scrollTo代替。

卡片能力: 从API version 7开始,该接口支持在ArkTS卡片中使用。

STRETCH10+

Swiper滑动一页的宽度为Swiper组件自身的宽度。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

AUTO_LINEAR(deprecated)

Swiper滑动一页的宽度为视窗内最左侧子组件的宽度。

从API version 10开始支持,从API version 12开始不再维护,建议使用Scroller.scrollTo代替。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

SwiperNestedScrollMode11+枚举说明

Swiper组件和父组件的嵌套滚动模式枚举。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称值描述
SELF_ONLY0Swiper只自身滚动,不与父组件联动。
SELF_FIRST1Swiper自身先滚动,自身滚动到边缘以后父组件滚动。父组件滚动到边缘以后,如果父组件有边缘效果,则父组件触发边缘效果,否则Swiper触发边缘效果。

SwiperController

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

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

导入对象

let controller: SwiperController = new SwiperController()

constructor

constructor()

SwiperController的构造函数。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

showNext

showNext()

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

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

showPrevious

showPrevious()

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

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

changeIndex12+

changeIndex(index: number, useAnimation?: boolean)

翻至指定页面。

卡片能力: 从API version 12开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
indexnumber是

指定页面在Swiper中的索引值。

说明:

设置的值小于0或大于最大页面索引时,取0。

useAnimationboolean否

设置翻至指定页面时是否有动效,true表示有动效,false表示没有动效。

默认值:false。

finishAnimation

finishAnimation(callback?: () => void)

停止播放动画。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
callback() => void否动画结束的回调。

Indicator10+对象说明

设置导航点距离Swiper组件距离。由于导航点有默认交互区域,交互区域高度为32vp, 所以无法让显示部分完全贴底。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

属性

名称类型必填说明
leftLength是

设置导航点左侧相对于Swiper的位置。

未设置left和right时,进行自适应大小布局,按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐

设置为0时:按照0位置布局计算

优先级:高于right属性

取值范围:[0,Swiper宽度-导航点区域宽度],超出该范围时,取最近的的边界值。

topLength是

设置导航点顶部相对于Swiper的位置。

未设置top和bottom时,进行自适应大小布局,按照指示器本身大小和Swiper的大小,在交叉轴方向上,位于底部,效果与设置bottom=0一致

设置为0时:按照0位置布局计算

优先级:高于bottom属性

取值范围:[0,Swiper高度-导航点区域高度],超出该范围时,取最近的边界值。

rightLength是

设置导航点右侧相对于Swiper的位置。

未设置left和right时,进行自适应大小布局,按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐

设置为0时:按照0位置布局计算

优先级:低于left属性

取值范围:[0,Swiper宽度-导航点区域宽度],超出该范围 时,取最近的边界值。

bottomLength是

设置导航点底部相对于Swiper的位置。

未设置top和bottom时,进行自适应大小布局,按照指示器本身大小和Swiper的大小,在交叉轴方向上,位于底部,效果与设置bottom=0一致

设置为0时:按照0位置布局计算

优先级:低于top属性

取值范围:[0,Swiper高度-导航点区域高度],超出该范围时,取最近的边界值。

start12+LengthMetrics是

在RTL模式下为导航点距离Swiper组件右边的距离,在LTR模式下为导航点距离Swiper组件左边的距离

默认值:0

单位:vp

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

end12+LengthMetrics是

在RTL模式下为导航点距离Swiper组件左边的距离,在LTR模式下为导航点距离Swiper组件右边的距离。

默认值:0

单位:vp

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

dot

static dot(): DotIndicator

返回一个DotIndicator对象。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

digit

static digit(): DigitIndicator

返回一个DigitIndicator对象。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

DotIndicator10+对象说明

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

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
itemWidthLength是

设置Swiper组件圆点导航指示器的宽,不支持设置百分比。

默认值:6

单位:vp

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

itemHeightLength是

设置Swiper组件圆点导航指示器的高,不支持设置百分比。

默认值:6

单位:vp

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

selectedItemWidthLength是

设置选中Swiper组件圆点导航指示器的宽,不支持设置百分比。

默认值:12

单位:vp

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

selectedItemHeightLength是

设置选中Swiper组件圆点导航指示器的高,不支持设置百分比。

默认值:6

单位:vp

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

maskboolean是

设置是否显示Swiper组件圆点导航指示器的蒙版样式。

默认值:false

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

colorResourceColor是

设置Swiper组件圆点导航指示器的颜色。

默认值:'#182431'(10%透明度)

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

selectedColorResourceColor是

设置选中Swiper组件圆点导航指示器的颜色。

默认值:'#007DFF'

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

maxDisplayCount12+number是

设置圆点导航点指示器样式下,导航点显示个数最大值,当实际导航点个数大于最大导航点个数时,会生效超长效果样式,样式如示例5所示。

默认值:这个属性没有默认值,如果设置异常值那等同于没有超长显示效果。

取值范围:6-9

说明:

1、超长显示场景,目前暂时不支持交互功能(包括:手指点击拖拽、鼠标操作等)。

2、在超长显示场景下,中间页面对应的选中导航点的位置,并不是完全固定的,取决于之前的翻页操作序列。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

constructor

constructor()

DotIndicator的构造函数。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

说明

按压导航点时,导航点会放大至1.33倍显示,因此非按压态时导航点的可见范围边界至实际范围边界存在一定距离,该距离会随着itemWidth、itemHeight、selectedItemWidth、selectedItemHeight等参数变大而变大。

DigitIndicator10+对象说明

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

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
fontColorResourceColor是

设置Swiper组件数字导航点的字体颜色。

默认值:'#ff182431'

selectedFontColorResourceColor是

设置选中Swiper组件数字导航点的字体颜色。

默认值:'#ff182431'

digitFont

{

size?:Length

weight?:number | FontWeight | string

}

是

设置Swiper组件数字导航点的字体样式:

- size:数字导航点指示器的字体大小,不支持设置百分比。

默认值:14vp

- weight:数字导航点指示器的字重。

默认值:FontWeight.Normal

selectedDigitFont

{

size?:Length

weight?:number | FontWeight | string

}

是

设置选中Swiper组件数字导航点的字体样式:

- size:数字导航点选中指示器的字体大小,不支持设置百分比。

默认值:14vp

- weight:数字导航点选中指示器的字重。

默认值:FontWeight.Normal

constructor

constructor()

DigitIndicator的构造函数。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

ArrowStyle10+对象说明

左右箭头属性。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
showBackgroundboolean否

设置箭头底板是否显示。

默认值:false

isSidebarMiddleboolean否

设置箭头显示位置。

默认值:false

默认显示在导航点指示器两侧。

backgroundSizeLength否

设置底板大小。

在导航点两侧显示:

默认值:24vp

在组件两侧显示:

默认值:32vp

不支持设置百分比。

backgroundColorResourceColor否

设置底板颜色。

在导航点两侧显示:

默认值:'#00000000'

在组件两侧显示:

默认值:'#19182431'

arrowSizeLength否

设置箭头大小。

在导航点两侧显示时:

默认值:18vp

在组件两侧显示时:

默认值:24vp

说明:

showBackground为true时,arrowSize为backgroundSize的3/4。

不支持设置百分比。

arrowColorResourceColor否

设置箭头颜色。

默认值:'#182431'

SwiperAutoFill10+对象说明

自适应属性。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
minSizeVP是

设置元素显示最小宽度。

默认值:0

事件

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

onChange

onChange(event: (index: number) => void)

当前显示的子组件索引变化时触发该事件,返回值为当前显示的子组件的索引值。

Swiper组件结合LazyForEach使用时,不能在onChange事件里触发子页面UI的刷新。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
indexnumber是当前显示元素的索引。

onAnimationStart9+

onAnimationStart(event: (index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => void)

切换动画开始时触发该回调。参数为动画开始前的index值(不是最终结束动画的index值),多列Swiper时,index为最左侧组件的索引。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
indexnumber是当前显示元素的索引。
targetIndex10+number是切换动画目标元素的索引。
extraInfo10+SwiperAnimationEvent是动画相关信息,包括主轴方向上当前显示元素和目标元素相对Swiper起始位置的位移,以及离手速度。

说明

  • 当翻页动画时长为0时,只有以下场景会触发该回调:滑动翻页、自动轮播、调用SwiperController.showNext()和SwiperController.showPrevious()接口以及手指点击导航点翻页。

onAnimationEnd9+

onAnimationEnd(event: (index: number, extraInfo: SwiperAnimationEvent) => void)

切换动画结束时触发该回调。

当Swiper切换动效结束时触发,包括动画过程中手势中断,通过SwiperController调用finishAnimation。参数为动画结束后的index值,多列Swiper时,index为最左侧组件的索引。

卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
indexnumber是当前显示元素的索引。
extraInfo10+SwiperAnimationEvent是动画相关信息,只返回主轴方向上当前显示元素相对于Swiper起始位置的位移。

说明

  • 当翻页动画时长为0时,只有以下场景会触发该回调:滑动翻页、自动轮播、调用SwiperController.showNext()和SwiperController.showPrevious()接口以及手指点击导航点翻页。

onGestureSwipe10+

onGestureSwipe(event: (index: number, extraInfo: SwiperAnimationEvent) => void)

在页面跟手滑动过程中,逐帧触发该回调。多列Swiper时,index为最左侧组件的索引。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
indexnumber是当前显示元素的索引。
extraInfoSwiperAnimationEvent是动画相关信息,只返回主轴方向上当前显示元素相对于Swiper起始位置的位移。

customContentTransition12+

customContentTransition(transition: SwiperContentAnimatedTransition)

自定义Swiper页面切换动画。在页面跟手滑动和离手后执行切换动画的过程中,会对视窗内所有页面逐帧触发回调,开发者可以在回调中设置透明度、缩放比例、位移等属性来自定义切换动画。

使用说明:

1、循环场景下,设置prevMargin和nextMargin属性,使得Swiper前后端显示同一页面时,该接口不生效。

2、在页面跟手滑动和离手后执行切换动画的过程中,会对视窗内所有页面逐帧触发SwiperContentTransitionProxy回调。例如,当视窗内有下标为0、1的两个页面时,会每帧触发两次index值分别为0和1的回调。

3、设置displayCount属性的swipeByGroup参数为true时,若同组中至少有一个页面在视窗内时,则会对同组中所有页面触发回调,若同组所有页面均不在视窗内时,则会一起下渲染树。

4、在页面跟手滑动和离手后执行切换动画的过程中,默认动画(页面滑动)依然会发生,若希望页面不滑动,可以设置主轴方向上负的位移(translate属性)来抵消页面滑动。例如:当displayCount属性值为2,视窗内有下标为0、1的两个页面时,页面水平滑动过程中,可以逐帧设置第0页的translate属性在x轴上的值为-position * mainAxisLength来抵消第0页的位移,设置第1页的translate属性在x轴上的值为-(position - 1) * mainAxisLength来抵消第1页的位移。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
transitionSwiperContentAnimatedTransition是Swiper自定义切换动画相关信息。

onContentDidScroll12+

onContentDidScroll(handler: ContentDidScrollCallback)

监听Swiper页面滑动事件。

使用说明:

1、循环场景下,设置prevMargin和nextMargin属性,使得Swiper前后端显示同一页面时,该接口不生效。

2、在页面滑动过程中,会对视窗内所有页面逐帧触发ContentDidScrollCallback回调。例如,当视窗内有下标为0、1的两个页面时,会每帧触发两次index值分别为0和1的回调。

3、设置displayCount属性的swipeByGroup参数为true时,若同组中至少有一个页面在视窗内时,则会对同组中所有页面触发回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名类型必填说明
handlerContentDidScrollCallback是Swiper滑动时触发的回调。

SwiperAnimationEvent10+对象说明

Swiper组件动画相关信息集合。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称类型只读可选说明
currentOffsetnumber否否Swiper当前显示元素在主轴方向上,相对于Swiper起始位置的位移。单位VP,默认值为0。
targetOffsetnumber否否Swiper动画目标元素在主轴方向上,相对于Swiper起始位置的位移。单位VP,默认值为0。
velocitynumber否否Swiper离手动画开始时的离手速度。单位VP/S,默认值为0。

SwiperContentAnimatedTransition12+对象说明

Swiper自定义切换动画相关信息。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
timeoutnumber否Swiper自定义切换动画超时时间。从页面执行默认动画(页面滑动)至移出视窗外的第一帧开始计时,如果到达该时间后,开发者仍未调用SwiperContentTransitionProxy的finishTransition接口通知Swiper组件此页面的自定义动画已结束,那么组件就会认为此页面的自定义动画已结束,立即将该页面节点下渲染树。单位ms,默认值为0。
transitionCallback<SwiperContentTransitionProxy>是自定义切换动画具体内容。

SwiperContentTransitionProxy12+对象说明

Swiper自定义切换动画执行过程中,返回给开发者的proxy对象。开发者可通过该对象获取自定义动画视窗内的页面信息,同时,也可以通过调用该对象的finishTransition接口通知Swiper组件页面自定义动画已结束。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

属性

名称类型只读可选说明
selectedIndexnumber否否当前选中页面的索引。
indexnumber否否视窗内页面的索引。
positionnumber否否index页面相对于Swiper主轴起始位置(selectedIndex对应页面的起始位置)的移动比例。
mainAxisLengthnumber否否index对应页面在主轴方向上的长度。

说明

  • 例如,当前选中的子组件的索引为0,从第0页切换到第1页的动画过程中,每帧都会对视窗内所有页面触发回调,当视窗内有第0页和第1页两页时,每帧会触发两次回调。其中,第一次回调的selectedIndex为0、index为0、position为当前帧第0页相对于动画开始前第0页的移动比例,mainAxisLength为主轴方向上第0页的长度。第二次回调的selectedIndex仍为0、index为1、position为当前帧第1页相对于动画开始前第0页的移动比例,mainAxisLength为主轴方向上第1页的长度。

  • 若动画曲线为弹簧插值曲线,从第0页切换到第1页的动画过程中,可能会因为离手时的位置和速度,先过滑到第2页,再回弹到第1页,该过程中每帧会对视窗内第1页和第2页触发回调。

finishTransition12+

finishTransition(): void

通知Swiper组件,此页面的自定义动画已结束。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

ContentDidScrollCallback12+

type ContentDidScrollCallback = (selectedIndex: number, index: number, position: number, mainAxisLength: number) => void

Swiper滑动时触发的回调,参数可参考SwiperContentTransitionProxy中的说明。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数名类型必填说明
selectedIndexnumber是当前选中页面的索引。
indexnumber是视窗内页面的索引。
positionnumber是index页面相对于Swiper主轴起始位置(selectedIndex对应页面的起始位置)的移动比例。
mainAxisLengthnumber是index对应页面在主轴方向上的长度。

示例

示例1(设置导航点交互)

该示例通过indicatorInteractive接口,实现了控制导航点交互的功能。

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

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

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

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

  registerDataChangeListener(listener: DataChangeListener): void {
  }

  unregisterDataChangeListener() {
  }
}

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

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

  build() {
    Column({ space: 5 }) {
      Swiper(this.swiperController) {
        LazyForEach(this.data, (item: string) => {
          Text(item.toString())
            .width('90%')
            .height(160)
            .backgroundColor(0xAFEEEE)
            .textAlign(TextAlign.Center)
            .fontSize(30)
        }, (item: string) => item)
      }
      .cachedCount(2)
      .index(1)
      .autoPlay(true)
      .interval(4000)
      .loop(true)
      .indicatorInteractive(true)
      .duration(1000)
      .itemSpace(0)
      .indicator( // 设置圆点导航点样式
        new DotIndicator()
          .itemWidth(15)
          .itemHeight(15)
          .selectedItemWidth(15)
          .selectedItemHeight(15)
          .color(Color.Gray)
          .selectedColor(Color.Blue))
      .displayArrow({ // 设置导航点箭头样式
        showBackground: true,
        isSidebarMiddle: true,
        backgroundSize: 24,
        backgroundColor: Color.White,
        arrowSize: 18,
        arrowColor: Color.Blue
      }, false)
      .curve(Curve.Linear)
      .onChange((index: number) => {
        console.info(index.toString())
      })
      .onGestureSwipe((index: number, extraInfo: SwiperAnimationEvent) => {
        console.info("index: " + index)
        console.info("current offset: " + extraInfo.currentOffset)
      })
      .onAnimationStart((index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => {
        console.info("index: " + index)
        console.info("targetIndex: " + targetIndex)
        console.info("current offset: " + extraInfo.currentOffset)
        console.info("target offset: " + extraInfo.targetOffset)
        console.info("velocity: " + extraInfo.velocity)
      })
      .onAnimationEnd((index: number, extraInfo: SwiperAnimationEvent) => {
        console.info("index: " + index)
        console.info("current offset: " + extraInfo.currentOffset)
      })

      Row({ space: 12 }) {
        Button('showNext')
          .onClick(() => {
            this.swiperController.showNext()
          })
        Button('showPrevious')
          .onClick(() => {
            this.swiperController.showPrevious()
          })
      }.margin(5)
    }.width('100%')
    .margin({ top: 5 })
  }
}

示例2(设置数字指示器)

该示例通过DigitIndicator接口,实现了数字指示器的效果和功能。

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

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

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

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

  registerDataChangeListener(listener: DataChangeListener): void {
  }

  unregisterDataChangeListener() {
  }
}

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

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

  build() {
    Column({ space: 5 }) {
      Swiper(this.swiperController) {
        LazyForEach(this.data, (item: string) => {
          Text(item.toString())
            .width('90%')
            .height(160)
            .backgroundColor(0xAFEEEE)
            .textAlign(TextAlign.Center)
            .fontSize(30)
        }, (item: string) => item)
      }
      .cachedCount(2)
      .index(1)
      .autoPlay(true)
      .interval(4000)
      .indicator(Indicator.digit() // 设置数字导航点样式
        .top(200)
        .fontColor(Color.Gray)
        .selectedFontColor(Color.Gray)
        .digitFont({ size: 20, weight: FontWeight.Bold })
        .selectedDigitFont({ size: 20, weight: FontWeight.Normal }))
      .loop(true)
      .duration(1000)
      .itemSpace(0)
      .displayArrow(true, false)

      Row({ space: 12 }) {
        Button('showNext')
          .onClick(() => {
            this.swiperController.showNext()
          })
        Button('showPrevious')
          .onClick(() => {
            this.swiperController.showPrevious()
          })
      }.margin(5)
    }.width('100%')
    .margin({ top: 5 })
  }
}

示例3(设置按组翻页)

该示例通过displayCount属性实现了按组翻页效果。

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

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

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

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

  registerDataChangeListener(listener: DataChangeListener): void {
  }

  unregisterDataChangeListener() {
  }
}

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

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

  build() {
    Column({ space: 5 }) {
      Swiper(this.swiperController) {
        LazyForEach(this.data, (item: string) => {
          Text(item.toString())
            .width('90%')
            .height(160)
            .backgroundColor(0xAFEEEE)
            .textAlign(TextAlign.Center)
            .fontSize(30)
        }, (item: string) => item)
      }
      .displayCount(3, true)
      .autoPlay(true)
      .interval(4000)
      .loop(true)
      .duration(1000)
      .itemSpace(10)
      .indicator( // 设置圆点导航点样式
        new DotIndicator()
          .itemWidth(15)
          .itemHeight(15)
          .selectedItemWidth(15)
          .selectedItemHeight(15)
          .color(Color.Gray)
          .selectedColor(Color.Blue))

      Row({ space: 12 }) {
        Button('showNext')
          .onClick(() => {
            this.swiperController.showNext()
          })
        Button('showPrevious')
          .onClick(() => {
            this.swiperController.showPrevious()
          })
      }.margin(5)
    }.width('100%')
    .margin({ top: 5 })
  }
}

示例4(设置自定义页面切换动画)

该示例通过customContentTransition接口,实现了自定义Swiper页面切换动画效果。

// xxx.ets
@Entry
@Component
struct SwiperCustomAnimationExample {
  private DISPLAY_COUNT: number = 2
  private MIN_SCALE: number = 0.75

  @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange]
  @State opacityList: number[] = []
  @State scaleList: number[] = []
  @State translateList: number[] = []
  @State zIndexList: number[] = []

  aboutToAppear(): void {
    for (let i = 0; i < this.backgroundColors.length; i++) {
      this.opacityList.push(1.0)
      this.scaleList.push(1.0)
      this.translateList.push(0.0)
      this.zIndexList.push(0)
    }
  }

  build() {
    Column() {
      Swiper() {
        ForEach(this.backgroundColors, (backgroundColor: Color, index: number) => {
          Text(index.toString()).width('100%').height('100%').fontSize(50).textAlign(TextAlign.Center)
            .backgroundColor(backgroundColor)
            // 自定义动画变化透明度、缩放页面、抵消系统默认位移、渲染层级等
            .opacity(this.opacityList[index])
            .scale({ x: this.scaleList[index], y: this.scaleList[index] })
            .translate({ x: this.translateList[index] })
            .zIndex(this.zIndexList[index])
        })
      }
      .height(300)
      .indicator(false)
      .displayCount(this.DISPLAY_COUNT, true)
      .customContentTransition({
        // 页面移除视窗时超时1000ms下渲染树
        timeout: 1000,
        // 对视窗内所有页面逐帧回调transition,在回调中修改opacity、scale、translate、zIndex等属性值,实现自定义动画
        transition: (proxy: SwiperContentTransitionProxy) => {
          if (proxy.position <= proxy.index % this.DISPLAY_COUNT || proxy.position >= this.DISPLAY_COUNT + proxy.index % this.DISPLAY_COUNT) {
            // 同组页面往左滑或往右完全滑出视窗外时,重置属性值
            this.opacityList[proxy.index] = 1.0
            this.scaleList[proxy.index] = 1.0
            this.translateList[proxy.index] = 0.0
            this.zIndexList[proxy.index] = 0
          } else {
            // 同组页面往右滑且未滑出视窗外时,对同组中左右两个页面,逐帧根据position修改属性值,实现两个页面往Swiper中间靠拢并透明缩放的自定义切换动画
            if (proxy.index % this.DISPLAY_COUNT === 0) {
              this.opacityList[proxy.index] = 1 - proxy.position / this.DISPLAY_COUNT
              this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - proxy.position / this.DISPLAY_COUNT)
              this.translateList[proxy.index] = - proxy.position * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0
            } else {
              this.opacityList[proxy.index] = 1 - (proxy.position - 1) / this.DISPLAY_COUNT
              this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - (proxy.position - 1) / this.DISPLAY_COUNT)
              this.translateList[proxy.index] = - (proxy.position - 1) * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0
            }
            this.zIndexList[proxy.index] = -1
          }
        }
      })
      .onContentDidScroll((selectedIndex: number, index: number, position: number, mainAxisLength: number) => {
        // 监听Swiper页面滑动事件,在该回调中可以实现自定义导航点切换动画等
        console.info("onContentDidScroll selectedIndex: " + selectedIndex + ", index: " + index + ", position: " + position + ", mainAxisLength: " + mainAxisLength)
      })
    }.width('100%')
  }
}

示例5(设置圆点导航点超长显示)

该示例通过DotIndicator接口的maxDisplayCount属性,实现了圆点导航点超长显示动画效果。

class MyDataSource implements IDataSource {
  private list: number[] = []

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

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

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

  registerDataChangeListener(listener: DataChangeListener): void {
  }

  unregisterDataChangeListener() {
  }
}

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

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

  build() {
    Column({ space: 5 }) {
      Swiper(this.swiperController) {
        LazyForEach(this.data, (item: string) => {
          Text(item.toString())
            .width('90%')
            .height(160)
            .backgroundColor(0xAFEEEE)
            .textAlign(TextAlign.Center)
            .fontSize(30)
        }, (item: string) => item)
      }
      .cachedCount(2)
      .index(5)
      .autoPlay(true)
      .interval(4000)
      .loop(true)
      .duration(1000)
      .itemSpace(0)
      .indicator( // 设置圆点导航点样式
        new DotIndicator()
          .itemWidth(8)
          .itemHeight(8)
          .selectedItemWidth(16)
          .selectedItemHeight(8)
          .color(Color.Gray)
          .selectedColor(Color.Blue)
          .maxDisplayCount(9))
      .displayArrow({ // 设置导航点箭头样式
        showBackground: true,
        isSidebarMiddle: true,
        backgroundSize: 24,
        backgroundColor: Color.White,
        arrowSize: 18,
        arrowColor: Color.Blue
      }, false)
      .curve(Curve.Linear)
      Row({ space: 12 }) {
        Button('showNext')
          .onClick(() => {
            this.swiperController.showNext()
          })
        Button('showPrevious')
          .onClick(() => {
            this.swiperController.showPrevious()
          })
      }.margin(5)
    }.width('100%')
    .margin({ top: 5 })
  }
}

鸿蒙ArkTS容器组件:【Swiper】 滑块视图容器,提供子组件滑动轮播显示的能力。该组件从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。 阅读详情

相关推荐

【ArkTS】一文带你了解Swiper组件的方方面面

Swiper是一个容器类组件,它提供了切换页面显示的能力,Swiper内部包含的每一个子组件都表示一个页面,简单来说就是如果Swiper中包含了3个子组件,那么Swiper中就有3个页面。代码很简单,就是使用Swiper组件内部包裹了3个Image组件,然后调用了显示页面指示器indicator()和自动轮播autoPlay()这两个api。OK,相信通过上面的代码说明,大家都已经能够很熟练的掌握Swiper组件的用法啦,今天的内容就到这里了,下期再会!

华为开发者联盟 2930

鸿蒙4.0应用开发——轮播图

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

高心星的专栏 1447

鸿蒙5.0版开发:UI框架JS组件-容器组件(swiper)

滑动容器,提供切换子组件显示的能力。

m0_69424697的博客 1060

鸿蒙开发 ArkTS 组件之 Swiper 篇

Swiper是常见的轮播图组件,支持图片自动播放、循环展示等功能。基本使用需配置网络图片数组,通过ForEach渲染图片,并设置圆角、点击事件等属性。常用功能包括:autoPlay自动播放(默认3秒间隔)、loop循环、itemSpace间距设置、displayCount多图展示(支持设备适配)、indicator导航指示器。进阶功能可通过SwiperController实现手动翻页控制,包含上一页/下一页/首页/尾页跳转等功能。使用需注意网络权限申请和不同设备尺寸的适配优化。

2301_77896664的博客 1362

鸿蒙5.0进阶开发:UI开发-使用懒加载开发长列表界面

针对List、Grid、WaterFlow、Swiper组件,提供NodeAdapter对象替代ArkTS侧的LazyForEach功能...........

AyomQAQ的博客 969

纯血鸿蒙APP实战开发——swiper指示器导航点位于swiper下方

本示例介绍通过分割swiper区域,实现指示器导航点位于swiper下方的效果。如果你觉得这篇内容对你还蛮有帮助,我想邀请你帮我三个小忙:关注小编,同时可以期待后续文章ing🚀,不定期分享原创知识。utils。

m0_71524094的博客 1010

HarmonyOS6 ArkTS swiper

Swiper 是 HarmonyOS6(API 11+)ArkUI 框架提供的滑块视图容器组件,核心用于实现子组件的滑动轮播展示,是开发轮播图、引导页、卡片滑动等场景的核心组件。该组件从 API Version 7 开始支持,HarmonyOS6 中对其属性、指示器定制、控制器能力进行了优化,支持自动播放、循环滚动、自定义指示器、手动控制翻页等核心能力,且适配多设备布局规范,是鸿蒙应用开发中高频使用的UI容器之一。

qq_37048082的博客 3万+

鸿蒙HarmonyOS NEXT开发实战:从环境搭建到电商应用

ArkTS作为TypeScript的超集,是鸿蒙HarmonyOS应用开发的核心语言,通过声明式UI和强化类型系统提升开发效率。面向对象编程特性如类继承、接口实现等,配合单例模式、观察者模式等设计模式,可构建高可维护性应用。在组件化开发中,状态管理机制(@State/@Link)实现数据驱动UI更新,结合内置布局组件快速搭建界面。典型应用场景如电商APP开发,涉及商品列表展示、购物车管理等模块实现,需注意列表性能优化和内存管理。HarmonyOS NEXT的DevEco Studio提供完整工具链支持,从环

weixin_34408624的博客 597

鸿蒙5.0进阶开发:UI开发-容器组件(swiper开发)

swiper为滑动容器,提供切换显示子组件的能力。

AyomQAQ的博客 878

鸿蒙开发入门:ArkTS与ArkUI实战指南

分布式操作系统是现代计算领域的重要发展方向,鸿蒙系统(HarmonyOS)作为华为自主研发的全场景操作系统,采用微内核架构实现跨设备协同。其核心技术包括声明式UI框架和ArkTS编程语言,ArkTS作为TypeScript的超集,通过静态类型检查和装饰器语法显著提升开发效率。在工程实践中,鸿蒙的DevEco Studio工具链提供了从编码到调试的完整支持,特别适合开发需要适配多种终端设备的应用。对于Android开发者转型鸿蒙,理解声明式编程范式与状态管理机制是关键突破点,这能帮助开发者快速构建高性能的分布

weixin_34292402的博客 417

手把手教你在全新服务器内网安装OpenEuler 22.03 LTS SP4+ 安装 openGuass 5.0.0(LTS) 数据库

openEuler是面向数字基础设施的操作系统,支持服务器、云计算、边缘计算、嵌入式等应用场景,支持多样性计算,致力于提供安全、稳定、易用的开源服务器Linux操作系统。

cgqyw的专栏 3740

鸿蒙系统开发

ArkTS 在保持 TypeScript(简称 TS)基本语法风格的基础上,进一步通过规范强化静态检查和分析,使得在程序运行之前的开发期能检测更多错误,并提升运行时性能。针对 JavaScript(简称JS)/TS 并发能力支持有限的问题,ArkTS 对并发编程 API 和能力进行了增强。(3)不支持structural typing。7、类和对象、集成和重写、多态和静态成员。(1)线性布局(Row/Column)(1)不支持在运行时更改对象布局。(2)层叠布局(stack)(3)弹性布局(Flex)

qq_55750963的博客 1176

三相Vienna整流器过零点电流畸变?试试这个SVPWM调制波补偿技巧

本文针对三相Vienna整流器在电流过零点附近出现的电流畸变问题,提出了一种基于SVPWM调制波补偿的有效解决方案。该方法通过注入零序分量重构占空比,巧妙解决因拓扑约束导致的调制矛盾,在基本不增加计算复杂度的前提下,显著平滑电流波形,降低THD。

weixin_29212867的博客 115

【HarmonyOS 6.0】ArkUI Swiper组件模拟拖拽功能深度解析

鸿蒙6.0 Swiper组件模拟拖拽功能解析 摘要 鸿蒙6.0为ArkUI Swiper组件新增模拟拖拽(Fake Drag)能力,使开发者可通过编程方式控制轮播图滑动。该功能支持在自动化测试、手势引导、远程控制等场景使用。模拟拖拽与真实拖拽效果一致,但触发源为代码而非用户触摸。 核心能力包括: 开启/关闭模拟拖拽:通过SwiperController的startFakeDrag()和stopFakeDrag()方法控制 设置拖拽距离:可指定滑动方向和偏移量(单位为vp) 获取拖拽状态

枫叶丹4的博客 726

深入学习FIFO

深入理解FIFO、同步FIFO和异步FIFO、FIFO设计的难点以及FIFO深度计算

好好学习,天天向上 2652

MAPPO实战:从理论到代码的协作智能体训练指南

本文详细介绍了MAPPO算法在多智能体协作训练中的实战应用,从理论基础到代码实现全面解析。通过对比PPO与MAPPO的差异,深入讲解CTDE框架、网络架构设计、参数调优等关键环节,并提供实际项目中的调参经验和常见问题解决方案,帮助开发者快速掌握这一强化学习前沿技术。

weixin_42561040的博客 267

HarmonyOS鸿蒙开发:Swiper组件实现精美轮播图

本文详细介绍了HarmonyOS中Swiper轮播图组件的实现方法。Swiper组件支持水平/垂直滑动、自动播放、循环播放等功能,并可通过属性配置自定义切换动画、指示器样式等。教程展示了基于网络图片的基础轮播图实现代码,强调需添加网络权限,并提供了常用属性配置示例。文章还总结了ArkUI框架在轮播图开发中的优势,帮助开发者快速掌握这一常见UI组件的实现技巧。最后作者分享了多个Android开发实战视频教程资源。

商城app+新闻app+备忘录记事本app视频教程在某站【浩宇软件开发】 638

基于Pascal VOC数据集的YOLOv8目标检测系统实现:人、鸟、猫、牛、电视、车等20类目标识别与UI界面部署全流程详解

VOC 2007、VOC 2012 两个主要版本;每个图像提供 bounding box(目标框)+ 目标类别;共计 20 类,所有图像手工标注,质量高。完整复现 Pascal VOC 20类检测任务成功训练 YOLOv8 模型实现可视化 UI + 实时检测系统支持多平台部署和演示。

YOLO 772

HarmonyOS6 ArkTS Indicator

Indicator(指示器)是HarmonyOS ArkTS中用于配合轮播组件Swiper展示当前页面位置、分页状态的核心UI组件,也可独立作为分页导航使用。核心作用:直观展示当前页码/总页数,支持点击切换、手动控制、样式自定义圆点指示器(DotIndicator)数字指示器(DigitIndicator)适用场景:轮播图分页、引导页导航、卡片滑动分页、多页面切换状态展示Indicator组件是轮播场景的标配组件,具备易用性强、定制化高、兼容性好的特点。

qq_37048082的博客 5722

Zookeeper+Hadoop+Spark+Flink+Kafka+Hbase+Hive 完全分布式高可用集群搭建(保姆级超详细含图文) 附安装包网盘下载

Hadoop+Spark+Flink+Zookeeper+Kafka+Hbase+Hive完全分布式高可用集群搭建 Hadoop高可用集群搭建 Spark高可用集群搭建 Flink高可用集群搭建 Zookeeper高可用集群搭建 Kafka高可用集群搭建 Hbase高可用集群搭建 Hive高可用集群搭建 mysql搭建 jdk部署 大数据集群环境搭建

Mr.L-OAM的博客 2万+

OpenClaw实战系列·进阶特辑02:多智能体协同——打造企业级AI中台

**企业级AI中台面临多Agent协同的挑战,本文提出基于多智能体协同的解决方案。通过分析单Agent的局限性(上下文溢出、专业度稀释等)和多Agent的核心优势(任务专注度、故障隔离等),提出三种协作架构模式(指挥型、联邦型、点对点型),并强调人格化设计的重要性。文章详细介绍Agent间通讯机制(同步/异步会话、文件系统协作)和"身脑分离"的解耦架构设计,提供可落地的企业级AI中台实施方案。

PeterPan的博客 495

鸿蒙HarmonyOS 5.0开发实战:短视频切换实现案例

本文基于Swiper组件和Video组件实现短视频切换功能。

m0_73088370的博客 806

基于Spring Security 6的OAuth2 系列之二 - 客户端--非代码演示授权码模式

至此,我们就使用浏览器+postman工具演示了通过授权码模式去获取Gitee的用户信息。这过程中,我们只是遵循OAuth2的流程,就能够实现授权方法。那么接下来,我们采用代码方式来实现这个流程。

代码让AI扣 1813

鸿蒙5.0开发进阶:使用NDK接口构建UI(懒加载开发长列表界面)

针对List、Grid、WaterFlow、Swiper组件,提供NodeAdapter对象替代ArkTS侧的LazyForEach功能...........

Androidbye的博客 1189

Data-Structures-and-Algorithm-Analysis-in-Java.pdf

作者: Weiss, Mark A. 出版社: Addison Wesley Data Structures and Algorithm Analysis in Java is an “advanced algorithms” book that fits between traditional CS2 and Algorithms Analysis courses. In the old ACM Curriculum Guidelines, this course was known as CS7. This text is for readers who want to learn good programming and algorithm analysis skills simultaneously so that they can develop such programs with the maximum amo...

WINCC7.3破解文件

WINCC7.3硬件够破解文件,有需要的下载!WINCC7.3硬件够破解文件,有需要的下载!

HarmonyOS ArkTS 常用 UI 组件通用样式规范手册

在 HarmonyOS 应用开发过程中,统一的组件样式规范不仅可以让项目 UI 视觉保持一致性、降低多页面的视觉割裂感,还能大幅减少重复样式代码编写、提升团队协作开发效率。本文基于 ArkTS 开发中高频使用的轮播图、选项卡、文本、输入框、按钮、图片、单选框7 类核心组件,整理一套可直接落地复用的通用样式设计规范,同时附带代码示例,新手可直接参考复用。降低 UI 返工成本:统一尺寸、圆角、色值、边距标准,前端开发可严格按照设计规范还原效果图,减少设计反复对齐调整的工作量。代码高复用。

2401_88832378的博客 361

蓝牙模块HM-10手册

蓝牙模块HM-10手册,该手册对蓝牙模块HM-10进行了详细的介绍和使用方法以及一些AT指令。

上一篇: 鸿蒙5.0开发进阶:UI框架-ArkTS组件(Scroll)
下一篇: 鸿蒙5.0开发进阶:UI框架-ArkTS组件(WaterFlow)
懂你的大海
博客等级 码龄6年 9049粉丝 1381原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值