1# Swiper 2 3 滑块视图容器，提供子组件滑动轮播显示的能力。 4 5> **说明：** 6> 7> - 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> - Swiper组件[通用属性clip](ts-universal-attributes-sharp-clipping.md)的默认值为true。 10> 11> - Swiper组件内包含了[PanGesture](ts-basic-gestures-pangesture.md)拖动手势事件，用于滑动轮播子组件。[disableSwipe](#disableswipe8)属性设为true会取消内部的PanGesture事件监听。 12 13## 子组件 14 15可以包含子组件。 16 17> **说明：** 18> 19> - 子组件类型：系统组件和自定义组件，支持渲染控制类型（[if/else](../../../quick-start/arkts-rendering-control-ifelse.md)、[ForEach](../../../quick-start/arkts-rendering-control-foreach.md)、[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)和[Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md)）。不建议子组件中混用懒加载组件（包括LazyForEach、Repeat）和非懒加载组件，或者子组件中使用多个懒加载组件，否则可能导致懒加载组件预加载能力失效等问题。 20> 21> - Swiper子组件的visibility属性设置为None，Swiper的displayCount属性设置为'auto'时，对应子组件在视窗内不占位，但不影响导航点个数。 22> 23> - Swiper子组件的visibility属性设置为None，或者visibility属性设置为Hidden时，对应子组件不显示，但依然会在视窗内占位。 24> 25> - 当Swiper子组件个数小于等于Swiper组件内容区内显示的节点总个数(totalDisplayCount = DisplayCount + prevMargin? (1 : 0) + nextMargin? (1 : 0))时，一般按照非循环模式布局处理，此时，前后边距对应子组件不显示，但依然会在视窗内占位。Swiper组件按照totalDisplayCount个数判断测算规格。例外情况如下： 26> 27> - 当Swiper子组件个数等于Swiper组件内容区内显示的节点总个数且prevMargin和nextMargin都生效时，设置loop为true支持循环。 28> 29> - 当Swiper子组件个数等于Swiper组件DisplayCount数 + 1，且prevMargin和nextMargin至少一个生效时，设置loop为true会生成截图占位组件(如果使用图片异步加载等显示耗时较长的组件可能不能正确生成截图，不建议在该场景开启循环)，支持循环。 30> 31> - 当Swiper子组件设置了offset属性时，会按照子组件的层级进行绘制，层级高的子组件会覆盖层级低的子组件。例如，Swiper包含3个子组件，其中第3个子组件设置了offset({ x : 100 })，那么在横向循环滑动中，第3个子组件会覆盖第1个子组件，此时可设置第1个子组件的zIndex属性值大于第3个子组件，使第1个子组件层级高于第3个子组件。 32> 33> - 当使用渲染控制类型（[if/else](../../../quick-start/arkts-rendering-control-ifelse.md)、[ForEach](../../../quick-start/arkts-rendering-control-foreach.md)、[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)和[Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md)）时，不要在组件动画过程中对数据源进行操作，否则会导致布局出现异常。 34 35## 接口 36 37Swiper(controller?: SwiperController) 38 39**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 40 41**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 42 43**系统能力：** SystemCapability.ArkUI.ArkUI.Full 44 45**参数：** 46 47| 参数名 | 类型 | 必填 | 说明 | 48| ---------- | ------------------------------------- | ---- | -------------------- | 49| controller | [SwiperController](#swipercontroller) | 否 | 给组件绑定一个控制器，用来控制组件翻页。 | 50 51 52## 属性 53 54除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 55 56### index 57 58index(value: number) 59 60设置当前在容器中显示的子组件的索引值。设置小于0或大于等于子组件数量时，按照默认值0处理。 61 62从API version 10开始，该属性支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。 63 64**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 65 66**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 67 68**系统能力：** SystemCapability.ArkUI.ArkUI.Full 69 70**参数：** 71 72| 参数名 | 类型 | 必填 | 说明 | 73| ------ | ------ | ---- | ------------------------------------------------ | 74| value | number | 是 | 当前在容器中显示的子组件的索引值。<br/>默认值：0 <br/>**说明：** <br/>设置的值小于0或大于最大页面索引时，取0。| 75 76### autoPlay 77 78autoPlay(value: boolean) 79 80设置子组件是否自动播放。 81 82loop为false时，自动轮播到最后一页时停止轮播。手势切换后不是最后一页时继续播放。当Swiper不可见时会停止轮播。 83 84**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 85 86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| ------ | ------- | ---- | -------------------------------------- | 94| value | boolean | 是 | 子组件是否自动播放。<br/>默认值：false | 95 96### interval 97 98interval(value: number) 99 100设置使用自动播放时播放的时间间隔。 101 102**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 103 104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 105 106**系统能力：** SystemCapability.ArkUI.ArkUI.Full 107 108**参数：** 109 110| 参数名 | 类型 | 必填 | 说明 | 111| ------ | ------ | ---- | ---------------------------------------------------------- | 112| value | number | 是 | 自动播放时播放的时间间隔。<br/>默认值：3000<br/>单位：毫秒 | 113 114### indicator 115 116indicator(value: DotIndicator | DigitIndicator | boolean) 117 118设置可选导航点指示器样式。 119 120**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 121 122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 130| value | [DotIndicator](#dotindicator10)<sup>10+</sup> \| [DigitIndicator](#digitindicator10)<sup>10+</sup> \| boolean | 是 | 可选导航点指示器样式。<br/> \- DotIndicator：圆点指示器样式。<br/> \- DigitIndicator：数字指示器样式。<br/> \- boolean：是否启用导航点指示器。设置为true启用，false不启用。<br/> 默认值：true<br/> 默认类型：DotIndicator | 131 132### loop 133 134loop(value: boolean) 135 136设置是否开启循环。设置为true时表示开启循环，在LazyForEach懒循环加载模式下，加载的组件数量建议大于5个。 137 138**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 139 140**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 141 142**系统能力：** SystemCapability.ArkUI.ArkUI.Full 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147| ------ | ------- | ---- | ------------------------------- | 148| value | boolean | 是 | 是否开启循环。<br/>默认值：true | 149 150### duration 151 152duration(value: number) 153 154设置子组件切换的动画时长。 155 156duration需要和[curve](#curve8)一起使用。 157 158curve默认曲线为[interpolatingSpring](../js-apis-curve.md#curvesinterpolatingspring10)，此时动画时长只受曲线自身参数影响，不再受duration的控制。不受duration控制的曲线可以查阅[插值计算](../js-apis-curve.md)模块，比如，[springMotion](../js-apis-curve.md#curvesspringmotion9) 159、[responsiveSpringMotion](../js-apis-curve.md#curvesresponsivespringmotion9)和interpolatingSpring类型的曲线不受duration控制。如果希望动画时长受到duration控制，需要给curve设置其他曲线。 160 161**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 162 163**系统能力：** SystemCapability.ArkUI.ArkUI.Full 164 165**参数：** 166 167| 参数名 | 类型 | 必填 | 说明 | 168| ------ | ------ | ---- | ----------------------------------------------------- | 169| value | number | 是 | 子组件切换的动画时长。<br/>默认值：400<br/>单位：毫秒 | 170 171### vertical 172 173vertical(value: boolean) 174 175设置是否为纵向滑动。 176 177**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 178 179**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 180 181**系统能力：** SystemCapability.ArkUI.ArkUI.Full 182 183**参数：** 184 185| 参数名 | 类型 | 必填 | 说明 | 186| ------ | ------- | ---- | ---------------------------------- | 187| value | boolean | 是 | 是否为纵向滑动。true为纵向滑动，false为横向滑动。<br/>默认值：false | 188 189### itemSpace 190 191itemSpace(value: number | string) 192 193设置子组件与子组件之间间隙。不支持设置百分比。 194 195类型为number时，默认单位vp。类型为string时，需要显式指定像素单位，如'10px'；未指定像素单位时，如'10'，单位为vp。 196 197**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 198 199**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 200 201**系统能力：** SystemCapability.ArkUI.ArkUI.Full 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| ------ | -------------------------- | ---- | -------------------------------------- | 207| value | number \| string | 是 | 子组件与子组件之间间隙。<br/>默认值：0 | 208 209### displayMode 210 211displayMode(value: SwiperDisplayMode) 212 213设置主轴方向上元素排列的模式，优先以displayCount设置的个数显示，displayCount未设置时本属性生效。 214 215**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 216 217**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 218 219**系统能力：** SystemCapability.ArkUI.ArkUI.Full 220 221**参数：** 222 223| 参数名 | 类型 | 必填 | 说明 | 224| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 225| value | [SwiperDisplayMode](#swiperdisplaymode枚举说明) | 是 | 主轴方向上元素排列的模式。<br/>默认值：SwiperDisplayMode.STRETCH | 226 227### cachedCount<sup>8+</sup> 228 229cachedCount(value: number) 230 231设置预加载子组件个数，以当前页面为基准，加载当前显示页面的前后个数。例如cachedCount=1时，会将当前显示的页面的前面一页和后面一页的子组件都预加载。如果设置为按组翻页，即displayCount的swipeByGroup参数设为true，预加载时会以组为基本单位。例如cachedCount=1，swipeByGroup=true时，会将当前组的前面一组和后面一组的子组件都预加载。 232 233**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 234 235**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 236 237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 238 239**参数：** 240 241| 参数名 | 类型 | 必填 | 说明 | 242| ------ | ------ | ---- | -------------------------------- | 243| value | number | 是 | 预加载子组件个数。<br/>默认值：1 | 244 245### disableSwipe<sup>8+</sup> 246 247disableSwipe(value: boolean) 248 249设置禁用组件滑动切换功能。 250 251**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 252 253**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 254 255**系统能力：** SystemCapability.ArkUI.ArkUI.Full 256 257**参数：** 258 259| 参数名 | 类型 | 必填 | 说明 | 260| ------ | ------- | ---- | ---------------------------------------- | 261| value | boolean | 是 | 禁用组件滑动切换功能。设置为true禁用，false不禁用。<br/>默认值：false | 262 263### curve<sup>8+</sup> 264 265curve(value: Curve | string | ICurve) 266 267设置Swiper的动画曲线，默认为弹簧插值曲线，常用曲线参考[Curve枚举说明](ts-appendix-enums.md#curve)，也可以通过[插值计算](../js-apis-curve.md)模块提供的接口创建自定义的插值曲线对象。 268 269**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 270 271**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 272 273**系统能力：** SystemCapability.ArkUI.ArkUI.Full 274 275**参数：** 276 277| 参数名 | 类型 | 必填 | 说明 | 278| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------- | 279| value | [Curve](ts-appendix-enums.md#curve) \| string \| [ICurve](../js-apis-curve.md#icurve9)<sup>10+</sup> | 是 | Swiper的动画曲线。<br/>默认值：interpolatingSpring(-1, 1, 328, 34) | 280 281### indicatorStyle<sup>(deprecated)</sup> 282 283indicatorStyle(value?: IndicatorStyle) 284 285设置导航点样式。 286 287从API version 8开始支持，从API version 10开始不再维护，建议使用[indicator](#indicator10)代替。 288 289**系统能力：** SystemCapability.ArkUI.ArkUI.Full 290 291**参数：** 292 293| 参数名 | 类型 | 必填 | 说明 | 294| ------ | --------------------------------------------------- | ---- | ------------ | 295| value | [IndicatorStyle](#indicatorstyledeprecated对象说明) | 否 | 导航点样式。 | 296 297### displayCount<sup>8+</sup> 298 299displayCount(value: number | string | SwiperAutoFill, swipeByGroup?: boolean) 300 301设置Swiper视窗内元素显示个数。 302 303字符串类型仅支持设置为'auto'。 304 305使用number类型且设置小于等于0时，按默认值1显示。 306 307使用number类型时，子组件按照主轴均分Swiper宽度（减去displayCount-1个itemSpace）的方式进行主轴拉伸（收缩）布局。 308 309使用SwiperAutoFill类型时，通过设置一个子组件最小宽度值minSize，会根据Swiper当前宽度和minSize值自动计算并更改一页内元素显示个数。当minSize为空或者小于等于0时，Swiper显示1列。 310 311当按组进行翻页时，如果最后一组的子元素数量小于displayCount时，会使用占位子元素补齐。占位子元素只是用于布局占位，不显示任何内容。在占位子元素的位置会直接显示Swiper自身的背景样式。 312 313在按组翻页时，判断翻页的拖拽距离阈值条件，会更新为Swiper自身宽度的一半。（按子元素翻页时，该阈值为子元素自身宽度的一半）。 314 315**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 316 317**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 318 319**系统能力：** SystemCapability.ArkUI.ArkUI.Full 320 321**参数：** 322 323| 参数名 | 类型 | 必填 | 说明 | 324| -------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 325| value | number \| string \| [SwiperAutoFill](#swiperautofill10)<sup>10+</sup> | 是 | 视窗内显示的子元素个数。<br/> 默认值：1 | 326| swipeByGroup<sup>11+</sup> | boolean | 否 | 是否按组进行翻页。如果设为true，在翻页时会按组进行翻页，每组内子元素的数量为displayCount value的值；如果为false，则为默认翻页行为，即按照子元素进行翻页。<br/> 默认值：false | 327 328### effectMode<sup>8+</sup> 329 330effectMode(value: EdgeEffect) 331 332设置边缘滑动效果，loop = false时生效。 目前支持的滑动效果参见EdgeEffect的枚举说明。控制器接口调用时不生效回弹。 333 334**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 335 336**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 337 338**系统能力：** SystemCapability.ArkUI.ArkUI.Full 339 340**参数：** 341 342| 参数名 | 类型 | 必填 | 说明 | 343| ------ | --------------------------------------------- | ---- | -------------------------------------------- | 344| value | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 是 | 边缘滑动效果。<br/>默认值：EdgeEffect.Spring | 345 346### displayArrow<sup>10+</sup> 347 348displayArrow(value: ArrowStyle | boolean, isHoverShow?: boolean) 349 350设置导航点箭头样式。 351 352**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 353 354**系统能力：** SystemCapability.ArkUI.ArkUI.Full 355 356**参数：** 357 358| 参数名 | 类型 | 必填 | 说明 | 359| -------------------------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 360| value | [ArrowStyle](#arrowstyle10对象说明) \| boolean | 是 | 支持设置箭头和底板样式，异常场景使用ArrowStyle对象中的默认值。设置为false不显示箭头和底板，true显示默认的箭头和底板样式。<br/>默认值：false | 361| isHoverShow | boolean | 否 | 设置鼠标悬停时是否显示箭头。<br/>默认值：false<br/>**说明：**<br/>isHoverShow为false时，常驻显示箭头，支持点击翻页。<br/>isHoverShow为true时，只有在鼠标悬停时才会显示箭头，并支持点击翻页。 | 362 363> **说明：** 364> 365> Swiper视窗内显示所有子节点时，只显示一屏，无法翻页，左右翻页箭头均不显示。 366 367### nextMargin<sup>10+</sup> 368 369nextMargin(value: Length, ignoreBlank?:boolean) 370 371设置后边距，用于露出后一项的一小部分。仅当Swiper子组件的布局方式为拉伸时生效，主要包括两种场景：1、displayMode属性设置为SwiperDisplayMode.STRETCH；2、displayCount属性设置为number类型。 372 373当主轴方向为横向布局时，nextMargin/prevMargin中任意一个大于子组件测算的宽度，nextMargin和prevMargin均不显示。 374 375当主轴方向为纵向布局时，nextMargin/prevMargin中任意一个大于子组件测算的高度，nextMargin和prevMargin均不显示。 376 377**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 378 379**系统能力：** SystemCapability.ArkUI.ArkUI.Full 380 381**参数：** 382 383| 参数名 | 类型 | 必填 | 说明 | 384| ------ | ---------------------------- | ---- | ---------------------- | 385| value | [Length](ts-types.md#length) | 是 | 后边距。<br/>默认值：0 | 386| ignoreBlank<sup>12+</sup> | boolean | 否 | 非loop场景下尾页不显示nextMargin。在非loop场景下，设置为true时，尾页不显示空白的nextMargin，尾页的右边缘与Swiper视窗右边缘对齐；设置false时，尾页显示空白nextMargin，尾页的右边缘与Swiper视窗右边缘的距离为nextMargin。<br/>默认值：false <br/>**说明：**<br/>尾页场景下，prevMargin和nextMargin的值相加作为左边边距显示前一个页面。 | 387 388### prevMargin<sup>10+</sup> 389 390prevMargin(value: Length, ignoreBlank?:boolean) 391 392设置前边距，用于露出前一项的一小部分。仅当Swiper子组件的布局方式为拉伸时生效，主要包括两种场景：1、displayMode属性设置为SwiperDisplayMode.STRETCH；2、displayCount属性设置为number类型。 393 394当主轴方向为横向布局时，nextMargin/prevMargin中任意一个大于子组件测算的宽度，nextMargin和prevMargin均不显示。 395 396当主轴方向为纵向布局时，nextMargin/prevMargin中任意一个大于子组件测算的高度，nextMargin和prevMargin均不显示。 397 398**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 399 400**系统能力：** SystemCapability.ArkUI.ArkUI.Full 401 402**参数：** 403 404| 参数名 | 类型 | 必填 | 说明 | 405| ------ | ---------------------------- | ---- | ---------------------- | 406| value | [Length](ts-types.md#length) | 是 | 前边距。<br/>默认值：0 | 407| ignoreBlank<sup>12+</sup> | boolean | 否 | 非loop场景下首页不显示prevMargin。在非loop场景下，设置为true时，首页不显示空白的prevMargin，首页的左边缘与Swiper视窗左边缘对齐；设置false时，首页显示空白prevMargin，首页的左边缘与Swiper视窗左边缘的距离为prevMargin。<br/>默认值：false <br/>**说明：**<br/>首页场景下，prevMargin和nextMargin的值相加作为右边边距显示后一个页面。| 408 409### nestedScroll<sup>11+</sup> 410 411nestedScroll(value: SwiperNestedScrollMode) 412 413设置Swiper组件和父组件的嵌套滚动模式。loop为true时Swiper组件没有边缘，不会触发父组件嵌套滚动。 414 415**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 416 417**系统能力：** SystemCapability.ArkUI.ArkUI.Full 418 419**参数：** 420 421| 参数名 | 类型 | 必填 | 说明 | 422| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 423| value | [SwiperNestedScrollMode](#swipernestedscrollmode11枚举说明) | 是 | Swiper组件和父组件的嵌套滚动模式。<br/>默认值：SwiperNestedScrollMode.SELF_ONLY | 424 425> **说明：** 426> 427> 由于Swiper的抛滑动画逻辑和其它滚动类组件不同（Swiper一次只能滑动一页，抛滑时做翻页动画），当Swiper内嵌套其它滚动组件时，如果Swiper的翻页动画已经启动，将无法接受子节点上传的滚动偏移量。这时Swiper的翻页动画和子节点的边缘效果动画会同时执行。 428 429### indicatorInteractive<sup>12+</sup> 430 431indicatorInteractive(value: boolean) 432 433设置禁用组件导航点交互功能。设置为true时表示导航点可交互。 434 435**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 436 437**系统能力：** SystemCapability.ArkUI.ArkUI.Full 438 439**参数：** 440 441| 参数名 | 类型 | 必填 | 说明 | 442| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 443| value | boolean | 是 | 导航点是否可交互。<br/>默认值：true | 444 445## IndicatorStyle<sup>(deprecated)</sup>对象说明 446 447从API version 8开始支持，从API version 10开始不再维护，建议使用[indicator](#indicator10)代替。 448 449**系统能力：** SystemCapability.ArkUI.ArkUI.Full 450 451| 名称 | 类型 | 必填 | 说明 | 452| ------------- | ------------------------------------------ | ---- | ---------------------------------------------------- | 453| left | [Length](ts-types.md#length) | 否 | 设置导航点左侧相对于Swiper的位置。<br/>未设置left和right时，进行自适应大小布局，按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐<br/>设置为0时：按照0位置布局计算<br/>优先级：高于right属性<br/>取值范围：[0,Swiper宽度-导航点区域宽度]，超出该范围时，取最近的的边界值。 | 454| top | [Length](ts-types.md#length) | 否 | 设置导航点顶部相对于Swiper的位置。<br/>未设置top和bottom时，进行自适应大小布局，按照指示器本身大小和Swiper的大小，在交叉轴方向上，位于底部，效果与设置bottom=0一致<br/>设置为0时：按照0位置布局计算<br/>优先级：高于bottom属性<br/>取值范围：[0,Swiper高度-导航点区域高度]，超出该范围时，取最近的边界值。 | 455| right | [Length](ts-types.md#length) | 否 | 设置导航点右侧相对于Swiper的位置。<br/>未设置left和right时，进行自适应大小布局，按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐<br/>设置为0时：按照0位置布局计算<br/>优先级：低于left属性<br/>取值范围：[0,Swiper宽度-导航点区域宽度]，超出该范围时，取最近的边界值。 | 456| bottom | [Length](ts-types.md#length) | 否 | 设置导航点底部相对于Swiper的位置。<br/>未设置top和bottom时，进行自适应大小布局，按照指示器本身大小和Swiper的大小，在交叉轴方向上，位于底部，效果与设置bottom=0一致<br/>设置为0时：按照0位置布局计算<br/>优先级：低于top属性<br/>取值范围：[0,Swiper高度-导航点区域高度]，超出该范围时，取最近的边界值。 | 457| size | [Length](ts-types.md#length) | 否 | 设置导航点的直径，不支持设置百分比。<br/>默认值：6vp | 458| mask | boolean | 否 | 设置是否显示导航点蒙层样式。 | 459| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置导航点的颜色。 | 460| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置选中的导航点的颜色。 | 461 462## SwiperDisplayMode枚举说明 463 464Swiper在主轴上的尺寸大小模式枚举。 465 466**系统能力：** SystemCapability.ArkUI.ArkUI.Full 467 468| 名称 | 说明 | 469| ---------------------------------- | ------------------------------------------------------------ | 470| Stretch<sup>(deprecated)</sup> | Swiper滑动一页的宽度为Swiper组件自身的宽度。<br>从API version 10开始不再维护，建议使用STRETCH代替。<br/>**卡片能力：** 从API version 7开始，该接口支持在ArkTS卡片中使用。 | 471| AutoLinear<sup>(deprecated)</sup> | Swiper滑动一页的宽度为子组件宽度中的最大值。<br>从API version 10开始不再维护，建议使用[Scroller.scrollTo](ts-container-scroll.md#scrollto)代替。<br/>**卡片能力：** 从API version 7开始，该接口支持在ArkTS卡片中使用。 | 472| STRETCH<sup>10+</sup> | Swiper滑动一页的宽度为Swiper组件自身的宽度。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 473| AUTO_LINEAR<sup>(deprecated)</sup> | Swiper滑动一页的宽度为视窗内最左侧子组件的宽度。<br/>从API version 10开始支持，从API version 12开始不再维护，建议使用[Scroller.scrollTo](ts-container-scroll.md#scrollto)代替。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 474 475## SwiperNestedScrollMode<sup>11+</sup>枚举说明 476 477Swiper组件和父组件的嵌套滚动模式枚举。 478 479**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 480 481**系统能力：** SystemCapability.ArkUI.ArkUI.Full 482 483| 名称 | 值 | 说明 | 484| ------------ | -- | ---------------------------------------- | 485| SELF_ONLY | 0 | Swiper只自身滚动，不与父组件联动。 | 486| SELF_FIRST | 1 | Swiper自身先滚动，自身滚动到边缘以后父组件滚动。父组件滚动到边缘以后，如果父组件有边缘效果，则父组件触发边缘效果，否则Swiper触发边缘效果。 | 487 488## SwiperController 489 490Swiper容器组件的控制器，可以将此对象绑定至Swiper组件，可以通过它控制翻页。 491 492**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 493 494**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 495 496**系统能力：** SystemCapability.ArkUI.ArkUI.Full 497 498### 导入对象 499 500```ts 501let controller: SwiperController = new SwiperController() 502``` 503 504### constructor 505 506constructor() 507 508SwiperController的构造函数。 509 510**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 511 512**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 513 514**系统能力：** SystemCapability.ArkUI.ArkUI.Full 515 516### showNext 517 518showNext() 519 520翻至下一页。翻页带动效切换过程，时长通过duration指定。 521 522**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 523 524**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 525 526**系统能力：** SystemCapability.ArkUI.ArkUI.Full 527 528### showPrevious 529 530showPrevious() 531 532翻至上一页。翻页带动效切换过程，时长通过duration指定。 533 534**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 535 536**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 537 538**系统能力：** SystemCapability.ArkUI.ArkUI.Full 539 540### changeIndex<sup>12+</sup> 541 542changeIndex(index: number, useAnimation?: boolean) 543 544翻至指定页面。 545 546**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 547 548**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 549 550**系统能力：** SystemCapability.ArkUI.ArkUI.Full 551 552**参数：** 553 554| 参数名 | 类型 | 必填 | 说明 | 555| -------- | ---------- | ---- | -------- | 556| index| number | 是 | 指定页面在Swiper中的索引值。<br/>**说明：** <br/>设置的值小于0或大于最大页面索引时，取0。 | 557| useAnimation| boolean | 否 | 设置翻至指定页面时是否有动效，true表示有动效，false表示没有动效。<br/>默认值：false。 | 558 559### finishAnimation 560 561finishAnimation(callback?: () => void) 562 563停止播放动画。 564 565**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 566 567**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 568 569**系统能力：** SystemCapability.ArkUI.ArkUI.Full 570 571**参数：** 572 573| 参数名 | 类型 | 必填 | 说明 | 574| -------- | ---------- | ---- | -------- | 575| callback | () => void | 否 | 动画结束的回调。 | 576 577## Indicator<sup>10+</sup> 578 579设置导航点距离Swiper组件距离。由于导航点有默认交互区域，交互区域高度为32vp, 所以无法让显示部分完全贴底。 580 581**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 582 583**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 584 585**系统能力：** SystemCapability.ArkUI.ArkUI.Full 586 587### left 588 589left(value: Length): T 590 591导航点左侧相对于Swiper的位置。 592 593**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 594 595**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 596 597**系统能力：** SystemCapability.ArkUI.ArkUI.Full 598 599**参数：** 600 601| 参数名 | 类型 | 必填 | 说明 | 602| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 603| value | [Length](ts-types.md#length) | 是 | 设置导航点左侧相对于Swiper的位置。<br/>未设置left和right时，进行自适应大小布局，按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐。<br/>设置为0时：按照0位置布局计算。<br/>优先级：高于right属性。<br/>取值范围：[0,Swiper宽度-导航点区域宽度]，超出该范围时，取最近的的边界值。 | 604 605### top 606 607top(value: Length): T 608 609导航点顶部相对于Swiper的位置。 610 611**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 612 613**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 614 615**系统能力：** SystemCapability.ArkUI.ArkUI.Full 616 617**参数：** 618 619| 参数名 | 类型 | 必填 | 说明 | 620| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 621| value | [Length](ts-types.md#length) | 是 | 设置导航点顶部相对于Swiper的位置。<br/>未设置top和bottom时，进行自适应大小布局，按照指示器本身大小和Swiper的大小，在交叉轴方向上，位于底部，效果与设置bottom=0一致。<br/>设置为0时：按照0位置布局计算。<br/>优先级：高于bottom属性。<br/>取值范围：[0,Swiper高度-导航点区域高度]，超出该范围时，取最近的边界值。 | 622 623### right 624 625right(value: Length): T 626 627导航点右侧相对于Swiper的位置。 628 629**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 630 631**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 632 633**系统能力：** SystemCapability.ArkUI.ArkUI.Full 634 635**参数：** 636 637| 参数名 | 类型 | 必填 | 说明 | 638| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 639| value | [Length](ts-types.md#length) | 是 | 设置导航点右侧相对于Swiper的位置。<br/>未设置left和right时，进行自适应大小布局，按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐。<br/>设置为0时：按照0位置布局计算。<br/>优先级：低于left属性。<br/>取值范围：[0,Swiper宽度-导航点区域宽度]，超出该范围 时，取最近的边界值。 | 640 641### bottom 642 643bottom(value: Length): T 644 645导航点底部相对于Swiper的位置。 646 647**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 648 649**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 650 651**系统能力：** SystemCapability.ArkUI.ArkUI.Full 652 653**参数：** 654 655| 参数名 | 类型 | 必填 | 说明 | 656| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 657| value | [Length](ts-types.md#length) | 是 | 设置导航点底部相对于Swiper的位置。<br/>未设置top和bottom时，进行自适应大小布局，按照指示器本身大小和Swiper的大小，在交叉轴方向上，位于底部，效果与设置bottom=0一致。<br/>设置为0时：按照0位置布局计算。<br/>优先级：低于top属性。<br/>取值范围：[0,Swiper高度-导航点区域高度]，超出该范围时，取最近的边界值。 | 658 659### start<sup>12+</sup> 660 661start(value: LengthMetrics): T 662 663在RTL模式下为导航点距离Swiper组件右边的距离，在LTR模式下为导航点距离Swiper组件左边的距离。 664 665**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 666 667**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 668 669**系统能力：** SystemCapability.ArkUI.ArkUI.Full 670 671**参数：** 672 673| 参数名 | 类型 | 必填 | 说明 | 674| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 675| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 是 | 设置在RTL模式下为导航点距离Swiper组件右边的距离，在LTR模式下为导航点距离Swiper组件左边的距离<br/>默认值：0<br/>单位：vp | 676 677### end<sup>12+</sup> 678 679end(value: LengthMetrics): T 680 681在RTL模式下为导航点距离Swiper组件左边的距离，在LTR模式下为导航点距离Swiper组件右边的距离。 682 683**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 684 685**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 686 687**系统能力：** SystemCapability.ArkUI.ArkUI.Full 688 689**参数：** 690 691| 参数名 | 类型 | 必填 | 说明 | 692| ------ | ---------------------------- | ---- | ---------------------------------------- | 693| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 是 | 设置在RTL模式下为导航点距离Swiper组件左边的距离，在LTR模式下为导航点距离Swiper组件右边的距离。<br/>默认值：0<br/>单位：vp <br/>**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 694 695### dot 696 697static dot(): DotIndicator 698 699返回一个DotIndicator对象。 700 701**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 702 703**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 704 705**系统能力：** SystemCapability.ArkUI.ArkUI.Full 706 707### digit 708 709static digit(): DigitIndicator 710 711返回一个DigitIndicator对象。 712 713**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 714 715**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 716 717**系统能力：** SystemCapability.ArkUI.ArkUI.Full 718 719## DotIndicator<sup>10+</sup> 720 721构造圆点指示器的样式，继承自[Indicator](#indicator10)。 722 723**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 724 725**系统能力：** SystemCapability.ArkUI.ArkUI.Full 726 727### itemWidth 728 729itemWidth(value: Length): DotIndicator 730 731Swiper组件圆点导航指示器的宽，不支持设置百分比。 732 733**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 734 735**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 736 737**系统能力：** SystemCapability.ArkUI.ArkUI.Full 738 739**参数：** 740 741| 参数名 | 类型 | 必填 | 说明 | 742| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 743| value | [Length](ts-types.md#length) | 是 | 设置Swiper组件圆点导航指示器的宽，不支持设置百分比。<br/>默认值：6<br/>单位：vp | 744 745**返回值：** 746 747| 类型 | 说明 | 748| ------------------------------- | ------------ | 749| [DotIndicator](#dotindicator10) | 圆点指示器。 | 750 751### itemHeight 752 753itemHeight(value: Length): DotIndicator 754 755Swiper组件圆点导航指示器的高，不支持设置百分比。 756 757**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 758 759**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 760 761**系统能力：** SystemCapability.ArkUI.ArkUI.Full 762 763**参数：** 764 765| 参数名 | 类型 | 必填 | 说明 | 766| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 767| value | [Length](ts-types.md#length) | 是 | 设置Swiper组件圆点导航指示器的高，不支持设置百分比。<br/>默认值：6<br/>单位：vp | 768 769**返回值：** 770 771| 类型 | 说明 | 772| ------------------------------- | ------------ | 773| [DotIndicator](#dotindicator10) | 圆点指示器。 | 774 775### selectedItemWidth 776 777selectedItemWidth(value: Length): DotIndicator 778 779选中Swiper组件圆点导航指示器的宽，不支持设置百分比。 780 781**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 782 783**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 784 785**系统能力：** SystemCapability.ArkUI.ArkUI.Full 786 787**参数：** 788 789| 参数名 | 类型 | 必填 | 说明 | 790| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 791| value | [Length](ts-types.md#length) | 是 | 设置选中Swiper组件圆点导航指示器的宽，不支持设置百分比。<br/>默认值：12<br/>单位：vp | 792 793**返回值：** 794 795| 类型 | 说明 | 796| ------------------------------- | ------------ | 797| [DotIndicator](#dotindicator10) | 圆点指示器。 | 798 799### selectedItemHeight 800 801selectedItemHeight(value: Length): DotIndicator 802 803选中Swiper组件圆点导航指示器的高，不支持设置百分比。 804 805**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 806 807**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 808 809**系统能力：** SystemCapability.ArkUI.ArkUI.Full 810 811**参数：** 812 813| 参数名 | 类型 | 必填 | 说明 | 814| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 815| value | [Length](ts-types.md#length) | 是 | 设置选中Swiper组件圆点导航指示器的高，不支持设置百分比。<br/>默认值：6<br/>单位：vp | 816 817**返回值：** 818 819| 类型 | 说明 | 820| ------------------------------- | ------------ | 821| [DotIndicator](#dotindicator10) | 圆点指示器。 | 822 823### mask 824 825mask(value: boolean): DotIndicator 826 827是否显示Swiper组件圆点导航指示器的蒙版样式。 828 829**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 830 831**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 832 833**系统能力：** SystemCapability.ArkUI.ArkUI.Full 834 835**参数：** 836 837| 参数名 | 类型 | 必填 | 说明 | 838| ------ | ------- | ---- | ------------------------------------------------------------ | 839| value | boolean | 是 | 设置是否显示Swiper组件圆点导航指示器的蒙版样式。<br/>默认值：false | 840 841**返回值：** 842 843| 类型 | 说明 | 844| ------------------------------- | ------------ | 845| [DotIndicator](#dotindicator10) | 圆点指示器。 | 846 847### color 848 849color(value: ResourceColor): DotIndicator 850 851Swiper组件圆点导航指示器的颜色。 852 853**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 854 855**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 856 857**系统能力：** SystemCapability.ArkUI.ArkUI.Full 858 859**参数：** 860 861| 参数名 | 类型 | 必填 | 说明 | 862| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 863| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置Swiper组件圆点导航指示器的颜色。<br/>默认值：'\#182431'（10%透明度） | 864 865**返回值：** 866 867| 类型 | 说明 | 868| ------------------------------- | ------------ | 869| [DotIndicator](#dotindicator10) | 圆点指示器。 | 870 871### selectedColor 872 873selectedColor(value: ResourceColor): DotIndicator 874 875选中Swiper组件圆点导航指示器的颜色。 876 877**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 878 879**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 880 881**系统能力：** SystemCapability.ArkUI.ArkUI.Full 882 883**参数：** 884 885| 参数名 | 类型 | 必填 | 说明 | 886| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 887| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置选中Swiper组件圆点导航指示器的颜色。<br/>默认值：'\#007DFF' | 888 889**返回值：** 890 891| 类型 | 说明 | 892| ------------------------------- | ------------ | 893| [DotIndicator](#dotindicator10) | 圆点指示器。 | 894 895### maxDisplayCount<sup>12+</sup> 896 897maxDisplayCount(maxDisplayCount: number): DotIndicator 898 899圆点导航点指示器样式下，导航点显示个数最大值。 900 901**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 902 903**系统能力：** SystemCapability.ArkUI.ArkUI.Full 904 905**参数：** 906 907| 参数名 | 类型 | 必填 | 说明 | 908| --------------- | ------ | ---- | ------------------------------------------------------------ | 909| maxDisplayCount | number | 是 | 设置圆点导航点指示器样式下，导航点显示个数最大值，当实际导航点个数大于最大导航点个数时，会生效超长效果样式，样式如示例5所示。<br/>默认值：这个属性没有默认值，如果设置异常值那等同于没有超长显示效果。<br/>取值范围：6-9<br/>**说明：** <br/>1、超长显示场景，目前暂时不支持交互功能（包括：手指点击拖拽、鼠标操作等）。<br/>2、在超长显示场景下，中间页面对应的选中导航点的位置，并不是完全固定的，取决于之前的翻页操作序列。 | 910 911**返回值：** 912 913| 类型 | 说明 | 914| ------------------------------- | ------------ | 915| [DotIndicator](#dotindicator10) | 圆点指示器。 | 916 917### constructor 918 919constructor() 920 921DotIndicator的构造函数。 922 923**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 924 925**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 926 927**系统能力：** SystemCapability.ArkUI.ArkUI.Full 928 929>**说明：** 930> 931>按压导航点时，导航点会放大至1.33倍显示，因此非按压态时导航点的可见范围边界至实际范围边界存在一定距离，该距离会随着itemWidth、itemHeight、selectedItemWidth、selectedItemHeight等参数变大而变大。 932 933## DigitIndicator<sup>10+</sup> 934 935构造数字指示器的样式，继承自[Indicator](#indicator10)。 936 937**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 938 939**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 940 941**系统能力：** SystemCapability.ArkUI.ArkUI.Full 942 943>**说明：** 944> 945>按组翻页时，数字导航点显示的子节点数量，不包括占位节点。<br/> 946>数字导航点文本最大的字体缩放倍数[maxFontScale](ts-basic-components-text.md#maxfontscale12)为2。 947 948### fontColor 949 950fontColor(value: ResourceColor): DigitIndicator 951 952Swiper组件数字导航点的字体颜色。 953 954**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 955 956**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 957 958**系统能力：** SystemCapability.ArkUI.ArkUI.Full 959 960**参数：** 961 962| 参数名 | 类型 | 必填 | 说明 | 963| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 964| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置Swiper组件数字导航点的字体颜色。<br/>默认值：'\#ff182431' | 965 966**返回值：** 967 968| 类型 | 说明 | 969| ----------------------------------- | ------------ | 970| [DigitIndicator](#digitindicator10) | 数字指示器。 | 971 972### selectedFontColor 973 974selectedFontColor(value: ResourceColor): DigitIndicator 975 976选中Swiper组件数字导航点的字体颜色。 977 978**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 979 980**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 981 982**系统能力：** SystemCapability.ArkUI.ArkUI.Full 983 984**参数：** 985 986| 参数名 | 类型 | 必填 | 说明 | 987| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 988| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置选中Swiper组件数字导航点的字体颜色。<br/>默认值：'\#ff182431' | 989 990**返回值：** 991 992| 类型 | 说明 | 993| ----------------------------------- | ------------ | 994| [DigitIndicator](#digitindicator10) | 数字指示器。 | 995 996### digitFont 997 998digitFont(value: Font): DigitIndicator 999 1000Swiper组件数字导航点的字体样式。 1001 1002**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1003 1004**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1005 1006**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1007 1008**参数：** 1009 1010| 参数名 | 类型 | 必填 | 说明 | 1011| ------ | ------------------------ | ---- | ------------------------------------------------------------ | 1012| value | [Font](ts-types.md#font) | 是 | 设置Swiper组件数字导航点的字体样式。<br/>只支持Font中size和weight参数，family和style设置不生效。<br/>默认值：<br/>{ size: 14, weight: FontWeight.Normal } | 1013 1014**返回值：** 1015 1016| 类型 | 说明 | 1017| ----------------------------------- | ------------ | 1018| [DigitIndicator](#digitindicator10) | 数字指示器。 | 1019 1020### selectedDigitFont 1021 1022selectedDigitFont(value: Font): DigitIndicator 1023 1024选中Swiper组件数字导航点的字体样式。 1025 1026**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1027 1028**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1029 1030**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1031 1032**参数：** 1033 1034| 参数名 | 类型 | 必填 | 说明 | 1035| ------ | ------------------------ | ---- | ------------------------------------------------------------ | 1036| value | [Font](ts-types.md#font) | 是 | 设置选中Swiper组件数字导航点的字体样式。<br/>默认值：<br/>{ size: 14, weight: FontWeight.Normal } | 1037 1038>**说明：** 1039> 1040> 按组翻页时，数字导航点显示的子节点数量，不包括占位节点。 1041 1042**返回值：** 1043 1044| 类型 | 说明 | 1045| ----------------------------------- | ------------ | 1046| [DigitIndicator](#digitindicator10) | 数字指示器。 | 1047 1048### constructor 1049 1050constructor() 1051 1052DigitIndicator的构造函数。 1053 1054**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1055 1056**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1057 1058**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1059 1060## ArrowStyle<sup>10+</sup>对象说明 1061左右箭头属性。 1062 1063**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1064 1065**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1066 1067| 名称 | 类型 | 必填 | 说明 | 1068| ---------------- | ---------------------------------------- | ---- | ---------------------------------------- | 1069| showBackground | boolean | 否 | 设置箭头底板是否显示。<br/>默认值：false | 1070| isSidebarMiddle | boolean | 否 | 设置箭头显示位置。<br/>默认值：false <br/>默认显示在导航点指示器两侧。 | 1071| backgroundSize | [Length](ts-types.md#length) | 否 | 设置底板大小。<br/>在导航点两侧显示：<br/>默认值：24vp<br/>在组件两侧显示：<br/>默认值：32vp<br/>不支持设置百分比。 | 1072| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置底板颜色。<br/>在导航点两侧显示：<br/>默认值：'\#00000000'<br/>在组件两侧显示：<br/>默认值：'\#19182431' | 1073| arrowSize | [Length](ts-types.md#length) | 否 | 设置箭头大小。<br/>在导航点两侧显示时：<br/>默认值：18vp<br/>在组件两侧显示时：<br/>默认值：24vp<br/>**说明：**<br/>showBackground为true时，arrowSize为backgroundSize的3/4。<br/>不支持设置百分比。 | 1074| arrowColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置箭头颜色。<br/>默认值：'\#182431' | 1075 1076## SwiperAutoFill<sup>10+</sup> 1077 1078自适应属性。 1079 1080**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1081 1082**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1083 1084**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1085 1086| 名称 | 类型 | 必填 | 说明 | 1087| ------- | -------------------- | ------ | ------------------------------------ | 1088| minSize | [VP](ts-types.md#vp10) | 是 | 设置元素显示最小宽度。<br/>默认值：0 | 1089 1090## 事件 1091 1092除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 1093 1094### onChange 1095 1096onChange(event: (index: number) => void) 1097 1098当前显示的子组件索引变化时触发该事件，返回值为当前显示的子组件的索引值。 1099 1100Swiper组件结合LazyForEach使用时，不能在onChange事件里触发子页面UI的刷新。 1101 1102**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1103 1104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1105 1106**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1107 1108**参数：** 1109 1110| 参数名 | 类型 | 必填 | 说明 | 1111| ------ | ------ | ---- | -------------------- | 1112| index | number | 是 | 当前显示元素的索引。 | 1113 1114### onAnimationStart<sup>9+</sup> 1115 1116onAnimationStart(event: (index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => void) 1117 1118切换动画开始时触发该回调。参数为动画开始前的index值（不是最终结束动画的index值），多列Swiper时，index为最左侧组件的索引。 1119 1120**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1121 1122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1123 1124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1125 1126**参数：** 1127 1128| 参数名 | 类型 | 必填 | 说明 | 1129| ------------------------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1130| index | number | 是 | 当前显示元素的索引。 | 1131| targetIndex<sup>10+</sup> | number | 是 | 切换动画目标元素的索引。 | 1132| extraInfo<sup>10+</sup> | [SwiperAnimationEvent](#swiperanimationevent10对象说明) | 是 | 动画相关信息，包括主轴方向上当前显示元素和目标元素相对Swiper起始位置的位移，以及离手速度。 | 1133 1134>**说明：** 1135> 1136>- 当翻页动画时长为0时，只有以下场景会触发该回调：滑动翻页、自动轮播、调用SwiperController.showNext()和SwiperController.showPrevious()接口以及手指点击导航点翻页。 1137 1138### onAnimationEnd<sup>9+</sup> 1139 1140onAnimationEnd(event: (index: number, extraInfo: SwiperAnimationEvent) => void) 1141 1142当Swiper切换动效结束时触发，包括动画过程中手势中断，通过SwiperController调用finishAnimation。参数为动画结束后的index值，多列Swiper时，index为最左侧组件的索引。 1143 1144当Swiper切换动效结束时触发，包括动画过程中手势中断，通过SwiperController调用finishAnimation。 1145 1146**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1147 1148**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1149 1150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1151 1152**参数：** 1153 1154| 参数名 | 类型 | 必填 | 说明 | 1155| ----------------------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1156| index | number | 是 | 当前显示元素的索引。 | 1157| extraInfo<sup>10+</sup> | [SwiperAnimationEvent](#swiperanimationevent10对象说明) | 是 | 动画相关信息，只返回主轴方向上当前显示元素相对于Swiper起始位置的位移。 | 1158 1159>**说明：** 1160> 1161>- 当翻页动画时长为0时，只有以下场景会触发该回调：滑动翻页、自动轮播、调用SwiperController.showNext()和SwiperController.showPrevious()接口以及手指点击导航点翻页。 1162 1163### onGestureSwipe<sup>10+</sup> 1164 1165onGestureSwipe(event: (index: number, extraInfo: SwiperAnimationEvent) => void) 1166 1167在页面跟手滑动过程中，逐帧触发该回调。多列Swiper时，index为最左侧组件的索引。 1168 1169**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1170 1171**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1172 1173**参数：** 1174 1175| 参数名 | 类型 | 必填 | 说明 | 1176| --------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1177| index | number | 是 | 当前显示元素的索引。 | 1178| extraInfo | [SwiperAnimationEvent](#swiperanimationevent10对象说明) | 是 | 动画相关信息，只返回主轴方向上当前显示元素相对于Swiper起始位置的位移。 | 1179 1180### customContentTransition<sup>12+</sup> 1181 1182customContentTransition(transition: SwiperContentAnimatedTransition) 1183 1184自定义Swiper页面切换动画。在页面跟手滑动和离手后执行切换动画的过程中，会对视窗内所有页面逐帧触发回调，开发者可以在回调中设置透明度、缩放比例、位移等属性来自定义切换动画。 1185 1186使用说明： 1187 11881、循环场景下，设置prevMargin和nextMargin属性，使得Swiper前后端显示同一页面时，该接口不生效。<br>2、在页面跟手滑动和离手后执行切换动画的过程中，会对视窗内所有页面逐帧触发[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)回调。例如，当视窗内有下标为0、1的两个页面时，会每帧触发两次index值分别为0和1的回调。<br>3、设置displayCount属性的swipeByGroup参数为true时，若同组中至少有一个页面在视窗内时，则会对同组中所有页面触发回调，若同组所有页面均不在视窗内时，则会一起下渲染树。<br>4、在页面跟手滑动和离手后执行切换动画的过程中，默认动画（页面滑动）依然会发生，若希望页面不滑动，可以设置主轴方向上负的位移（translate属性）来抵消页面滑动。例如：当displayCount属性值为2，视窗内有下标为0、1的两个页面时，页面水平滑动过程中，可以逐帧设置第0页的translate属性在x轴上的值为-position * mainAxisLength来抵消第0页的位移，设置第1页的translate属性在x轴上的值为-(position - 1) * mainAxisLength来抵消第1页的位移。 1189 1190**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1191 1192**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1193 1194**参数：** 1195 1196| 参数名 | 类型 | 必填 | 说明 | 1197| ------ | ---- | ---- | ---- | 1198| transition | [SwiperContentAnimatedTransition](#swipercontentanimatedtransition12) | 是 | Swiper自定义切换动画相关信息。 | 1199 1200### onContentDidScroll<sup>12+</sup> 1201 1202onContentDidScroll(handler: ContentDidScrollCallback) 1203 1204监听Swiper页面滑动事件。 1205 1206使用说明： 1207 12081、循环场景下，设置prevMargin和nextMargin属性，使得Swiper前后端显示同一页面时，该接口不生效。<br>2、在页面滑动过程中，会对视窗内所有页面逐帧触发[ContentDidScrollCallback](#contentdidscrollcallback12)回调。例如，当视窗内有下标为0、1的两个页面时，会每帧触发两次index值分别为0和1的回调。<br>3、设置displayCount属性的swipeByGroup参数为true时，若同组中至少有一个页面在视窗内时，则会对同组中所有页面触发回调。 1209 1210**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1211 1212**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1213 1214**参数：** 1215 1216| 参数名 | 类型 | 必填 | 说明 | 1217| ------ | ---- | ---- | ---- | 1218| handler | [ContentDidScrollCallback](#contentdidscrollcallback12) | 是 | Swiper滑动时触发的回调。 | 1219 1220## SwiperAnimationEvent<sup>10+</sup>对象说明 1221 1222Swiper组件动画相关信息集合。 1223 1224**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1225 1226**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1227 1228| 名称 | 类型 | 只读 | 可选 | 说明 | 1229| ------------- | ----------- | ---- | ---- |------------------------------- | 1230| currentOffset | number | 否 | 否 | Swiper当前显示元素在主轴方向上，相对于Swiper起始位置的位移。单位VP，默认值为0。| 1231| targetOffset | number | 否 | 否 | Swiper动画目标元素在主轴方向上，相对于Swiper起始位置的位移。单位VP，默认值为0。| 1232| velocity | number | 否 | 否 | Swiper离手动画开始时的离手速度。单位VP/S，默认值为0。| 1233 1234## SwiperContentAnimatedTransition<sup>12+</sup> 1235 1236Swiper自定义切换动画相关信息。 1237 1238**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1239 1240**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1241 1242| 名称 | 类型 | 必填 | 说明 | 1243| ------ | ---- | ---- | ---- | 1244| timeout | number | 否 | Swiper自定义切换动画超时时间。从页面执行默认动画（页面滑动）至移出视窗外的第一帧开始计时，如果到达该时间后，开发者仍未调用[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)的finishTransition接口通知Swiper组件此页面的自定义动画已结束，那么组件就会认为此页面的自定义动画已结束，立即将该页面节点下渲染树。单位ms，默认值为0。 | 1245| transition | Callback<[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)> | 是 | 自定义切换动画具体内容。 | 1246 1247## SwiperContentTransitionProxy<sup>12+</sup> 1248 1249Swiper自定义切换动画执行过程中，返回给开发者的proxy对象。开发者可通过该对象获取自定义动画视窗内的页面信息，同时，也可以通过调用该对象的finishTransition接口通知Swiper组件页面自定义动画已结束。 1250 1251**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1252 1253**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1254 1255### 属性 1256 1257| 名称 | 类型 | 只读 | 可选 | 说明 | 1258| ---- | ---- | --- | ---- | --- | 1259| selectedIndex | number | 否 | 否 | 当前选中页面的索引。 | 1260| index | number | 否 | 否 | 视窗内页面的索引。 | 1261| position | number | 否 | 否 | index页面相对于Swiper主轴起始位置（selectedIndex对应页面的起始位置）的移动比例。 | 1262| mainAxisLength | number | 否 | 否 | index对应页面在主轴方向上的长度。 | 1263 1264>**说明：** 1265> 1266>- 例如，当前选中的子组件的索引为0，从第0页切换到第1页的动画过程中，每帧都会对视窗内所有页面触发回调，当视窗内有第0页和第1页两页时，每帧会触发两次回调。其中，第一次回调的selectedIndex为0、index为0、position为当前帧第0页相对于动画开始前第0页的移动比例，mainAxisLength为主轴方向上第0页的长度。第二次回调的selectedIndex仍为0、index为1、position为当前帧第1页相对于动画开始前第0页的移动比例，mainAxisLength为主轴方向上第1页的长度。 1267> 1268>- 若动画曲线为弹簧插值曲线，从第0页切换到第1页的动画过程中，可能会因为离手时的位置和速度，先过滑到第2页，再回弹到第1页，该过程中每帧会对视窗内第1页和第2页触发回调。 1269 1270 1271### finishTransition<sup>12+</sup> 1272 1273finishTransition(): void 1274 1275通知Swiper组件，此页面的自定义动画已结束。 1276 1277**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1278 1279**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1280 1281## ContentDidScrollCallback<sup>12+</sup> 1282 1283type ContentDidScrollCallback = (selectedIndex: number, index: number, position: number, mainAxisLength: number) => void 1284 1285Swiper滑动时触发的回调，参数可参考[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)中的说明。 1286 1287**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1288 1289**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1290 1291| 参数名 | 类型 | 必填 | 说明 | 1292| ------ | ---- | ---- | ---- | 1293| selectedIndex | number | 是 | 当前选中页面的索引。 | 1294| index | number | 是 | 视窗内页面的索引。 | 1295| position | number | 是 | index页面相对于Swiper主轴起始位置（selectedIndex对应页面的起始位置）的移动比例。 | 1296| mainAxisLength | number | 是 | index对应页面在主轴方向上的长度。 | 1297 1298## 示例 1299 1300### 示例1（设置导航点交互） 1301 1302该示例通过indicatorInteractive接口，实现了控制导航点交互的功能。 1303 1304```ts 1305// xxx.ets 1306class MyDataSource implements IDataSource { 1307 private list: number[] = [] 1308 1309 constructor(list: number[]) { 1310 this.list = list 1311 } 1312 1313 totalCount(): number { 1314 return this.list.length 1315 } 1316 1317 getData(index: number): number { 1318 return this.list[index] 1319 } 1320 1321 registerDataChangeListener(listener: DataChangeListener): void { 1322 } 1323 1324 unregisterDataChangeListener() { 1325 } 1326} 1327 1328@Entry 1329@Component 1330struct SwiperExample { 1331 private swiperController: SwiperController = new SwiperController() 1332 private data: MyDataSource = new MyDataSource([]) 1333 1334 aboutToAppear(): void { 1335 let list: number[] = [] 1336 for (let i = 1; i <= 10; i++) { 1337 list.push(i); 1338 } 1339 this.data = new MyDataSource(list) 1340 } 1341 1342 build() { 1343 Column({ space: 5 }) { 1344 Swiper(this.swiperController) { 1345 LazyForEach(this.data, (item: string) => { 1346 Text(item.toString()) 1347 .width('90%') 1348 .height(160) 1349 .backgroundColor(0xAFEEEE) 1350 .textAlign(TextAlign.Center) 1351 .fontSize(30) 1352 }, (item: string) => item) 1353 } 1354 .cachedCount(2) 1355 .index(1) 1356 .autoPlay(true) 1357 .interval(4000) 1358 .loop(true) 1359 .indicatorInteractive(true) 1360 .duration(1000) 1361 .itemSpace(0) 1362 .indicator( // 设置圆点导航点样式 1363 new DotIndicator() 1364 .itemWidth(15) 1365 .itemHeight(15) 1366 .selectedItemWidth(15) 1367 .selectedItemHeight(15) 1368 .color(Color.Gray) 1369 .selectedColor(Color.Blue)) 1370 .displayArrow({ // 设置导航点箭头样式 1371 showBackground: true, 1372 isSidebarMiddle: true, 1373 backgroundSize: 24, 1374 backgroundColor: Color.White, 1375 arrowSize: 18, 1376 arrowColor: Color.Blue 1377 }, false) 1378 .curve(Curve.Linear) 1379 .onChange((index: number) => { 1380 console.info(index.toString()) 1381 }) 1382 .onGestureSwipe((index: number, extraInfo: SwiperAnimationEvent) => { 1383 console.info("index: " + index) 1384 console.info("current offset: " + extraInfo.currentOffset) 1385 }) 1386 .onAnimationStart((index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => { 1387 console.info("index: " + index) 1388 console.info("targetIndex: " + targetIndex) 1389 console.info("current offset: " + extraInfo.currentOffset) 1390 console.info("target offset: " + extraInfo.targetOffset) 1391 console.info("velocity: " + extraInfo.velocity) 1392 }) 1393 .onAnimationEnd((index: number, extraInfo: SwiperAnimationEvent) => { 1394 console.info("index: " + index) 1395 console.info("current offset: " + extraInfo.currentOffset) 1396 }) 1397 1398 Row({ space: 12 }) { 1399 Button('showNext') 1400 .onClick(() => { 1401 this.swiperController.showNext() 1402 }) 1403 Button('showPrevious') 1404 .onClick(() => { 1405 this.swiperController.showPrevious() 1406 }) 1407 }.margin(5) 1408 }.width('100%') 1409 .margin({ top: 5 }) 1410 } 1411} 1412``` 1413 1414 1415 1416### 示例2（设置数字指示器） 1417 1418该示例通过DigitIndicator接口，实现了数字指示器的效果和功能。 1419 1420```ts 1421// xxx.ets 1422class MyDataSource implements IDataSource { 1423 private list: number[] = [] 1424 1425 constructor(list: number[]) { 1426 this.list = list 1427 } 1428 1429 totalCount(): number { 1430 return this.list.length 1431 } 1432 1433 getData(index: number): number { 1434 return this.list[index] 1435 } 1436 1437 registerDataChangeListener(listener: DataChangeListener): void { 1438 } 1439 1440 unregisterDataChangeListener() { 1441 } 1442} 1443 1444@Entry 1445@Component 1446struct SwiperExample { 1447 private swiperController: SwiperController = new SwiperController() 1448 private data: MyDataSource = new MyDataSource([]) 1449 1450 aboutToAppear(): void { 1451 let list: number[] = [] 1452 for (let i = 1; i <= 10; i++) { 1453 list.push(i); 1454 } 1455 this.data = new MyDataSource(list) 1456 } 1457 1458 build() { 1459 Column({ space: 5 }) { 1460 Swiper(this.swiperController) { 1461 LazyForEach(this.data, (item: string) => { 1462 Text(item.toString()) 1463 .width('90%') 1464 .height(160) 1465 .backgroundColor(0xAFEEEE) 1466 .textAlign(TextAlign.Center) 1467 .fontSize(30) 1468 }, (item: string) => item) 1469 } 1470 .cachedCount(2) 1471 .index(1) 1472 .autoPlay(true) 1473 .interval(4000) 1474 .indicator(Indicator.digit() // 设置数字导航点样式 1475 .top(200) 1476 .fontColor(Color.Gray) 1477 .selectedFontColor(Color.Gray) 1478 .digitFont({ size: 20, weight: FontWeight.Bold }) 1479 .selectedDigitFont({ size: 20, weight: FontWeight.Normal })) 1480 .loop(true) 1481 .duration(1000) 1482 .itemSpace(0) 1483 .displayArrow(true, false) 1484 1485 Row({ space: 12 }) { 1486 Button('showNext') 1487 .onClick(() => { 1488 this.swiperController.showNext() 1489 }) 1490 Button('showPrevious') 1491 .onClick(() => { 1492 this.swiperController.showPrevious() 1493 }) 1494 }.margin(5) 1495 }.width('100%') 1496 .margin({ top: 5 }) 1497 } 1498} 1499``` 1500 1501 1502### 示例3（设置按组翻页） 1503 1504该示例通过displayCount属性实现了按组翻页效果。 1505 1506```ts 1507// xxx.ets 1508class MyDataSource implements IDataSource { 1509 private list: number[] = [] 1510 1511 constructor(list: number[]) { 1512 this.list = list 1513 } 1514 1515 totalCount(): number { 1516 return this.list.length 1517 } 1518 1519 getData(index: number): number { 1520 return this.list[index] 1521 } 1522 1523 registerDataChangeListener(listener: DataChangeListener): void { 1524 } 1525 1526 unregisterDataChangeListener() { 1527 } 1528} 1529 1530@Entry 1531@Component 1532struct SwiperExample { 1533 private swiperController: SwiperController = new SwiperController() 1534 private data: MyDataSource = new MyDataSource([]) 1535 1536 aboutToAppear(): void { 1537 let list: number[] = [] 1538 for (let i = 1; i <= 10; i++) { 1539 list.push(i); 1540 } 1541 this.data = new MyDataSource(list) 1542 } 1543 1544 build() { 1545 Column({ space: 5 }) { 1546 Swiper(this.swiperController) { 1547 LazyForEach(this.data, (item: string) => { 1548 Text(item.toString()) 1549 .width('90%') 1550 .height(160) 1551 .backgroundColor(0xAFEEEE) 1552 .textAlign(TextAlign.Center) 1553 .fontSize(30) 1554 }, (item: string) => item) 1555 } 1556 .displayCount(3, true) 1557 .autoPlay(true) 1558 .interval(4000) 1559 .loop(true) 1560 .duration(1000) 1561 .itemSpace(10) 1562 .indicator( // 设置圆点导航点样式 1563 new DotIndicator() 1564 .itemWidth(15) 1565 .itemHeight(15) 1566 .selectedItemWidth(15) 1567 .selectedItemHeight(15) 1568 .color(Color.Gray) 1569 .selectedColor(Color.Blue)) 1570 1571 Row({ space: 12 }) { 1572 Button('showNext') 1573 .onClick(() => { 1574 this.swiperController.showNext() 1575 }) 1576 Button('showPrevious') 1577 .onClick(() => { 1578 this.swiperController.showPrevious() 1579 }) 1580 }.margin(5) 1581 }.width('100%') 1582 .margin({ top: 5 }) 1583 } 1584} 1585``` 1586 1587 1588### 示例4（设置自定义页面切换动画） 1589 1590该示例通过customContentTransition接口，实现了自定义Swiper页面切换动画效果。 1591 1592```ts 1593// xxx.ets 1594@Entry 1595@Component 1596struct SwiperCustomAnimationExample { 1597 private DISPLAY_COUNT: number = 2 1598 private MIN_SCALE: number = 0.75 1599 1600 @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange] 1601 @State opacityList: number[] = [] 1602 @State scaleList: number[] = [] 1603 @State translateList: number[] = [] 1604 @State zIndexList: number[] = [] 1605 1606 aboutToAppear(): void { 1607 for (let i = 0; i < this.backgroundColors.length; i++) { 1608 this.opacityList.push(1.0) 1609 this.scaleList.push(1.0) 1610 this.translateList.push(0.0) 1611 this.zIndexList.push(0) 1612 } 1613 } 1614 1615 build() { 1616 Column() { 1617 Swiper() { 1618 ForEach(this.backgroundColors, (backgroundColor: Color, index: number) => { 1619 Text(index.toString()).width('100%').height('100%').fontSize(50).textAlign(TextAlign.Center) 1620 .backgroundColor(backgroundColor) 1621 // 自定义动画变化透明度、缩放页面、抵消系统默认位移、渲染层级等 1622 .opacity(this.opacityList[index]) 1623 .scale({ x: this.scaleList[index], y: this.scaleList[index] }) 1624 .translate({ x: this.translateList[index] }) 1625 .zIndex(this.zIndexList[index]) 1626 }) 1627 } 1628 .height(300) 1629 .indicator(false) 1630 .displayCount(this.DISPLAY_COUNT, true) 1631 .customContentTransition({ 1632 // 页面移除视窗时超时1000ms下渲染树 1633 timeout: 1000, 1634 // 对视窗内所有页面逐帧回调transition，在回调中修改opacity、scale、translate、zIndex等属性值，实现自定义动画 1635 transition: (proxy: SwiperContentTransitionProxy) => { 1636 if (proxy.position <= proxy.index % this.DISPLAY_COUNT || proxy.position >= this.DISPLAY_COUNT + proxy.index % this.DISPLAY_COUNT) { 1637 // 同组页面往左滑或往右完全滑出视窗外时，重置属性值 1638 this.opacityList[proxy.index] = 1.0 1639 this.scaleList[proxy.index] = 1.0 1640 this.translateList[proxy.index] = 0.0 1641 this.zIndexList[proxy.index] = 0 1642 } else { 1643 // 同组页面往右滑且未滑出视窗外时，对同组中左右两个页面，逐帧根据position修改属性值，实现两个页面往Swiper中间靠拢并透明缩放的自定义切换动画 1644 if (proxy.index % this.DISPLAY_COUNT === 0) { 1645 this.opacityList[proxy.index] = 1 - proxy.position / this.DISPLAY_COUNT 1646 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - proxy.position / this.DISPLAY_COUNT) 1647 this.translateList[proxy.index] = - proxy.position * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 1648 } else { 1649 this.opacityList[proxy.index] = 1 - (proxy.position - 1) / this.DISPLAY_COUNT 1650 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - (proxy.position - 1) / this.DISPLAY_COUNT) 1651 this.translateList[proxy.index] = - (proxy.position - 1) * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 1652 } 1653 this.zIndexList[proxy.index] = -1 1654 } 1655 } 1656 }) 1657 .onContentDidScroll((selectedIndex: number, index: number, position: number, mainAxisLength: number) => { 1658 // 监听Swiper页面滑动事件，在该回调中可以实现自定义导航点切换动画等 1659 console.info("onContentDidScroll selectedIndex: " + selectedIndex + ", index: " + index + ", position: " + position + ", mainAxisLength: " + mainAxisLength) 1660 }) 1661 }.width('100%') 1662 } 1663} 1664``` 1665 1666 1667### 示例5（设置圆点导航点超长显示） 1668 1669该示例通过DotIndicator接口的maxDisplayCount属性，实现了圆点导航点超长显示动画效果。 1670 1671```ts 1672class MyDataSource implements IDataSource { 1673 private list: number[] = [] 1674 1675 constructor(list: number[]) { 1676 this.list = list 1677 } 1678 1679 totalCount(): number { 1680 return this.list.length 1681 } 1682 1683 getData(index: number): number { 1684 return this.list[index] 1685 } 1686 1687 registerDataChangeListener(listener: DataChangeListener): void { 1688 } 1689 1690 unregisterDataChangeListener() { 1691 } 1692} 1693 1694@Entry 1695@Component 1696struct Index { 1697 private swiperController: SwiperController = new SwiperController() 1698 private data: MyDataSource = new MyDataSource([]) 1699 1700 aboutToAppear(): void { 1701 let list: number[] = [] 1702 for (let i = 1; i <= 15; i++) { 1703 list.push(i); 1704 } 1705 this.data = new MyDataSource(list) 1706 } 1707 1708 build() { 1709 Column({ space: 5 }) { 1710 Swiper(this.swiperController) { 1711 LazyForEach(this.data, (item: string) => { 1712 Text(item.toString()) 1713 .width('90%') 1714 .height(160) 1715 .backgroundColor(0xAFEEEE) 1716 .textAlign(TextAlign.Center) 1717 .fontSize(30) 1718 }, (item: string) => item) 1719 } 1720 .cachedCount(2) 1721 .index(5) 1722 .autoPlay(true) 1723 .interval(4000) 1724 .loop(true) 1725 .duration(1000) 1726 .itemSpace(0) 1727 .indicator( // 设置圆点导航点样式 1728 new DotIndicator() 1729 .itemWidth(8) 1730 .itemHeight(8) 1731 .selectedItemWidth(16) 1732 .selectedItemHeight(8) 1733 .color(Color.Gray) 1734 .selectedColor(Color.Blue) 1735 .maxDisplayCount(9)) 1736 .displayArrow({ // 设置导航点箭头样式 1737 showBackground: true, 1738 isSidebarMiddle: true, 1739 backgroundSize: 24, 1740 backgroundColor: Color.White, 1741 arrowSize: 18, 1742 arrowColor: Color.Blue 1743 }, false) 1744 .curve(Curve.Linear) 1745 Row({ space: 12 }) { 1746 Button('showNext') 1747 .onClick(() => { 1748 this.swiperController.showNext() 1749 }) 1750 Button('showPrevious') 1751 .onClick(() => { 1752 this.swiperController.showPrevious() 1753 }) 1754 }.margin(5) 1755 }.width('100%') 1756 .margin({ top: 5 }) 1757 } 1758} 1759``` 1760 1761 1762
