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