1# Swiper 2 3 滑块视图容器，提供子组件滑动轮播显示的能力。 4 5> **说明：** 6> 7> - 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> - Swiper组件内包含了[PanGesture](ts-basic-gestures-pangesture.md)拖动手势事件，用于滑动轮播子组件。[disableSwipe](#disableswipe8)属性设为true会取消内部的PanGesture事件监听。 10 11## 子组件 12 13可以包含子组件。 14 15> **说明：** 16> 17> - 子组件类型：系统组件和自定义组件，支持渲染控制类型（[if/else](../../../ui/state-management/arkts-rendering-control-ifelse.md)、[ForEach](../../../ui/state-management/arkts-rendering-control-foreach.md)、[LazyForEach](../../../ui/state-management/arkts-rendering-control-lazyforeach.md)和[Repeat](../../../ui/state-management/arkts-new-rendering-control-repeat.md)）。不建议子组件中混用懒加载组件（包括LazyForEach、Repeat）和非懒加载组件，或者子组件中使用多个懒加载组件，否则可能导致懒加载组件预加载能力失效等问题。不建议在组件动画过程中对数据源进行操作，否则会导致布局出现异常。 18> 19> - Swiper子组件的[visibility](ts-universal-attributes-visibility.md#visibility)属性设置为Visibility.None，且Swiper的displayCount属性设置为'auto'时，对应子组件在视窗内不占位，但不影响导航点个数；visibility属性设置为Visibility.None或者Visibility.Hidden时，对应子组件不显示，但依然会在视窗内占位。 20> 21> - 当Swiper子组件设置了[offset](ts-universal-attributes-location.md#offset)属性时，会按照子组件的层级进行绘制，层级高的子组件会覆盖层级低的子组件。例如，Swiper包含3个子组件，其中第3个子组件设置了offset({ x : 100 })，那么在横向循环滑动中，第3个子组件会覆盖第1个子组件，此时可设置第1个子组件的[zIndex](ts-universal-attributes-z-order.md)属性值大于第3个子组件，使第1个子组件层级高于第3个子组件。 22> 23> - 在走焦到用户定义的子节点时，导航点、箭头会由于[焦点样式](../../../ui/arkts-common-events-focus-event.md#焦点样式)修改zindex的行为被遮挡。 24 25## 接口 26 27Swiper(controller?: SwiperController) 28 29创建滑块视图容器。 30 31**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 32 33**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 34 35**系统能力：** SystemCapability.ArkUI.ArkUI.Full 36 37**参数：** 38 39| 参数名 | 类型 | 必填 | 说明 | 40| ---------- | ------------------------------------- | ---- | -------------------- | 41| controller | [SwiperController](#swipercontroller) | 否 | 给组件绑定一个控制器，用来控制组件翻页或者预加载指定子节点。 | 42 43 44## 属性 45 46除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 47 48> **说明：** 49> 50> Swiper组件[通用属性clip](ts-universal-attributes-sharp-clipping.md)的默认值为true。 51 52### index 53 54index(value: number) 55 56设置当前在容器中显示的子组件的索引值。设置小于0或大于等于子组件数量时，按照默认值0处理。 57 58从API version 10开始，该属性支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。 59 60**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 61 62**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 63 64**系统能力：** SystemCapability.ArkUI.ArkUI.Full 65 66**参数：** 67 68| 参数名 | 类型 | 必填 | 说明 | 69| ------ | ------ | ---- | ------------------------------------------------ | 70| value | number | 是 | 当前在容器中显示的子组件的索引值。<br/>默认值：0 <br/>**说明：** <br/>设置的值小于0或大于最大页面索引时，取0。| 71 72### autoPlay 73 74autoPlay(value: boolean) 75 76设置子组件是否自动播放。 77 78[loop](#loop)为false时，自动轮播到最后一页时停止轮播。手势切换后不是最后一页时继续播放。当Swiper不可见时会停止轮播。 79 80**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 81 82**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 83 84**系统能力：** SystemCapability.ArkUI.ArkUI.Full 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| ------ | ------- | ---- | -------------------------------------- | 90| value | boolean | 是 | 子组件是否自动播放。<br/>默认值：false，不自动轮播。 | 91 92### autoPlay<sup>18+</sup> 93 94autoPlay(autoPlay: boolean, options: AutoPlayOptions) 95 96设置子组件是否自动播放。options入参控制手指或者鼠标等按下屏幕时子组件是否停止自动播放。 97 98当[loop](#loop)设置为false时，自动轮播将在到达最后一页时停止。在通过手势切换且未处于最后一页的情况下，轮播将继续进行。Swiper在不可见时，轮播也将停止。 99 100**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 101 102**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 103 104**系统能力：** SystemCapability.ArkUI.ArkUI.Full 105 106**参数：** 107 108| 参数名 | 类型 | 必填 | 说明 | 109| ------ | ------- | ---- | -------------------------------------- | 110| autoPlay | boolean | 是 | 子组件是否自动播放。<br/>默认值：false，不自动轮播。 | 111| options | [AutoPlayOptions](#autoplayoptions18对象说明) | 是 | 配置手指或者鼠标等按下屏幕时子组件是否停止自动播放。当stopWhenTouched设置为true时，多指按下场景中任意一个手指抬起后，将自动继续播放。<br/>默认值：{ stopWhenTouched: true }，停止自动播放。 | 112 113### interval 114 115interval(value: number) 116 117设置使用自动播放时播放的时间间隔。 118 119**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 120 121**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 122 123**系统能力：** SystemCapability.ArkUI.ArkUI.Full 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| ------ | ------ | ---- | ---------------------------------------------------------- | 129| value | number | 是 | 自动播放时播放的时间间隔。当小于[duration](#duration)属性值时，翻页完成后会立即开始下一次轮播。<br/>默认值：3000<br/>单位：毫秒<br/>取值范围：[0, +∞)，设置小于0的值时，按照默认值处理。 | 130 131### indicator 132 133indicator(value: DotIndicator | DigitIndicator | boolean) 134 135设置可选导航点指示器样式。 136 137**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 138 139**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 140 141**系统能力：** SystemCapability.ArkUI.ArkUI.Full 142 143**参数：** 144 145| 参数名 | 类型 | 必填 | 说明 | 146| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 147| value | [DotIndicator](#dotindicator10)<sup>10+</sup> \| [DigitIndicator](#digitindicator10)<sup>10+</sup> \| boolean | 是 | 可选导航点指示器样式。<br/> \- DotIndicator：圆点指示器样式。<br/> \- DigitIndicator：数字指示器样式。<br/> \- boolean：是否启用导航点指示器。设置为true启用，false不启用。<br/> 默认值：true<br/> 默认类型：DotIndicator | 148 149### indicator<sup>15+</sup> 150 151indicator(indicator: IndicatorComponentController | DotIndicator | DigitIndicator | boolean) 152 153设置外部绑定的导航点组件控制器。 154 155**卡片能力：** 从API version 15开始，该接口支持在ArkTS卡片中使用。 156 157**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 158 159**系统能力：** SystemCapability.ArkUI.ArkUI.Full 160 161**参数：** 162 163| 参数名 | 类型 | 必填 | 说明 | 164| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 165| indicator | [IndicatorComponentController](ts-swiper-components-indicator.md#indicatorcomponentcontroller)<sup>15+</sup> \| [DotIndicator](#dotindicator10) \| [DigitIndicator](#digitindicator10) \| boolean| 是 | 可选导航点指示器样式。<br/>\- IndicatorComponentController：单独导航点指示器控制器。当使用单独导航点指示器控制器时，可以与外部单独导航点进行绑定，但是绑定的单独导航点和内置导航点不能同时存在。<br/> \- DotIndicator：圆点指示器样式。<br/> \- DigitIndicator：数字指示器样式。<br/> \- boolean：是否启用导航点指示器。设置为true启用，false不启用。<br/> 默认值：true<br/> 默认类型：DotIndicator。| 166 167 168### loop 169 170loop(value: boolean) 171 172设置是否开启循环。设置为true时表示开启循环，在LazyForEach懒循环加载模式下，加载的组件数量建议大于5个。 173 174**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 175 176**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 177 178**系统能力：** SystemCapability.ArkUI.ArkUI.Full 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| ------ | ------- | ---- | ------------------------------- | 184| value | boolean | 是 | 是否开启循环。true为开启循环，false为不开启循环。<br/>默认值：true | 185 186### duration 187 188duration(value: number) 189 190设置子组件切换的动画时长。 191 192duration需要和[curve](#curve8)一起使用。 193 194curve默认曲线为[interpolatingSpring](../js-apis-curve.md#curvesinterpolatingspring10)，此时动画时长只受曲线自身参数影响，不再受duration的控制。不受duration控制的曲线可以查阅[插值计算](../js-apis-curve.md)模块，比如，[springMotion](../js-apis-curve.md#curvesspringmotion9)、[responsiveSpringMotion](../js-apis-curve.md#curvesresponsivespringmotion9)和interpolatingSpring类型的曲线不受duration控制。如果希望动画时长受到duration控制，需要给curve设置其他曲线。 195 196**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 197 198**系统能力：** SystemCapability.ArkUI.ArkUI.Full 199 200**参数：** 201 202| 参数名 | 类型 | 必填 | 说明 | 203| ------ | ------ | ---- | ----------------------------------------------------- | 204| value | number | 是 | 子组件切换的动画时长。<br/>默认值：400<br/>单位：毫秒<br/>取值范围：[0, +∞)，设置小于0的值时，按照默认值处理。 | 205 206### vertical 207 208vertical(value: boolean) 209 210设置是否为纵向滑动。 211 212**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 213 214**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 215 216**系统能力：** SystemCapability.ArkUI.ArkUI.Full 217 218**参数：** 219 220| 参数名 | 类型 | 必填 | 说明 | 221| ------ | ------- | ---- | ---------------------------------- | 222| value | boolean | 是 | 是否为纵向滑动。true为纵向滑动，false为横向滑动。<br/>默认值：false | 223 224### itemSpace 225 226itemSpace(value: number | string) 227 228设置子组件与子组件之间间隙。不支持设置百分比。 229 230类型为number时，默认单位vp。类型为string时，需要显式指定像素单位，如'10px'；未指定像素单位时，如'10'，单位为vp。 231 232**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 233 234**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 235 236**系统能力：** SystemCapability.ArkUI.ArkUI.Full 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| ------ | -------------------------- | ---- | -------------------------------------- | 242| value | number \| string | 是 | 子组件与子组件之间间隙。<br/>默认值：0<br/>取值范围：[0, +∞)，当设置数值小于0或超出Swiper组件宽度范围时，按照默认值处理。 | 243 244### displayMode 245 246displayMode(value: SwiperDisplayMode) 247 248设置主轴方向上元素排列的模式，优先以displayCount设置的个数显示，displayCount未设置时本属性生效。 249 250**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 251 252**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 253 254**系统能力：** SystemCapability.ArkUI.ArkUI.Full 255 256**参数：** 257 258| 参数名 | 类型 | 必填 | 说明 | 259| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 260| value | [SwiperDisplayMode](#swiperdisplaymode枚举说明) | 是 | 主轴方向上元素排列的模式。<br/>默认值：SwiperDisplayMode.STRETCH | 261 262### cachedCount<sup>8+</sup> 263 264cachedCount(value: number) 265 266设置预加载子组件个数，以当前页面为基准，加载当前显示页面的前后个数。例如cachedCount=1时，会将当前显示的页面的前面一页和后面一页的子组件都预加载。如果设置为按组翻页，即displayCount的swipeByGroup参数设为true，预加载时会以组为基本单位。例如cachedCount=1，swipeByGroup=true时，会将当前组的前面一组和后面一组的子组件都预加载。 267 268**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 269 270**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 271 272**系统能力：** SystemCapability.ArkUI.ArkUI.Full 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| ------ | ------ | ---- | -------------------------------- | 278| value | number | 是 | 预加载子组件个数。<br/>默认值：1<br/>取值范围：[0, +∞)，设置小于0的值时，按照默认值处理。 | 279 280### cachedCount<sup>15+</sup> 281 282cachedCount(count: number, isShown: boolean) 283 284设置预加载子组件个数。 285 286**卡片能力：** 从API version 15开始，该接口支持在ArkTS卡片中使用。 287 288**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 289 290**系统能力：** SystemCapability.ArkUI.ArkUI.Full 291 292**参数：** 293 294| 参数名 | 类型 | 必填 | 说明 | 295| ------ | ------ | ---- | -------------------------------- | 296| count | number | 是 | 预加载子组件个数。<br/>默认值：1<br/>取值范围：[0, +∞)，设置小于0的值时，按照默认值处理。 | 297| isShown | boolean | 是 | 预加载范围内的节点是否进行绘制，不下渲染树。<br/>默认值：false，预加载范围内的节点不进行绘制。 | 298 299### disableSwipe<sup>8+</sup> 300 301disableSwipe(value: boolean) 302 303设置禁用组件滑动切换功能。 304 305**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 306 307**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 308 309**系统能力：** SystemCapability.ArkUI.ArkUI.Full 310 311**参数：** 312 313| 参数名 | 类型 | 必填 | 说明 | 314| ------ | ------- | ---- | ---------------------------------------- | 315| value | boolean | 是 | 禁用组件滑动切换功能。设置为true禁用，false不禁用。<br/>默认值：false | 316 317### curve<sup>8+</sup> 318 319curve(value: Curve | string | ICurve) 320 321设置Swiper的动画曲线，默认为弹簧插值曲线，常用曲线参考[Curve枚举说明](ts-appendix-enums.md#curve)，也可以通过[插值计算](../js-apis-curve.md)模块提供的接口创建自定义的插值曲线对象。 322 323**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 324 325**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 326 327**系统能力：** SystemCapability.ArkUI.ArkUI.Full 328 329**参数：** 330 331| 参数名 | 类型 | 必填 | 说明 | 332| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------- | 333| value | [Curve](ts-appendix-enums.md#curve) \| string \| [ICurve](../js-apis-curve.md#icurve9)<sup>10+</sup> | 是 | Swiper的动画曲线。<br/>string类型来源[curves.init](../js-apis-curve.md#curvesinitdeprecated)，[curves.steps](../js-apis-curve.md#curvesstepsdeprecated)，[curves.cubicBezier](../js-apis-curve.md#curvescubicbezierdeprecated)，[curves.spring](../js-apis-curve.md#curvesspringdeprecated)函数从API 9开始废弃，推荐使用Curve和ICurve类型。<br/>默认值：[interpolatingSpring](../js-apis-curve.md#curvesinterpolatingspring10)(-1, 1, 328, 34) | 334 335### indicatorStyle<sup>(deprecated)</sup> 336 337indicatorStyle(value?: IndicatorStyle) 338 339设置导航点样式。 340 341从API version 8开始支持，从API version 10开始不再维护，建议使用[indicator](#indicator10)代替。 342 343**系统能力：** SystemCapability.ArkUI.ArkUI.Full 344 345**参数：** 346 347| 参数名 | 类型 | 必填 | 说明 | 348| ------ | --------------------------------------------------- | ---- | ------------ | 349| value | [IndicatorStyle](#indicatorstyledeprecated对象说明) | 否 | 导航点样式。 | 350 351### displayCount<sup>8+</sup> 352 353displayCount(value: number | string | SwiperAutoFill, swipeByGroup?: boolean) 354 355设置Swiper视窗内元素显示个数。 356 357使用字符串类型时，仅支持设置为'auto'，此时，设置[customContentTransition](#customcontenttransition12)和[onContentDidScroll](#oncontentdidscroll12)事件不生效。使用number类型时，子组件按照主轴均分Swiper宽度（减去displayCount-1个itemSpace）的方式进行主轴拉伸（收缩）布局，设置为小于等于0的值时，按默认值1显示。使用SwiperAutoFill类型时，通过设置一个子组件最小宽度值minSize，会根据Swiper当前宽度和minSize值自动计算并更改一页内元素显示个数。当minSize为空或者小于等于0时，Swiper显示1列。 358 359当按组进行翻页时，判定翻页的拖拽距离阈值将调整为Swiper宽度的50%（若按子元素翻页，该阈值为子元素宽度的50%）。若最后一组的子元素数量少于displayCount，将利用占位子元素进行填充，占位子元素仅用于布局定位，不显示任何内容，其位置将直接显示Swiper的背景样式。 360 361**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 362 363**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 364 365**系统能力：** SystemCapability.ArkUI.ArkUI.Full 366 367**参数：** 368 369| 参数名 | 类型 | 必填 | 说明 | 370| -------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 371| value | number \| string \| [SwiperAutoFill](#swiperautofill10)<sup>10+</sup> | 是 | 视窗内显示的子元素个数。<br/> 默认值：1<br/>取值范围：(0, +∞)，设置小于等于0的值时，按照默认值处理。| 372| swipeByGroup<sup>11+</sup> | boolean | 否 | 是否按组进行翻页。如果设为true，在翻页时会按组进行翻页，每组内子元素的数量为displayCount value的值；如果为false，则为默认翻页行为，即按照子元素进行翻页。<br/> 默认值：false | 373 374> **说明：** 375> 376> 当Swiper子组件个数小于等于Swiper组件内容区内显示的节点总个数(totalDisplayCount = DisplayCount + prevMargin? (1 : 0) + nextMargin? (1 : 0))时，一般按照非循环模式布局处理，此时，前后边距对应子组件不显示，但依然会在视窗内占位。Swiper组件按照totalDisplayCount个数判断测算规格。例外情况如下： 377> 378> - 当Swiper子组件个数等于Swiper组件内容区内显示的节点总个数且prevMargin和nextMargin都生效时，设置loop为true支持循环。 379> 380> - 当Swiper子组件个数等于Swiper组件DisplayCount数 + 1，且prevMargin和nextMargin至少一个生效时，设置loop为true会生成截图占位组件(如果使用图片异步加载等显示耗时较长的组件可能不能正确生成截图，不建议在该场景开启循环)，支持循环。 381> 382 383### effectMode<sup>8+</sup> 384 385effectMode(value: EdgeEffect) 386 387设置边缘滑动效果，[loop](#loop) = false时生效。调用SwiperController.changeIndex()、SwiperController.showNext()和SwiperController.showPrevious()接口跳转至首尾页时不生效回弹。 388 389**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 390 391**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 392 393**系统能力：** SystemCapability.ArkUI.ArkUI.Full 394 395**参数：** 396 397| 参数名 | 类型 | 必填 | 说明 | 398| ------ | --------------------------------------------- | ---- | -------------------------------------------- | 399| value | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 是 | 边缘滑动效果。<br/>默认值：EdgeEffect.Spring | 400 401### displayArrow<sup>10+</sup> 402 403displayArrow(value: ArrowStyle | boolean, isHoverShow?: boolean) 404 405设置导航点箭头样式。 406 407**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 408 409**系统能力：** SystemCapability.ArkUI.ArkUI.Full 410 411**参数：** 412 413| 参数名 | 类型 | 必填 | 说明 | 414| -------------------------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 415| value | [ArrowStyle](#arrowstyle10对象说明) \| boolean | 是 | 支持设置箭头和底板样式，异常场景使用ArrowStyle对象中的默认值。设置为false不显示箭头和底板，true显示默认的箭头和底板样式。<br/>默认值：false | 416| isHoverShow | boolean | 否 | 设置鼠标悬停时是否显示箭头。<br/>默认值：false<br/>**说明：**<br/>1、isHoverShow为false时，常驻显示箭头。<br/>2、isHoverShow为true时，有导航点时鼠标悬停在导航点和箭头范围内显示箭头，无导航点时鼠标悬停在Swiper显示范围内显示箭头。<br/>3、箭头显示时，支持点击翻页。 | 417 418> **说明：** 419> 420> Swiper视窗内显示所有子节点时，只显示一屏，无法翻页，左右翻页箭头均不显示。 421 422### nextMargin<sup>10+</sup> 423 424nextMargin(value: Length, ignoreBlank?:boolean) 425 426设置后边距，用于露出后一项的一小部分，使用效果可以参考[示例1设置导航点交互及翻页动效](#示例1设置导航点交互及翻页动效)。仅当Swiper子组件的布局方式为拉伸时生效，主要包括两种场景：1、displayMode属性设置为SwiperDisplayMode.STRETCH；2、displayCount属性设置为number类型。 427 428当主轴方向为横向布局时，nextMargin/prevMargin中任意一个大于子组件测算的宽度，nextMargin和prevMargin均不显示。 429 430当主轴方向为纵向布局时，nextMargin/prevMargin中任意一个大于子组件测算的高度，nextMargin和prevMargin均不显示。 431 432**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 433 434**系统能力：** SystemCapability.ArkUI.ArkUI.Full 435 436**参数：** 437 438| 参数名 | 类型 | 必填 | 说明 | 439| ------ | ---------------------------- | ---- | ---------------------- | 440| value | [Length](ts-types.md#length) | 是 | 后边距。不支持设置百分比。<br/>默认值：0 | 441| ignoreBlank<sup>12+</sup> | boolean | 否 | 非loop场景下尾页不显示nextMargin。在非loop场景下，设置为true时，尾页不显示空白的nextMargin，尾页的右边缘与Swiper视窗右边缘对齐；设置false时，尾页显示空白nextMargin，尾页的右边缘与Swiper视窗右边缘的距离为nextMargin。<br/>默认值：false <br/>**说明：**<br/>尾页场景下，prevMargin和nextMargin的值相加作为左边边距显示前一个页面。 | 442 443### prevMargin<sup>10+</sup> 444 445prevMargin(value: Length, ignoreBlank?:boolean) 446 447设置前边距，用于露出前一项的一小部分，使用效果可以参考[示例1设置导航点交互及翻页动效](#示例1设置导航点交互及翻页动效)。仅当Swiper子组件的布局方式为拉伸时生效，主要包括两种场景：1、displayMode属性设置为SwiperDisplayMode.STRETCH；2、displayCount属性设置为number类型。 448 449当主轴方向为横向布局时，nextMargin/prevMargin中任意一个大于子组件测算的宽度，nextMargin和prevMargin均不显示。 450 451当主轴方向为纵向布局时，nextMargin/prevMargin中任意一个大于子组件测算的高度，nextMargin和prevMargin均不显示。 452 453**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 454 455**系统能力：** SystemCapability.ArkUI.ArkUI.Full 456 457**参数：** 458 459| 参数名 | 类型 | 必填 | 说明 | 460| ------ | ---------------------------- | ---- | ---------------------- | 461| value | [Length](ts-types.md#length) | 是 | 前边距。不支持设置百分比。<br/>默认值：0 | 462| ignoreBlank<sup>12+</sup> | boolean | 否 | 非loop场景下首页不显示prevMargin。在非loop场景下，设置为true时，首页不显示空白的prevMargin，首页的左边缘与Swiper视窗左边缘对齐；设置false时，首页显示空白prevMargin，首页的左边缘与Swiper视窗左边缘的距离为prevMargin。<br/>默认值：false <br/>**说明：**<br/>首页场景下，prevMargin和nextMargin的值相加作为右边边距显示后一个页面。| 463 464### nestedScroll<sup>11+</sup> 465 466nestedScroll(value: SwiperNestedScrollMode) 467 468设置Swiper组件和父组件的嵌套滚动模式。loop为true时Swiper组件没有边缘，不会触发父组件嵌套滚动。 469 470**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 471 472**系统能力：** SystemCapability.ArkUI.ArkUI.Full 473 474**参数：** 475 476| 参数名 | 类型 | 必填 | 说明 | 477| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 478| value | [SwiperNestedScrollMode](#swipernestedscrollmode11枚举说明) | 是 | Swiper组件和父组件的嵌套滚动模式。<br/>默认值：SwiperNestedScrollMode.SELF_ONLY | 479 480> **说明：** 481> 482> 由于Swiper的抛滑动画逻辑和其它滚动类组件不同（Swiper一次只能滑动一页，抛滑时做翻页动画），当Swiper内嵌套其它滚动组件时，如果Swiper的翻页动画已经启动，将无法接受子节点上传的滚动偏移量。这时Swiper的翻页动画和子节点的边缘效果动画会同时执行。 483 484### indicatorInteractive<sup>12+</sup> 485 486indicatorInteractive(value: boolean) 487 488设置禁用组件导航点交互功能。设置为true时表示导航点可交互。 489 490**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 491 492**系统能力：** SystemCapability.ArkUI.ArkUI.Full 493 494**参数：** 495 496| 参数名 | 类型 | 必填 | 说明 | 497| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 498| value | boolean | 是 | 导航点是否可交互。true为导航点可交互，false为导航点不可交互。<br/>默认值：true | 499 500### pageFlipMode<sup>15+</sup> 501 502pageFlipMode(mode: Optional\<PageFlipMode>) 503 504设置鼠标滚轮翻页模式。 505 506**卡片能力：** 从API version 15开始，该接口支持在ArkTS卡片中使用。 507 508**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 509 510**系统能力：** SystemCapability.ArkUI.ArkUI.Full 511 512**参数：** 513 514| 参数名 | 类型 | 必填 | 说明 | 515| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 516| mode | Optional\<[PageFlipMode](ts-appendix-enums.md#pageflipmode15)> | 是 | 鼠标滚轮翻页模式。<br/>默认值：PageFlipMode.CONTINUOUS | 517 518## IndicatorStyle<sup>(deprecated)</sup>对象说明 519 520从API version 8开始支持，从API version 10开始不再维护，建议使用[indicator](#indicator10)代替。 521 522**系统能力：** SystemCapability.ArkUI.ArkUI.Full 523 524| 名称 | 类型 | 必填 | 说明 | 525| ------------- | ------------------------------------------ | ---- | ---------------------------------------------------- | 526| left | [Length](ts-types.md#length) | 否 | 设置导航点左侧相对于Swiper的位置。<br/>未设置left和right时，进行自适应大小布局，按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐<br/>设置为0时：按照0位置布局计算<br/>优先级：高于right属性<br/>取值范围：[0,Swiper宽度-导航点区域宽度]，超出该范围时，取最近的边界值。 | 527| top | [Length](ts-types.md#length) | 否 | 设置导航点顶部相对于Swiper的位置。<br/>未设置top和bottom时，进行自适应大小布局，按照指示器本身大小和Swiper的大小，在交叉轴方向上，位于底部，效果与设置bottom=0一致<br/>设置为0时：按照0位置布局计算<br/>优先级：高于bottom属性<br/>取值范围：[0,Swiper高度-导航点区域高度]，超出该范围时，取最近的边界值。 | 528| right | [Length](ts-types.md#length) | 否 | 设置导航点右侧相对于Swiper的位置。<br/>未设置left和right时，进行自适应大小布局，按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐<br/>设置为0时：按照0位置布局计算<br/>优先级：低于left属性<br/>取值范围：[0,Swiper宽度-导航点区域宽度]，超出该范围时，取最近的边界值。 | 529| bottom | [Length](ts-types.md#length) | 否 | 设置导航点底部相对于Swiper的位置。<br/>未设置top和bottom时，进行自适应大小布局，按照指示器本身大小和Swiper的大小，在交叉轴方向上，位于底部，效果与设置bottom=0一致<br/>设置为0时：按照0位置布局计算<br/>优先级：低于top属性<br/>取值范围：[0,Swiper高度-导航点区域高度]，超出该范围时，取最近的边界值。 | 530| size | [Length](ts-types.md#length) | 否 | 设置导航点的直径，不支持设置百分比。<br/>默认值：6vp | 531| mask | boolean | 否 | 设置是否显示导航点蒙层样式。<br/>设置为true时显示导航点蒙层样式，为false时不显示。 | 532| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置导航点的颜色。 | 533| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置选中的导航点的颜色。 | 534 535## SwiperDisplayMode枚举说明 536 537Swiper在主轴上的尺寸大小模式枚举。 538 539**系统能力：** SystemCapability.ArkUI.ArkUI.Full 540 541| 名称 | 说明 | 542| ---------------------------------- | ------------------------------------------------------------ | 543| Stretch<sup>(deprecated)</sup> | Swiper滑动一页的宽度为Swiper组件自身的宽度。<br>从API version 10开始不再维护，建议使用STRETCH代替。<br/>**卡片能力：** 从API version 7开始，该接口支持在ArkTS卡片中使用。 | 544| AutoLinear<sup>(deprecated)</sup> | Swiper滑动一页的宽度为子组件宽度中的最大值。<br>从API version 10开始不再维护，建议使用[Scroller.scrollTo](ts-container-scroll.md#scrollto)代替。<br/>**卡片能力：** 从API version 7开始，该接口支持在ArkTS卡片中使用。 | 545| STRETCH<sup>10+</sup> | Swiper滑动一页的宽度为Swiper组件自身的宽度。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 546| 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开始，该接口支持在原子化服务中使用。 | 547 548## SwiperNestedScrollMode<sup>11+</sup>枚举说明 549 550Swiper组件和父组件的嵌套滚动模式枚举。 551 552**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 553 554**系统能力：** SystemCapability.ArkUI.ArkUI.Full 555 556| 名称 | 值 | 说明 | 557| ------------ | -- | ---------------------------------------- | 558| SELF_ONLY | 0 | Swiper只自身滚动，不与父组件联动。 | 559| SELF_FIRST | 1 | Swiper自身先滚动，自身滚动到边缘以后父组件滚动。父组件滚动到边缘以后，如果父组件有边缘效果，则父组件触发边缘效果，否则Swiper触发边缘效果。 | 560 561## SwiperController 562 563Swiper容器组件的控制器，可以将此对象绑定至Swiper组件，实现控制Swiper翻页等功能。 564 565**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 566 567**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 568 569**系统能力：** SystemCapability.ArkUI.ArkUI.Full 570 571### constructor 572 573constructor() 574 575SwiperController的构造函数。 576 577**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 578 579**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 580 581**系统能力：** SystemCapability.ArkUI.ArkUI.Full 582 583### showNext 584 585showNext() 586 587翻至下一页。翻页带动效切换过程，时长通过Swiper的[duration](#duration)属性设置。 588 589**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 590 591**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 592 593**系统能力：** SystemCapability.ArkUI.ArkUI.Full 594 595### showPrevious 596 597showPrevious() 598 599翻至上一页。翻页带动效切换过程，时长通过Swiper的[duration](#duration)属性设置。 600 601**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 602 603**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 604 605**系统能力：** SystemCapability.ArkUI.ArkUI.Full 606 607### changeIndex<sup>12+</sup> 608 609changeIndex(index: number, useAnimation?: boolean) 610 611翻至指定页面。 612 613**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 614 615**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 616 617**系统能力：** SystemCapability.ArkUI.ArkUI.Full 618 619**参数：** 620 621| 参数名 | 类型 | 必填 | 说明 | 622| -------- | ---------- | ---- | -------- | 623| index| number | 是 | 指定页面在Swiper中的索引值。<br/>**说明：** <br/>设置的值小于0或大于最大页面索引时，取0。 | 624| useAnimation| boolean | 否 | 设置翻至指定页面时是否有动效，true表示有动效，false表示没有动效。<br/>默认值：false。 | 625 626### changeIndex<sup>15+</sup> 627 628changeIndex(index: number, animationMode?: SwiperAnimationMode | boolean) 629 630翻页至指定页面。 631 632**卡片能力：** 从API version 15开始，该接口支持在ArkTS卡片中使用。 633 634**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 635 636**系统能力：** SystemCapability.ArkUI.ArkUI.Full 637 638**参数：** 639 640| 参数名 | 类型 | 必填 | 说明 | 641| -------- | ---------- | ---- | -------- | 642| index| number | 是 | 指定页面在Swiper中的索引值。<br/>**说明：** <br/>设置的值小于0或大于最大页面索引时，取0。 | 643| animationMode| [SwiperAnimationMode](#swiperanimationmode15枚举说明) \| boolean | 否 | 设置翻页至指定页面时的动效模式。<br/>默认值：SwiperAnimationMode.NO_ANIMATION<br/> **说明：** <br/>当传入true时有动效，等同于SwiperAnimationMode.DEFAULT_ANIMATION；当传入false时无动效，等同于SwiperAnimationMode.NO_ANIMATION。 | 644 645### finishAnimation 646 647finishAnimation(callback?: VoidCallback) 648 649停止播放动画。 650 651**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 652 653**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 654 655**系统能力：** SystemCapability.ArkUI.ArkUI.Full 656 657**参数：** 658 659| 参数名 | 类型 | 必填 | 说明 | 660| -------- | ---------- | ---- | -------- | 661| callback | [VoidCallback](./ts-types.md#voidcallback12) | 否 | 动画结束的回调。 | 662 663### preloadItems<sup>18+</sup> 664 665preloadItems(indices: Optional\<Array\<number>>): Promise\<void> 666 667控制Swiper预加载指定子节点。调用该接口后会一次性加载所有指定的子节点，因此为了性能考虑，建议分批加载子节点。 668 669如果SwiperController对象未绑定任何Swiper组件，直接调用该接口，会抛出JS异常，并返回错误码100004。因此使用该接口时，建议通过try-catch捕获异常。 670 671与[LazyForEach](../../../ui/state-management/arkts-rendering-control-lazyforeach.md)和自定义组件结合使用时，由于[LazyForEach](../../../ui/state-management/arkts-rendering-control-lazyforeach.md)只会保留缓存范围内的自定义组件，在缓存范围外的会被删除，因此需要开发者保证通过该接口预加载的节点index在缓存范围内。 672 673**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 674 675**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 676 677**系统能力：** SystemCapability.ArkUI.ArkUI.Full 678 679**参数：** 680 681| 参数名 | 类型 | 必填 | 说明 | 682| ----- | ------ | ---- | ---------------------------------------- | 683| indices | Optional\<Array\<number>> | 是 | 需预加载的子节点的下标数组。<br/>默认值：空数组。 | 684 685**返回值：** 686 687| 类型 | 说明 | 688| ------------------------------------------------------------ | ------------------------ | 689| Promise\<void> | 预加载完成后触发的回调。 | 690 691**错误码：** 692 693以下错误码的详细介绍请参见[通用错误码](../../errorcode-universal.md)和[滚动类组件错误码](../../apis-arkui/errorcode-scroll.md)错误码。 694 695| 错误码ID | 错误信息 | 696| -------- | -------------------------------------------- | 697| 401 | Parameter invalid. Possible causes: 1. The parameter type is not Array\<number>; 2. The parameter is an empty array; 3. The parameter contains an invalid index. | 698| 100004 | Controller not bound to component. | 699 700## SwiperAnimationMode<sup>15+</sup>枚举说明 701 702Swiper组件翻页至指定页面的动效模式。 703 704**卡片能力：** 从API version 15开始，该接口支持在ArkTS卡片中使用。 705 706**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 707 708**系统能力：** SystemCapability.ArkUI.ArkUI.Full 709 710| 名称 | 值 | 说明 | 711| ------------- | ---- | ------------------------------------------------------------ | 712| NO_ANIMATION | 0 | 无动效翻页至指定页面。 | 713| DEFAULT_ANIMATION | 1 | 有动效翻页至指定页面。 | 714| FAST_ANIMATION | 2 | 先无动效翻页至指定页面附近，再有动效翻页至指定页面。 | 715 716## Indicator<sup>10+</sup> 717 718设置导航点距离Swiper组件距离。由于导航点有默认交互区域，交互区域高度为32vp，所以无法让显示部分完全贴底。 719 720**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 721 722**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 723 724**系统能力：** SystemCapability.ArkUI.ArkUI.Full 725 726### left 727 728left(value: Length): T 729 730导航点左侧相对于Swiper的位置。 731 732**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 733 734**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 735 736**系统能力：** SystemCapability.ArkUI.ArkUI.Full 737 738**参数：** 739 740| 参数名 | 类型 | 必填 | 说明 | 741| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 742| value | [Length](ts-types.md#length) | 是 | 设置导航点左侧相对于Swiper的位置。<br/>未设置left和right时，进行自适应大小布局，按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐。<br/>设置为0时：按照0位置布局计算。<br/>优先级：高于right属性。<br/>取值范围：[0,Swiper宽度-导航点区域宽度]，超出该范围时，取最近的边界值。 | 743 744### top 745 746top(value: Length): T 747 748导航点顶部相对于Swiper的位置。 749 750**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 751 752**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 753 754**系统能力：** SystemCapability.ArkUI.ArkUI.Full 755 756**参数：** 757 758| 参数名 | 类型 | 必填 | 说明 | 759| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 760| value | [Length](ts-types.md#length) | 是 | 设置导航点顶部相对于Swiper的位置。<br/>未设置top和bottom时，进行自适应大小布局，按照指示器本身大小和Swiper的大小，在交叉轴方向上，位于底部，效果与设置bottom=0一致。<br/>设置为0时：按照0位置布局计算。<br/>优先级：高于bottom属性。<br/>取值范围：[0,Swiper高度-导航点区域高度]，超出该范围时，取最近的边界值。 | 761 762### right 763 764right(value: Length): T 765 766导航点右侧相对于Swiper的位置。 767 768**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 769 770**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 771 772**系统能力：** SystemCapability.ArkUI.ArkUI.Full 773 774**参数：** 775 776| 参数名 | 类型 | 必填 | 说明 | 777| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 778| value | [Length](ts-types.md#length) | 是 | 设置导航点右侧相对于Swiper的位置。<br/>未设置left和right时，进行自适应大小布局，按照指示器本身大小和Swiper的大小在主轴方向上进行居中对齐。<br/>设置为0时：按照0位置布局计算。<br/>优先级：低于left属性。<br/>取值范围：[0,Swiper宽度-导航点区域宽度]，超出该范围 时，取最近的边界值。 | 779 780### bottom 781 782bottom(value: Length): T 783 784导航点底部相对于Swiper的位置。 785 786**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 787 788**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 789 790**系统能力：** SystemCapability.ArkUI.ArkUI.Full 791 792**参数：** 793 794| 参数名 | 类型 | 必填 | 说明 | 795| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 796| value | [Length](ts-types.md#length) | 是 | 设置导航点底部相对于Swiper的位置。<br/>未设置top和bottom时，进行自适应大小布局，按照指示器本身大小和Swiper的大小，在交叉轴方向上，位于底部，效果与设置bottom=0一致。<br/>设置为0时：按照0位置布局计算。<br/>优先级：低于top属性。<br/>取值范围：[0,Swiper高度-导航点区域高度]，超出该范围时，取最近的边界值。 | 797 798### start<sup>12+</sup> 799 800start(value: LengthMetrics): T 801 802在RTL模式下为导航点距离Swiper组件右边的距离，在LTR模式下为导航点距离Swiper组件左边的距离。 803 804**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 805 806**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 807 808**系统能力：** SystemCapability.ArkUI.ArkUI.Full 809 810**参数：** 811 812| 参数名 | 类型 | 必填 | 说明 | 813| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 814| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 是 | 设置在RTL模式下为导航点距离Swiper组件右边的距离，在LTR模式下为导航点距离Swiper组件左边的距离<br/>默认值：0<br/>单位：vp | 815 816### end<sup>12+</sup> 817 818end(value: LengthMetrics): T 819 820在RTL模式下为导航点距离Swiper组件左边的距离，在LTR模式下为导航点距离Swiper组件右边的距离。 821 822**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 823 824**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 825 826**系统能力：** SystemCapability.ArkUI.ArkUI.Full 827 828**参数：** 829 830| 参数名 | 类型 | 必填 | 说明 | 831| ------ | ---------------------------- | ---- | ---------------------------------------- | 832| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 是 | 设置在RTL模式下为导航点距离Swiper组件左边的距离，在LTR模式下为导航点距离Swiper组件右边的距离。<br/>默认值：0<br/>单位：vp | 833 834### dot 835 836static dot(): DotIndicator 837 838返回一个DotIndicator对象。 839 840**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 841 842**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 843 844**系统能力：** SystemCapability.ArkUI.ArkUI.Full 845 846**返回值：** 847 848| 类型 | 说明 | 849| ------------------------------- | ------------ | 850| [DotIndicator](#dotindicator10) | 圆点指示器。 | 851 852### digit 853 854static digit(): DigitIndicator 855 856返回一个DigitIndicator对象。 857 858**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 859 860**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 861 862**系统能力：** SystemCapability.ArkUI.ArkUI.Full 863 864**返回值：** 865 866| 类型 | 说明 | 867| ----------------------------------- | ------------ | 868| [DigitIndicator](#digitindicator10) | 数字指示器。 | 869 870## DotIndicator<sup>10+</sup> 871 872构造圆点指示器的样式，继承自[Indicator](#indicator10)。 873 874**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 875 876**系统能力：** SystemCapability.ArkUI.ArkUI.Full 877 878### itemWidth 879 880itemWidth(value: Length): DotIndicator 881 882Swiper组件圆点导航指示器的宽，不支持设置百分比。 883 884**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 885 886**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 887 888**系统能力：** SystemCapability.ArkUI.ArkUI.Full 889 890**参数：** 891 892| 参数名 | 类型 | 必填 | 说明 | 893| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 894| value | [Length](ts-types.md#length) | 是 | 设置Swiper组件圆点导航指示器的宽，不支持设置百分比。<br/>默认值：6<br/>单位：vp | 895 896**返回值：** 897 898| 类型 | 说明 | 899| ------------------------------- | ------------ | 900| [DotIndicator](#dotindicator10) | 圆点指示器。 | 901 902### itemHeight 903 904itemHeight(value: Length): DotIndicator 905 906Swiper组件圆点导航指示器的高，不支持设置百分比。 907 908**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 909 910**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 911 912**系统能力：** SystemCapability.ArkUI.ArkUI.Full 913 914**参数：** 915 916| 参数名 | 类型 | 必填 | 说明 | 917| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 918| value | [Length](ts-types.md#length) | 是 | 设置Swiper组件圆点导航指示器的高，不支持设置百分比。<br/>默认值：6<br/>单位：vp | 919 920**返回值：** 921 922| 类型 | 说明 | 923| ------------------------------- | ------------ | 924| [DotIndicator](#dotindicator10) | 圆点指示器。 | 925 926### selectedItemWidth 927 928selectedItemWidth(value: Length): DotIndicator 929 930选中Swiper组件圆点导航指示器的宽，不支持设置百分比。 931 932**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 933 934**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 935 936**系统能力：** SystemCapability.ArkUI.ArkUI.Full 937 938**参数：** 939 940| 参数名 | 类型 | 必填 | 说明 | 941| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 942| value | [Length](ts-types.md#length) | 是 | 设置选中Swiper组件圆点导航指示器的宽，不支持设置百分比。<br/>默认值：12<br/>单位：vp | 943 944**返回值：** 945 946| 类型 | 说明 | 947| ------------------------------- | ------------ | 948| [DotIndicator](#dotindicator10) | 圆点指示器。 | 949 950### selectedItemHeight 951 952selectedItemHeight(value: Length): DotIndicator 953 954选中Swiper组件圆点导航指示器的高，不支持设置百分比。 955 956**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 957 958**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 959 960**系统能力：** SystemCapability.ArkUI.ArkUI.Full 961 962**参数：** 963 964| 参数名 | 类型 | 必填 | 说明 | 965| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 966| value | [Length](ts-types.md#length) | 是 | 设置选中Swiper组件圆点导航指示器的高，不支持设置百分比。<br/>默认值：6<br/>单位：vp | 967 968**返回值：** 969 970| 类型 | 说明 | 971| ------------------------------- | ------------ | 972| [DotIndicator](#dotindicator10) | 圆点指示器。 | 973 974### mask 975 976mask(value: boolean): DotIndicator 977 978是否显示Swiper组件圆点导航指示器的蒙版样式。 979 980**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 981 982**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 983 984**系统能力：** SystemCapability.ArkUI.ArkUI.Full 985 986**参数：** 987 988| 参数名 | 类型 | 必填 | 说明 | 989| ------ | ------- | ---- | ------------------------------------------------------------ | 990| value | boolean | 是 | 设置是否显示Swiper组件圆点导航指示器的蒙版样式。<br/>默认值：false | 991 992**返回值：** 993 994| 类型 | 说明 | 995| ------------------------------- | ------------ | 996| [DotIndicator](#dotindicator10) | 圆点指示器。 | 997 998### color 999 1000color(value: ResourceColor): DotIndicator 1001 1002Swiper组件圆点导航指示器的颜色。 1003 1004**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1005 1006**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1007 1008**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1009 1010**参数：** 1011 1012| 参数名 | 类型 | 必填 | 说明 | 1013| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 1014| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置Swiper组件圆点导航指示器的颜色。<br/>默认值：'\#182431'（10%透明度） | 1015 1016**返回值：** 1017 1018| 类型 | 说明 | 1019| ------------------------------- | ------------ | 1020| [DotIndicator](#dotindicator10) | 圆点指示器。 | 1021 1022### selectedColor 1023 1024selectedColor(value: ResourceColor): DotIndicator 1025 1026选中Swiper组件圆点导航指示器的颜色。 1027 1028**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1029 1030**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1031 1032**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1033 1034**参数：** 1035 1036| 参数名 | 类型 | 必填 | 说明 | 1037| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 1038| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置选中Swiper组件圆点导航指示器的颜色。<br/>默认值：'\#007DFF' | 1039 1040**返回值：** 1041 1042| 类型 | 说明 | 1043| ------------------------------- | ------------ | 1044| [DotIndicator](#dotindicator10) | 圆点指示器。 | 1045 1046### maxDisplayCount<sup>12+</sup> 1047 1048maxDisplayCount(maxDisplayCount: number): DotIndicator 1049 1050圆点导航点指示器样式下，导航点显示个数最大值。 1051 1052单独导航点组件在没有和Swiper绑定使用时，该属性不生效。 1053 1054**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1055 1056**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1057 1058**参数：** 1059 1060| 参数名 | 类型 | 必填 | 说明 | 1061| --------------- | ------ | ---- | ------------------------------------------------------------ | 1062| maxDisplayCount | number | 是 | 设置圆点导航点指示器样式下，导航点显示个数最大值，当实际导航点个数大于最大导航点个数时，会生效超长效果样式，样式如示例5所示。<br/>默认值：这个属性没有默认值，如果设置异常值那等同于没有超长显示效果。<br/>取值范围：6-9<br/>**说明：** <br/>1、超长显示场景，目前暂时不支持交互功能（包括：手指点击拖拽、鼠标操作等）。<br/>2、在超长显示场景下，中间页面对应的选中导航点的位置，并不是完全固定的，取决于之前的翻页操作序列。<br/>3、当前仅支持displayCount为1的场景。 | 1063 1064**返回值：** 1065 1066| 类型 | 说明 | 1067| ------------------------------- | ------------ | 1068| [DotIndicator](#dotindicator10) | 圆点指示器。 | 1069 1070### constructor 1071 1072constructor() 1073 1074DotIndicator的构造函数。 1075 1076**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1077 1078**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1079 1080**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1081 1082>**说明：** 1083> 1084>按压导航点时，导航点会放大至1.33倍显示，因此非按压态时导航点的可见范围边界至实际范围边界存在一定距离，该距离会随着itemWidth、itemHeight、selectedItemWidth、selectedItemHeight等参数变大而变大。 1085 1086## DigitIndicator<sup>10+</sup> 1087 1088构造数字指示器的样式，继承自[Indicator](#indicator10)。 1089 1090**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1091 1092**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1093 1094**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1095 1096>**说明：** 1097> 1098>按组翻页时，数字导航点显示的子节点数量，不包括占位节点。<br/> 1099>数字导航点文本最大的字体缩放倍数[maxFontScale](ts-basic-components-text.md#maxfontscale12)为2。 1100 1101### fontColor 1102 1103fontColor(value: ResourceColor): DigitIndicator 1104 1105Swiper组件数字导航点的字体颜色。 1106 1107**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1108 1109**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1110 1111**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1112 1113**参数：** 1114 1115| 参数名 | 类型 | 必填 | 说明 | 1116| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 1117| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置Swiper组件数字导航点的字体颜色。<br/>默认值：'\#ff182431' | 1118 1119**返回值：** 1120 1121| 类型 | 说明 | 1122| ----------------------------------- | ------------ | 1123| [DigitIndicator](#digitindicator10) | 数字指示器。 | 1124 1125### selectedFontColor 1126 1127selectedFontColor(value: ResourceColor): DigitIndicator 1128 1129选中Swiper组件数字导航点的字体颜色。 1130 1131**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1132 1133**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1134 1135**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1136 1137**参数：** 1138 1139| 参数名 | 类型 | 必填 | 说明 | 1140| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 1141| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置选中Swiper组件数字导航点的字体颜色。<br/>默认值：'\#ff182431' | 1142 1143**返回值：** 1144 1145| 类型 | 说明 | 1146| ----------------------------------- | ------------ | 1147| [DigitIndicator](#digitindicator10) | 数字指示器。 | 1148 1149### digitFont 1150 1151digitFont(value: Font): DigitIndicator 1152 1153Swiper组件数字导航点的字体样式。 1154 1155**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1156 1157**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1158 1159**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1160 1161**参数：** 1162 1163| 参数名 | 类型 | 必填 | 说明 | 1164| ------ | ------------------------ | ---- | ------------------------------------------------------------ | 1165| value | [Font](ts-types.md#font) | 是 | 设置Swiper组件数字导航点的字体样式。<br/>只支持Font中size和weight参数，family和style设置不生效。<br/>默认值：<br/>{ size: 14, weight: FontWeight.Normal } | 1166 1167**返回值：** 1168 1169| 类型 | 说明 | 1170| ----------------------------------- | ------------ | 1171| [DigitIndicator](#digitindicator10) | 数字指示器。 | 1172 1173### selectedDigitFont 1174 1175selectedDigitFont(value: Font): DigitIndicator 1176 1177选中Swiper组件数字导航点的字体样式。 1178 1179**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1180 1181**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1182 1183**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1184 1185**参数：** 1186 1187| 参数名 | 类型 | 必填 | 说明 | 1188| ------ | ------------------------ | ---- | ------------------------------------------------------------ | 1189| value | [Font](ts-types.md#font) | 是 | 设置选中Swiper组件数字导航点的字体样式。<br/>默认值：<br/>{ size: 14, weight: FontWeight.Normal } | 1190 1191>**说明：** 1192> 1193> 按组翻页时，数字导航点显示的子节点数量，不包括占位节点。 1194 1195**返回值：** 1196 1197| 类型 | 说明 | 1198| ----------------------------------- | ------------ | 1199| [DigitIndicator](#digitindicator10) | 数字指示器。 | 1200 1201### constructor 1202 1203constructor() 1204 1205DigitIndicator的构造函数。 1206 1207**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1208 1209**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1210 1211**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1212 1213## ArrowStyle<sup>10+</sup>对象说明 1214左右箭头属性。 1215 1216**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1217 1218**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1219 1220| 名称 | 类型 | 必填 | 说明 | 1221| ---------------- | ---------------------------------------- | ---- | ---------------------------------------- | 1222| showBackground | boolean | 否 | 设置箭头底板是否显示。为true时箭头底板显示，为false时箭头底板不显示。<br/>默认值：false | 1223| isSidebarMiddle | boolean | 否 | 设置箭头显示位置。为true时箭头居中显示在swiper组件两侧，为false时显示在导航点指示器两侧。<br/>默认值：false <br/>默认显示在导航点指示器两侧。 | 1224| backgroundSize | [Length](ts-types.md#length) | 否 | 设置底板大小。<br/>在导航点两侧显示：<br/>默认值：24vp<br/>在组件两侧显示：<br/>默认值：32vp<br/>不支持设置百分比。 | 1225| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置底板颜色。<br/>在导航点两侧显示：<br/>默认值：'\#00000000'<br/>在组件两侧显示：<br/>默认值：'\#19182431' | 1226| arrowSize | [Length](ts-types.md#length) | 否 | 设置箭头大小。<br/>在导航点两侧显示时：<br/>默认值：18vp<br/>在组件两侧显示时：<br/>默认值：24vp<br/>**说明：**<br/>showBackground为true时，arrowSize为backgroundSize的3/4。<br/>不支持设置百分比。 | 1227| arrowColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置箭头颜色。<br/>默认值：'\#182431' | 1228 1229## SwiperAutoFill<sup>10+</sup> 1230 1231自适应属性。 1232 1233**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1234 1235**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1236 1237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1238 1239| 名称 | 类型 | 必填 | 说明 | 1240| ------- | -------------------- | ------ | ------------------------------------ | 1241| minSize | [VP](ts-types.md#vp10) | 是 | 设置元素显示最小宽度。<br/>默认值：0 | 1242 1243## AutoPlayOptions<sup>18+</sup>对象说明 1244 1245自动播放属性。 1246 1247**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 1248 1249**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1250 1251**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1252 1253| 名称 | 类型 | 必填 | 说明 | 1254| ---------------- | ---------------------------------------- | ---- | ---------------------------------------- | 1255| stopWhenTouched | boolean | 是 | 在按下事件中配置子组件是否立即停止播放。<br/>设置为true时，停止播放。设置为false时，自动播放不中断。<br/>默认值：true | 1256 1257## 事件 1258 1259除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 1260 1261### onChange 1262 1263onChange(event: Callback\<number>) 1264 1265当前显示的子组件索引变化时触发该事件，返回值为当前显示的子组件的索引值。 1266 1267Swiper组件结合LazyForEach使用时，不能在onChange事件里触发子页面UI的刷新。 1268 1269**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1270 1271**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1272 1273**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1274 1275**参数：** 1276 1277| 参数名 | 类型 | 必填 | 说明 | 1278| ------ | ------ | ---- | -------------------- | 1279| event | [Callback](./ts-types.md#callback12)\<number> | 是 | 当前显示元素的索引。 | 1280 1281### onAnimationStart<sup>9+</sup> 1282 1283onAnimationStart(event: OnSwiperAnimationStartCallback) 1284 1285切换动画开始时触发该回调。 1286 1287**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1288 1289**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1290 1291**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1292 1293**参数：** 1294 1295| 参数名 | 类型 | 必填 | 说明 | 1296| ------ | ------ | ---- | -------------------- | 1297| event | [OnSwiperAnimationStartCallback](#onswiperanimationstartcallback18) | 是 | 切换动画开始时触发的回调。 | 1298 1299>**说明：** 1300> 1301>- 当翻页动画时长为0时，只有以下场景会触发该回调：滑动翻页、自动轮播、调用SwiperController.showNext()和SwiperController.showPrevious()接口以及手指点击导航点翻页。 1302 1303### onAnimationEnd<sup>9+</sup> 1304 1305onAnimationEnd(event: OnSwiperAnimationEndCallback) 1306 1307切换动画结束时触发该回调。 1308 1309当Swiper切换动效结束时触发，包括动画过程中手势中断，通过SwiperController调用finishAnimation。 1310 1311**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 1312 1313**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1314 1315**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1316 1317**参数：** 1318 1319| 参数名 | 类型 | 必填 | 说明 | 1320| ------ | ------ | ---- | -------------------- | 1321| event | [OnSwiperAnimationEndCallback](#onswiperanimationendcallback18) | 是 | 切换动画结束时触发的回调。 | 1322 1323>**说明：** 1324> 1325>- 当翻页动画时长为0时，只有以下场景会触发该回调：滑动翻页、自动轮播、调用SwiperController.showNext()和SwiperController.showPrevious()接口以及手指点击导航点翻页。 1326 1327### onGestureSwipe<sup>10+</sup> 1328 1329onGestureSwipe(event: OnSwiperGestureSwipeCallback) 1330 1331在页面跟手滑动过程中，逐帧触发该回调。 1332 1333**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1334 1335**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1336 1337**参数：** 1338 1339| 参数名 | 类型 | 必填 | 说明 | 1340| ------ | ------ | ---- | -------------------- | 1341| event | [OnSwiperGestureSwipeCallback](#onswipergestureswipecallback18) | 是 | 在页面跟手滑动过程中，逐帧触发的回调。 | 1342 1343### customContentTransition<sup>12+</sup> 1344 1345customContentTransition(transition: SwiperContentAnimatedTransition) 1346 1347自定义Swiper页面切换动画。在页面跟手滑动和离手后执行切换动画的过程中，会对视窗内所有页面逐帧触发回调，开发者可以在回调中设置透明度、缩放比例、位移等属性来自定义切换动画。 1348 1349使用说明： 1350 13511、循环场景下，设置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页的位移。 1352 1353**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1354 1355**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1356 1357**参数：** 1358 1359| 参数名 | 类型 | 必填 | 说明 | 1360| ------ | ---- | ---- | ---- | 1361| transition | [SwiperContentAnimatedTransition](#swipercontentanimatedtransition12) | 是 | Swiper自定义切换动画相关信息。 | 1362 1363### onContentDidScroll<sup>12+</sup> 1364 1365onContentDidScroll(handler: ContentDidScrollCallback) 1366 1367监听Swiper页面滑动事件。 1368 1369使用说明： 1370 13711、循环场景下，设置prevMargin和nextMargin属性，使得Swiper前后端显示同一页面时，该接口不生效。<br>2、在页面滑动过程中，会对视窗内所有页面逐帧触发[ContentDidScrollCallback](#contentdidscrollcallback12)回调。例如，当视窗内有下标为0、1的两个页面时，会每帧触发两次index值分别为0和1的回调。<br>3、设置displayCount属性的swipeByGroup参数为true时，若同组中至少有一个页面在视窗内时，则会对同组中所有页面触发回调。 1372 1373**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1374 1375**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1376 1377**参数：** 1378 1379| 参数名 | 类型 | 必填 | 说明 | 1380| ------ | ---- | ---- | ---- | 1381| handler | [ContentDidScrollCallback](#contentdidscrollcallback12) | 是 | Swiper滑动时触发的回调。 | 1382 1383### onSelected<sup>18+</sup> 1384 1385onSelected(event: Callback\<number>) 1386 1387当选中元素改变时触发该回调，返回值为当前选中的元素的索引值。 1388 1389**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 1390 1391**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1392 1393**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1394 1395**参数：** 1396 1397| 参数名 | 类型 | 必填 | 说明 | 1398| ------ | ------ | ---- | -------------------- | 1399| event | [Callback](./ts-types.md#callback12)\<number> | 是 | 当前选中元素的索引。 | 1400 1401> **说明：** 1402> 1403> onSelected回调中不可修改swiper的index属性，不可调用SwiperController.changeIndex()、SwiperController.showNext()和SwiperController.showPrevious()方法。 1404 1405### onUnselected<sup>18+</sup> 1406 1407onUnselected(event: Callback\<number>) 1408 1409当选中元素改变时触发该回调，返回值为将要隐藏的元素的索引值。 1410 1411**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 1412 1413**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1414 1415**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1416 1417**参数：** 1418 1419| 参数名 | 类型 | 必填 | 说明 | 1420| ------ | ------ | ---- | -------------------- | 1421| event | [Callback](./ts-types.md#callback12)\<number> | 是 | 将要隐藏元素的索引。 | 1422 1423> **说明：** 1424> 1425> onUnselected回调中不可修改swiper的index属性，不可调用SwiperController.changeIndex()、SwiperController.showNext()和SwiperController.showPrevious()方法。 1426 1427### onContentWillScroll<sup>15+</sup> 1428 1429onContentWillScroll(handler: ContentWillScrollCallback) 1430 1431Swiper滑动行为拦截事件，在滑动前触发。Swiper会依据该事件的返回值来决定是否允许此次滑动行为。若返回true，表示允许此次滑动行为，Swiper页面将跟随滑动。若返回false，表示不允许此次滑动，页面将保持静止。 1432 14331. 触发该事件的场景仅限于手势操作，具体包括手指滑动、滚动鼠标滚轮以及使用键盘方向键进行焦点移动。 1434 14352. 在手指滑动的过程中，每帧都将触发该事件，系统会依据事件的返回值判断是否对每帧的滑动做出响应。 1436 14373. 对于滚动鼠标滚轮和使用键盘方向键进行焦点移动的场景，每次翻页操作都会触发一次该事件，翻页是否被允许将根据事件的返回值来决定。 1438 1439**卡片能力：** 从API version 15开始，该接口支持在ArkTS卡片中使用。 1440 1441**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1442 1443**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1444 1445**参数：** 1446 1447| 参数名 | 类型 | 必填 | 说明 | 1448| ------ | ---- | ---- | ---- | 1449| handler | [ContentWillScrollCallback](#contentwillscrollcallback15) | 是 | Swiper滑动时触发的回调。 | 1450 1451## OnSwiperAnimationStartCallback<sup>18+</sup> 1452 1453type OnSwiperAnimationStartCallback = (index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => void 1454 1455切换动画开始时触发的回调。 1456 1457**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 1458 1459**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1460 1461**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1462 1463**参数：** 1464 1465| 参数名 | 类型 | 必填 | 说明 | 1466| ------------------------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1467| index | number | 是 | 当前显示元素的索引。多列Swiper时，index为最左侧组件的索引。 | 1468| targetIndex<sup>10+</sup> | number | 是 | 切换动画目标元素的索引。 | 1469| extraInfo<sup>10+</sup> | [SwiperAnimationEvent](#swiperanimationevent10对象说明) | 是 | 动画相关信息，包括主轴方向上当前显示元素和目标元素相对Swiper起始位置的位移，以及离手速度。 | 1470 1471## OnSwiperAnimationEndCallback<sup>18+</sup> 1472 1473type OnSwiperAnimationEndCallback = (index: number, extraInfo: SwiperAnimationEvent) => void 1474 1475切换动画结束时触发的回调。 1476 1477**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 1478 1479**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1480 1481**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1482 1483**参数：** 1484 1485| 参数名 | 类型 | 必填 | 说明 | 1486| ----------------------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1487| index | number | 是 | 当前显示元素的索引。多列Swiper时，index为最左侧组件的索引。 | 1488| extraInfo<sup>10+</sup> | [SwiperAnimationEvent](#swiperanimationevent10对象说明) | 是 | 动画相关信息，只返回主轴方向上当前显示元素相对于Swiper起始位置的位移。 | 1489 1490## OnSwiperGestureSwipeCallback<sup>18+</sup> 1491 1492type OnSwiperGestureSwipeCallback = (index: number, extraInfo: SwiperAnimationEvent) => void 1493 1494在页面跟手滑动过程中，逐帧触发的回调。 1495 1496**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1497 1498**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1499 1500**参数：** 1501 1502| 参数名 | 类型 | 必填 | 说明 | 1503| --------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1504| index | number | 是 | 当前显示元素的索引。多列Swiper时，index为最左侧组件的索引。 | 1505| extraInfo | [SwiperAnimationEvent](#swiperanimationevent10对象说明) | 是 | 动画相关信息，只返回主轴方向上当前显示元素相对于Swiper起始位置的位移。 | 1506 1507## ContentDidScrollCallback<sup>12+</sup> 1508 1509type ContentDidScrollCallback = (selectedIndex: number, index: number, position: number, mainAxisLength: number) => void 1510 1511Swiper滑动时触发的回调，参数可参考[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)中的说明。 1512 1513**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1514 1515**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1516 1517| 参数名 | 类型 | 必填 | 说明 | 1518| ------ | ---- | ---- | ---- | 1519| selectedIndex | number | 是 | 当前选中页面的索引。 | 1520| index | number | 是 | 视窗内页面的索引。 | 1521| position | number | 是 | index页面相对于Swiper主轴起始位置（selectedIndex对应页面的起始位置）的移动比例。 | 1522| mainAxisLength | number | 是 | index对应页面在主轴方向上的长度，单位vp。 | 1523 1524## ContentWillScrollCallback<sup>15+</sup> 1525 1526type ContentWillScrollCallback = (result: SwiperContentWillScrollResult) => boolean 1527 1528Swiper即将滑动前触发的回调，返回值表示是否允许此次滑动。 1529 1530**卡片能力：** 从API version 15开始，该接口支持在ArkTS卡片中使用。 1531 1532**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1533 1534**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1535 1536**参数：** 1537 1538| 参数名 | 类型 | 必填 | 说明 | 1539| ------ | ---- | ---- | ---- | 1540| result | [SwiperContentWillScrollResult](#swipercontentwillscrollresult15对象说明) | 是 | 即将滑动的相关信息，主要包括：当前页面对应的index、滑动方向上即将显示的页面index和此次滑动的位移。 | 1541 1542**返回值：** 1543 1544| 类型 | 说明 | 1545| ------ | ---- | 1546| boolean | Swiper是否响应本次滑动，true表示响应，false表示不响应。 | 1547 1548## SwiperContentWillScrollResult<sup>15+</sup>对象说明 1549 1550滑动的相关信息，主要包括：当前页面对应的index、滑动方向上即将显示的页面index和此次滑动的位移。 1551 1552**卡片能力：** 从API version 15开始，该接口支持在ArkTS卡片中使用。 1553 1554**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1555 1556**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1557 1558| 名称 | 类型 | 必填 | 说明 | 1559| ------ | ---- | ---- | ---- | 1560| currentIndex | number | 是 | 当前页面对应的index。在一次跟手滑动过程中，只要手指未离开屏幕，该值将保持不变，即使该页面已完全移出视窗，如在涉及多个页面的场景中。 | 1561| comingIndex | number | 是 | 滑动方向上即将显示的页面index。 | 1562| offset | number | 是 | 此次滑动的位移，带有符号，正负分别指示不同的翻页方向。正数表示从index=1向index=0翻页，负数表示从index=0向index=1翻页。<br>在手指滑动的场景中，该值为滑动事件中每帧传递下来的偏移量。在滚动鼠标滚轮和使用键盘方向键导航的场景中，该值代表即将翻页的距离。 | 1563 1564## SwiperAnimationEvent<sup>10+</sup>对象说明 1565 1566Swiper组件动画相关信息集合。 1567 1568**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1569 1570**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1571 1572| 名称 | 类型 | 只读 | 可选 | 说明 | 1573| ------------- | ----------- | ---- | ---- |------------------------------- | 1574| currentOffset | number | 否 | 否 | Swiper当前显示元素在主轴方向上，相对于Swiper起始位置的位移。单位VP，默认值为0。| 1575| targetOffset | number | 否 | 否 | Swiper动画目标元素在主轴方向上，相对于Swiper起始位置的位移。单位VP，默认值为0。| 1576| velocity | number | 否 | 否 | Swiper离手动画开始时的离手速度。单位VP/S，默认值为0。| 1577 1578## SwiperContentAnimatedTransition<sup>12+</sup> 1579 1580Swiper自定义切换动画相关信息。 1581 1582**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1583 1584**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1585 1586| 名称 | 类型 | 必填 | 说明 | 1587| ------ | ---- | ---- | ---- | 1588| timeout | number | 否 | Swiper自定义切换动画超时时间。从页面执行默认动画（页面滑动）至移出视窗外的第一帧开始计时，如果到达该时间后，开发者仍未调用[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)的finishTransition接口通知Swiper组件此页面的自定义动画已结束，那么组件就会认为此页面的自定义动画已结束，立即将该页面节点下渲染树。单位ms，默认值为0。 | 1589| transition | Callback<[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)> | 是 | 自定义切换动画具体内容。 | 1590 1591## SwiperContentTransitionProxy<sup>12+</sup> 1592 1593Swiper自定义切换动画执行过程中，返回给开发者的proxy对象。开发者可通过该对象获取自定义动画视窗内的页面信息，同时，也可以通过调用该对象的finishTransition接口通知Swiper组件页面自定义动画已结束。 1594 1595**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1596 1597**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1598 1599### 属性 1600 1601| 名称 | 类型 | 只读 | 可选 | 说明 | 1602| ---- | ---- | --- | ---- | --- | 1603| selectedIndex | number | 否 | 否 | 当前选中页面的索引。 | 1604| index | number | 否 | 否 | 视窗内页面的索引。 | 1605| position | number | 否 | 否 | index页面相对于Swiper主轴起始位置（selectedIndex对应页面的起始位置）的移动比例。 | 1606| mainAxisLength | number | 否 | 否 | index对应页面在主轴方向上的长度，单位vp。 | 1607 1608>**说明：** 1609> 1610>- 例如，当前选中的子组件的索引为0，从第0页切换到第1页的动画过程中，每帧都会对视窗内所有页面触发回调，当视窗内有第0页和第1页两页时，每帧会触发两次回调。其中，第一次回调的selectedIndex为0、index为0、position为当前帧第0页相对于动画开始前第0页的移动比例，mainAxisLength为主轴方向上第0页的长度。第二次回调的selectedIndex仍为0、index为1、position为当前帧第1页相对于动画开始前第0页的移动比例，mainAxisLength为主轴方向上第1页的长度。 1611> 1612>- 若动画曲线为弹簧插值曲线，从第0页切换到第1页的动画过程中，可能会因为离手时的位置和速度，先过滑到第2页，再回弹到第1页，该过程中每帧会对视窗内第1页和第2页触发回调。 1613 1614 1615### finishTransition<sup>12+</sup> 1616 1617finishTransition(): void 1618 1619通知Swiper组件，此页面的自定义动画已结束。 1620 1621**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1622 1623**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1624 1625## 示例 1626 1627### 示例1（设置导航点交互及翻页动效） 1628 1629该示例通过changeIndex接口设置SwiperAnimationMode动效模式，实现了Swiper组件翻页至指定页面。 1630 1631```ts 1632// xxx.ets 1633class MyDataSource implements IDataSource { 1634 private list: number[] = [] 1635 1636 constructor(list: number[]) { 1637 this.list = list 1638 } 1639 1640 totalCount(): number { 1641 return this.list.length 1642 } 1643 1644 getData(index: number): number { 1645 return this.list[index] 1646 } 1647 1648 registerDataChangeListener(listener: DataChangeListener): void { 1649 } 1650 1651 unregisterDataChangeListener() { 1652 } 1653} 1654 1655@Entry 1656@Component 1657struct SwiperExample { 1658 private swiperController: SwiperController = new SwiperController() 1659 private data: MyDataSource = new MyDataSource([]) 1660 1661 aboutToAppear(): void { 1662 let list: number[] = [] 1663 for (let i = 1; i <= 10; i++) { 1664 list.push(i); 1665 } 1666 this.data = new MyDataSource(list) 1667 } 1668 1669 build() { 1670 Column({ space: 5 }) { 1671 Swiper(this.swiperController) { 1672 LazyForEach(this.data, (item: string) => { 1673 Text(item.toString()) 1674 .width('90%') 1675 .height(160) 1676 .backgroundColor(0xAFEEEE) 1677 .textAlign(TextAlign.Center) 1678 .fontSize(30) 1679 }, (item: string) => item) 1680 } 1681 .cachedCount(2) 1682 .index(1) 1683 .autoPlay(true) 1684 .interval(4000) 1685 .loop(true) 1686 .indicatorInteractive(true) 1687 .duration(1000) 1688 .itemSpace(5) 1689 .prevMargin(35) 1690 .nextMargin(35) 1691 .indicator( // 设置圆点导航点样式 1692 new DotIndicator() 1693 .itemWidth(15) 1694 .itemHeight(15) 1695 .selectedItemWidth(15) 1696 .selectedItemHeight(15) 1697 .color(Color.Gray) 1698 .selectedColor(Color.Blue)) 1699 .displayArrow({ // 设置导航点箭头样式 1700 showBackground: true, 1701 isSidebarMiddle: true, 1702 backgroundSize: 24, 1703 backgroundColor: Color.White, 1704 arrowSize: 18, 1705 arrowColor: Color.Blue 1706 }, false) 1707 .curve(Curve.Linear) 1708 .onChange((index: number) => { 1709 console.info(index.toString()) 1710 }) 1711 .onGestureSwipe((index: number, extraInfo: SwiperAnimationEvent) => { 1712 console.info("index: " + index) 1713 console.info("current offset: " + extraInfo.currentOffset) 1714 }) 1715 .onAnimationStart((index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => { 1716 console.info("index: " + index) 1717 console.info("targetIndex: " + targetIndex) 1718 console.info("current offset: " + extraInfo.currentOffset) 1719 console.info("target offset: " + extraInfo.targetOffset) 1720 console.info("velocity: " + extraInfo.velocity) 1721 }) 1722 .onAnimationEnd((index: number, extraInfo: SwiperAnimationEvent) => { 1723 console.info("index: " + index) 1724 console.info("current offset: " + extraInfo.currentOffset) 1725 }) 1726 1727 Row({ space: 12 }) { 1728 Button('showPrevious') 1729 .onClick(() => { 1730 this.swiperController.showPrevious() 1731 }) 1732 Button('showNext') 1733 .onClick(() => { 1734 this.swiperController.showNext() 1735 }) 1736 }.margin(5) 1737 Row({ space: 5 }) { 1738 Button('FAST 0') 1739 .onClick(() => { 1740 this.swiperController.changeIndex(0, SwiperAnimationMode.FAST_ANIMATION) 1741 }) 1742 Button('FAST 3') 1743 .onClick(() => { 1744 this.swiperController.changeIndex(3, SwiperAnimationMode.FAST_ANIMATION) 1745 }) 1746 Button('FAST ' + 9) 1747 .onClick(() => { 1748 this.swiperController.changeIndex(9, SwiperAnimationMode.FAST_ANIMATION) 1749 }) 1750 }.margin(5) 1751 }.width('100%') 1752 .margin({ top: 5 }) 1753 } 1754} 1755``` 1756 1757 1758 1759### 示例2（设置数字指示器） 1760 1761该示例通过DigitIndicator接口，实现了数字指示器的效果和功能。 1762 1763```ts 1764// xxx.ets 1765class MyDataSource implements IDataSource { 1766 private list: number[] = [] 1767 1768 constructor(list: number[]) { 1769 this.list = list 1770 } 1771 1772 totalCount(): number { 1773 return this.list.length 1774 } 1775 1776 getData(index: number): number { 1777 return this.list[index] 1778 } 1779 1780 registerDataChangeListener(listener: DataChangeListener): void { 1781 } 1782 1783 unregisterDataChangeListener() { 1784 } 1785} 1786 1787@Entry 1788@Component 1789struct SwiperExample { 1790 private swiperController: SwiperController = new SwiperController() 1791 private data: MyDataSource = new MyDataSource([]) 1792 1793 aboutToAppear(): void { 1794 let list: number[] = [] 1795 for (let i = 1; i <= 10; i++) { 1796 list.push(i); 1797 } 1798 this.data = new MyDataSource(list) 1799 } 1800 1801 build() { 1802 Column({ space: 5 }) { 1803 Swiper(this.swiperController) { 1804 LazyForEach(this.data, (item: string) => { 1805 Text(item.toString()) 1806 .width('90%') 1807 .height(160) 1808 .backgroundColor(0xAFEEEE) 1809 .textAlign(TextAlign.Center) 1810 .fontSize(30) 1811 }, (item: string) => item) 1812 } 1813 .cachedCount(2) 1814 .index(1) 1815 .autoPlay(true) 1816 .interval(4000) 1817 .indicator(Indicator.digit() // 设置数字导航点样式 1818 .top(200) 1819 .fontColor(Color.Gray) 1820 .selectedFontColor(Color.Gray) 1821 .digitFont({ size: 20, weight: FontWeight.Bold }) 1822 .selectedDigitFont({ size: 20, weight: FontWeight.Normal })) 1823 .loop(true) 1824 .duration(1000) 1825 .itemSpace(0) 1826 .displayArrow(true, false) 1827 1828 Row({ space: 12 }) { 1829 Button('showNext') 1830 .onClick(() => { 1831 this.swiperController.showNext() 1832 }) 1833 Button('showPrevious') 1834 .onClick(() => { 1835 this.swiperController.showPrevious() 1836 }) 1837 }.margin(5) 1838 }.width('100%') 1839 .margin({ top: 5 }) 1840 } 1841} 1842``` 1843 1844 1845### 示例3（设置按组翻页） 1846 1847该示例通过displayCount属性实现了按组翻页效果。 1848 1849```ts 1850// xxx.ets 1851class MyDataSource implements IDataSource { 1852 private list: number[] = [] 1853 1854 constructor(list: number[]) { 1855 this.list = list 1856 } 1857 1858 totalCount(): number { 1859 return this.list.length 1860 } 1861 1862 getData(index: number): number { 1863 return this.list[index] 1864 } 1865 1866 registerDataChangeListener(listener: DataChangeListener): void { 1867 } 1868 1869 unregisterDataChangeListener() { 1870 } 1871} 1872 1873@Entry 1874@Component 1875struct SwiperExample { 1876 private swiperController: SwiperController = new SwiperController() 1877 private data: MyDataSource = new MyDataSource([]) 1878 1879 aboutToAppear(): void { 1880 let list: number[] = [] 1881 for (let i = 1; i <= 10; i++) { 1882 list.push(i); 1883 } 1884 this.data = new MyDataSource(list) 1885 } 1886 1887 build() { 1888 Column({ space: 5 }) { 1889 Swiper(this.swiperController) { 1890 LazyForEach(this.data, (item: string) => { 1891 Text(item.toString()) 1892 .width('90%') 1893 .height(160) 1894 .backgroundColor(0xAFEEEE) 1895 .textAlign(TextAlign.Center) 1896 .fontSize(30) 1897 }, (item: string) => item) 1898 } 1899 .displayCount(3, true) 1900 .autoPlay(true) 1901 .interval(4000) 1902 .loop(true) 1903 .duration(1000) 1904 .itemSpace(10) 1905 .indicator( // 设置圆点导航点样式 1906 new DotIndicator() 1907 .itemWidth(15) 1908 .itemHeight(15) 1909 .selectedItemWidth(15) 1910 .selectedItemHeight(15) 1911 .color(Color.Gray) 1912 .selectedColor(Color.Blue)) 1913 1914 Row({ space: 12 }) { 1915 Button('showNext') 1916 .onClick(() => { 1917 this.swiperController.showNext() 1918 }) 1919 Button('showPrevious') 1920 .onClick(() => { 1921 this.swiperController.showPrevious() 1922 }) 1923 }.margin(5) 1924 }.width('100%') 1925 .margin({ top: 5 }) 1926 } 1927} 1928``` 1929 1930 1931### 示例4（设置自定义页面切换动画） 1932 1933该示例通过customContentTransition接口，实现了自定义Swiper页面按组翻页动画效果。 1934 1935<!--code_no_check--> 1936 1937```ts 1938// EntryAbility.ets 1939import { Configuration, UIAbility } from '@kit.AbilityKit'; 1940import { i18n } from '@kit.LocalizationKit'; 1941import { CommonUtil } from '../common/CommonUtil'; 1942 1943export default class EntryAbility extends UIAbility { 1944 onConfigurationUpdate(newConfig: Configuration): void { 1945 // 监听系统配置变化 1946 if (newConfig.language) { 1947 CommonUtil.setIsRTL(i18n.isRTL(newConfig.language)) 1948 } 1949 } 1950} 1951``` 1952 1953<!--code_no_check--> 1954 1955```ts 1956// CommonUtil.ets 1957import { i18n, intl } from '@kit.LocalizationKit'; 1958 1959export class CommonUtil { 1960 private static isRTL: boolean = i18n.isRTL((new intl.Locale()).language) 1961 1962 public static setIsRTL(isRTL: boolean): void { 1963 CommonUtil.isRTL = isRTL 1964 } 1965 1966 public static getIsRTL(): boolean { 1967 return CommonUtil.isRTL 1968 } 1969} 1970``` 1971 1972<!--code_no_check--> 1973 1974```ts 1975// xxx.ets 1976import { CommonUtil } from '../common/CommonUtil'; 1977 1978@Entry 1979@Component 1980struct SwiperCustomAnimationExample { 1981 private DISPLAY_COUNT: number = 2 1982 private MIN_SCALE: number = 0.75 1983 1984 @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange] 1985 @State opacityList: number[] = [] 1986 @State scaleList: number[] = [] 1987 @State translateList: number[] = [] 1988 @State zIndexList: number[] = [] 1989 1990 aboutToAppear(): void { 1991 for (let i = 0; i < this.backgroundColors.length; i++) { 1992 this.opacityList.push(1.0) 1993 this.scaleList.push(1.0) 1994 this.translateList.push(0.0) 1995 this.zIndexList.push(0) 1996 } 1997 } 1998 1999 build() { 2000 Column() { 2001 Swiper() { 2002 ForEach(this.backgroundColors, (backgroundColor: Color, index: number) => { 2003 Text(index.toString()).width('100%').height('100%').fontSize(50).textAlign(TextAlign.Center) 2004 .backgroundColor(backgroundColor) 2005 // 自定义动画变化透明度、缩放页面、抵消系统默认位移、渲染层级等 2006 .opacity(this.opacityList[index]) 2007 .scale({ x: this.scaleList[index], y: this.scaleList[index] }) 2008 .translate({ x: this.translateList[index] }) 2009 .zIndex(this.zIndexList[index]) 2010 }) 2011 } 2012 .height(300) 2013 .indicator(false) 2014 .displayCount(this.DISPLAY_COUNT, true) 2015 .customContentTransition({ 2016 // 页面移除视窗时超时1000ms下渲染树 2017 timeout: 1000, 2018 // 对视窗内所有页面逐帧回调transition，在回调中修改opacity、scale、translate、zIndex等属性值，实现自定义动画 2019 transition: (proxy: SwiperContentTransitionProxy) => { 2020 if (!CommonUtil.getIsRTL()) { 2021 if (proxy.position <= proxy.index % this.DISPLAY_COUNT || proxy.position >= this.DISPLAY_COUNT + proxy.index % this.DISPLAY_COUNT) { 2022 // 同组页面往左滑或往右完全滑出视窗外时，重置属性值 2023 this.opacityList[proxy.index] = 1.0 2024 this.scaleList[proxy.index] = 1.0 2025 this.translateList[proxy.index] = 0.0 2026 this.zIndexList[proxy.index] = 0 2027 } else { 2028 // 同组页面往右滑且未滑出视窗外时，对同组中左右两个页面，逐帧根据position修改属性值，实现两个页面往Swiper中间靠拢并透明缩放的自定义切换动画 2029 if (proxy.index % this.DISPLAY_COUNT === 0) { 2030 this.opacityList[proxy.index] = 1 - proxy.position / this.DISPLAY_COUNT 2031 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - proxy.position / this.DISPLAY_COUNT) 2032 this.translateList[proxy.index] = -proxy.position * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 2033 } else { 2034 this.opacityList[proxy.index] = 1 - (proxy.position - 1) / this.DISPLAY_COUNT 2035 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - (proxy.position - 1) / this.DISPLAY_COUNT) 2036 this.translateList[proxy.index] = -(proxy.position - 1) * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 2037 } 2038 this.zIndexList[proxy.index] = -1 2039 } 2040 } else { 2041 // 适配镜像 2042 if (proxy.position >= -proxy.index % this.DISPLAY_COUNT || proxy.position <= -this.DISPLAY_COUNT - proxy.index % this.DISPLAY_COUNT) { 2043 // 同组页面往右滑或往左完全滑出视窗外时，重置属性值 2044 this.opacityList[proxy.index] = 1.0 2045 this.scaleList[proxy.index] = 1.0 2046 this.translateList[proxy.index] = 0.0 2047 this.zIndexList[proxy.index] = 0 2048 } else { 2049 // 同组页面往左滑且未滑出视窗外时，对同组中左右两个页面，逐帧根据position修改属性值，实现两个页面往Swiper中间靠拢并透明缩放的自定义切换动画 2050 if (proxy.index % this.DISPLAY_COUNT === 0) { 2051 this.opacityList[proxy.index] = 1 + proxy.position / this.DISPLAY_COUNT 2052 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 + proxy.position / this.DISPLAY_COUNT) 2053 this.translateList[proxy.index] = -proxy.position * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 2054 } else { 2055 this.opacityList[proxy.index] = 1 + (proxy.position + 1) / this.DISPLAY_COUNT 2056 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 + (proxy.position + 1) / this.DISPLAY_COUNT) 2057 this.translateList[proxy.index] = -(proxy.position + 1) * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 2058 } 2059 this.zIndexList[proxy.index] = -1 2060 } 2061 } 2062 } 2063 }) 2064 .onContentDidScroll((selectedIndex: number, index: number, position: number, mainAxisLength: number) => { 2065 // 监听Swiper页面滑动事件，在该回调中可以实现自定义导航点切换动画等 2066 console.info("onContentDidScroll selectedIndex: " + selectedIndex + ", index: " + index + ", position: " + position + ", mainAxisLength: " + mainAxisLength) 2067 }) 2068 }.width('100%') 2069 } 2070} 2071``` 2072 2073 2074### 示例5（设置圆点导航点超长显示） 2075 2076该示例通过DotIndicator接口的maxDisplayCount属性，实现了圆点导航点超长显示动画效果。 2077 2078```ts 2079class MyDataSource implements IDataSource { 2080 private list: number[] = [] 2081 2082 constructor(list: number[]) { 2083 this.list = list 2084 } 2085 2086 totalCount(): number { 2087 return this.list.length 2088 } 2089 2090 getData(index: number): number { 2091 return this.list[index] 2092 } 2093 2094 registerDataChangeListener(listener: DataChangeListener): void { 2095 } 2096 2097 unregisterDataChangeListener() { 2098 } 2099} 2100 2101@Entry 2102@Component 2103struct Index { 2104 private swiperController: SwiperController = new SwiperController() 2105 private data: MyDataSource = new MyDataSource([]) 2106 2107 aboutToAppear(): void { 2108 let list: number[] = [] 2109 for (let i = 1; i <= 15; i++) { 2110 list.push(i); 2111 } 2112 this.data = new MyDataSource(list) 2113 } 2114 2115 build() { 2116 Column({ space: 5 }) { 2117 Swiper(this.swiperController) { 2118 LazyForEach(this.data, (item: string) => { 2119 Text(item.toString()) 2120 .width('90%') 2121 .height(160) 2122 .backgroundColor(0xAFEEEE) 2123 .textAlign(TextAlign.Center) 2124 .fontSize(30) 2125 }, (item: string) => item) 2126 } 2127 .cachedCount(2) 2128 .index(5) 2129 .autoPlay(true) 2130 .interval(4000) 2131 .loop(true) 2132 .duration(1000) 2133 .itemSpace(0) 2134 .indicator( // 设置圆点导航点样式 2135 new DotIndicator() 2136 .itemWidth(8) 2137 .itemHeight(8) 2138 .selectedItemWidth(16) 2139 .selectedItemHeight(8) 2140 .color(Color.Gray) 2141 .selectedColor(Color.Blue) 2142 .maxDisplayCount(9)) 2143 .displayArrow({ // 设置导航点箭头样式 2144 showBackground: true, 2145 isSidebarMiddle: true, 2146 backgroundSize: 24, 2147 backgroundColor: Color.White, 2148 arrowSize: 18, 2149 arrowColor: Color.Blue 2150 }, false) 2151 .curve(Curve.Linear) 2152 Row({ space: 12 }) { 2153 Button('showNext') 2154 .onClick(() => { 2155 this.swiperController.showNext() 2156 }) 2157 Button('showPrevious') 2158 .onClick(() => { 2159 this.swiperController.showPrevious() 2160 }) 2161 }.margin(5) 2162 }.width('100%') 2163 .margin({ top: 5 }) 2164 } 2165} 2166``` 2167 2168 2169 2170### 示例6（预加载子节点） 2171 2172本示例通过preloadItems接口实现了预加载指定子节点。 2173 2174```ts 2175// xxx.ets 2176import { BusinessError } from '@kit.BasicServicesKit' 2177 2178@Entry 2179@Component 2180struct SwiperPreloadItems { 2181 @State currentIndex: number = 1 2182 private swiperController: SwiperController = new SwiperController() 2183 @State arr: string[] = ["0", "1", "2", "3", "4", "5"] 2184 2185 build() { 2186 Column() { 2187 Swiper(this.swiperController) { 2188 ForEach(this.arr, (item: string) => { 2189 MyComponent({ txt: item }) 2190 }) 2191 } 2192 .cachedCount(1, true) 2193 .width("70%") 2194 .height("50%") 2195 2196 2197 Button('preload items: [2, 3]') 2198 .margin(5) 2199 .onClick(() => { 2200 // 预加载index=2和index=3的子节点 2201 try { 2202 this.swiperController.preloadItems([2, 3]) 2203 .then(() => { 2204 console.info('preloadItems [2, 3] success.') 2205 }) 2206 .catch((error: BusinessError) => { 2207 console.error('preloadItems [2, 3] failed, error code: ' + error.code + ', error message: ' + error.message) 2208 }) 2209 } catch (error) { 2210 console.error('preloadItems [2, 3] failed, error code: ' + error.code + ', error message: ' + error.message) 2211 } 2212 2213 }) 2214 } 2215 .width("100%") 2216 .margin(5) 2217 } 2218} 2219 2220@Component 2221struct MyComponent { 2222 private txt: string = "" 2223 2224 aboutToAppear(): void { 2225 console.info('aboutToAppear txt:' + this.txt) 2226 } 2227 2228 aboutToDisappear(): void { 2229 console.info('aboutToDisappear txt:' + this.txt) 2230 } 2231 2232 build() { 2233 Text(this.txt) 2234 .textAlign(TextAlign.Center) 2235 .width('100%') 2236 .height('100%') 2237 .backgroundColor(0xAFEEEE) 2238 } 2239} 2240``` 2241 2242### 示例7（实现Tabs与Swiper联动） 2243 2244该示例通过onSelected接口，实现了Tabs与Swiper联动切换。 2245 2246```ts 2247// xxx.ets 2248class MyDataSource implements IDataSource { 2249 private list: number[] = [] 2250 2251 constructor(list: number[]) { 2252 this.list = list 2253 } 2254 2255 totalCount(): number { 2256 return this.list.length 2257 } 2258 2259 getData(index: number): number { 2260 return this.list[index] 2261 } 2262 2263 registerDataChangeListener(listener: DataChangeListener): void { 2264 } 2265 2266 unregisterDataChangeListener() { 2267 } 2268} 2269 2270@Entry 2271@Component 2272struct TabsSwiperExample { 2273 @State fontColor: string = '#182431' 2274 @State selectedFontColor: string = '#007DFF' 2275 @State currentIndex: number = 0 2276 private list: number[] = [] 2277 private tabsController: TabsController = new TabsController() 2278 private swiperController: SwiperController = new SwiperController() 2279 private swiperData: MyDataSource = new MyDataSource([]) 2280 2281 aboutToAppear(): void { 2282 for (let i = 0; i <= 9; i++) { 2283 this.list.push(i); 2284 } 2285 this.swiperData = new MyDataSource(this.list) 2286 } 2287 2288 @Builder tabBuilder(index: number, name: string) { 2289 Column() { 2290 Text(name) 2291 .fontColor(this.currentIndex === index ? this.selectedFontColor : this.fontColor) 2292 .fontSize(16) 2293 .fontWeight(this.currentIndex === index ? 500 : 400) 2294 .lineHeight(22) 2295 .margin({ top: 17, bottom: 7 }) 2296 Divider() 2297 .strokeWidth(2) 2298 .color('#007DFF') 2299 .opacity(this.currentIndex === index ? 1 : 0) 2300 }.width('20%') 2301 } 2302 2303 build() { 2304 Column() { 2305 Tabs({ barPosition: BarPosition.Start, controller: this.tabsController }) { 2306 ForEach(this.list, (index: number) =>{ 2307 TabContent().tabBar(this.tabBuilder(index, '页签 ' + this.list[index])) 2308 }) 2309 } 2310 .onTabBarClick((index: number) => { 2311 this.currentIndex = index 2312 this.swiperController.changeIndex(index, true) 2313 }) 2314 .barMode(BarMode.Scrollable) 2315 .backgroundColor('#F1F3F5') 2316 .height(56) 2317 .width('100%') 2318 2319 Swiper(this.swiperController) { 2320 LazyForEach(this.swiperData, (item: string) => { 2321 Text(item.toString()) 2322 .onAppear(()=>{ 2323 console.info('onAppear ' + item.toString()) 2324 }) 2325 .onDisAppear(()=>{ 2326 console.info('onDisAppear ' + item.toString()) 2327 }) 2328 .width('100%') 2329 .height('40%') 2330 .backgroundColor(0xAFEEEE) 2331 .textAlign(TextAlign.Center) 2332 .fontSize(30) 2333 }, (item: string) => item) 2334 } 2335 .loop(false) 2336 .onSelected((index: number) => { 2337 console.info("onSelected:" + index) 2338 this.currentIndex = index; 2339 this.tabsController.changeIndex(index) 2340 }) 2341 } 2342 } 2343} 2344``` 2345 2346 2347### 示例8（滑动行为拦截事件） 2348 2349本示例通过onContentWillScroll事件实现了单方向的滑动翻页，即只能滑动向前翻页，滑动向后翻页的行为会被拦截。 2350 2351```ts 2352// xxx.ets 2353class MyDataSource implements IDataSource { 2354 private list: number[] = [] 2355 2356 constructor(list: number[]) { 2357 this.list = list 2358 } 2359 2360 totalCount(): number { 2361 return this.list.length 2362 } 2363 2364 getData(index: number): number { 2365 return this.list[index] 2366 } 2367 2368 registerDataChangeListener(listener: DataChangeListener): void { 2369 } 2370 2371 unregisterDataChangeListener() { 2372 } 2373} 2374 2375@Entry 2376@Component 2377struct SwiperExample { 2378 private swiperController: SwiperController = new SwiperController() 2379 private data: MyDataSource = new MyDataSource([]) 2380 private currentIndex: number = 4 2381 2382 aboutToAppear(): void { 2383 let list: number[] = [] 2384 for (let i = 1; i <= 10; i++) { 2385 list.push(i); 2386 } 2387 this.data = new MyDataSource(list) 2388 } 2389 2390 build() { 2391 Column({ space: 5 }) { 2392 Swiper(this.swiperController) { 2393 LazyForEach(this.data, (item: string) => { 2394 Text(item.toString()) 2395 .width('90%') 2396 .height(160) 2397 .backgroundColor(0xAFEEEE) 2398 .textAlign(TextAlign.Center) 2399 .fontSize(30) 2400 }, (item: string) => item) 2401 } 2402 .index(this.currentIndex) 2403 .loop(false) 2404 .onChange((index: number) => { 2405 this.currentIndex = index 2406 }) 2407 .onContentWillScroll((result: SwiperContentWillScrollResult) => { 2408 if (result.comingIndex > this.currentIndex) { 2409 return false; 2410 } 2411 return true; 2412 }) 2413 2414 Row({ space: 12 }) { 2415 Button('showNext') 2416 .onClick(() => { 2417 this.swiperController.showNext() 2418 }) 2419 Button('showPrevious') 2420 .onClick(() => { 2421 this.swiperController.showPrevious() 2422 }) 2423 }.margin(5) 2424 }.width('100%') 2425 .margin({ top: 5 }) 2426 } 2427} 2428``` 2429
