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