1# 创建轮播 (Swiper)
2
3
4[Swiper](../reference/apis-arkui/arkui-ts/ts-container-swiper.md)组件提供滑动轮播显示的能力。Swiper本身是一个容器组件，当设置了多个子组件后，可以对这些子组件进行轮播显示。通常，在一些应用首页显示推荐的内容时，需要用到轮播显示的能力。
5
6针对复杂页面场景，可以使用 Swiper 组件的预加载机制，利用主线程的空闲时间来提前构建和布局绘制组件，优化滑动体验。<!--Del-->详细指导见[Swiper高性能开发指导](../performance/swiper_optimization.md)。<!--DelEnd-->
7
8
9## 布局与约束
10
11Swiper作为一个容器组件，如果设置了自身尺寸属性，则在轮播显示过程中均以该尺寸生效。如果自身尺寸属性未被设置，则分两种情况：如果设置了prevMargin或者nextMargin属性，则Swiper自身尺寸会跟随其父组件；如果未设置prevMargin或者nextMargin属性，则会自动根据子组件的大小设置自身的尺寸。
12
13
14## 循环播放
15
16通过loop属性控制是否循环播放，该属性默认值为true。
17
18当loop为true时，在显示第一页或最后一页时，可以继续往前切换到前一页或者往后切换到后一页。如果loop为false，则在第一页或最后一页时，无法继续向前或者向后切换页面。
19
20- loop为true
21
22```ts
23Swiper() {
24  Text('0')
25    .width('90%')
26    .height('100%')
27    .backgroundColor(Color.Gray)
28    .textAlign(TextAlign.Center)
29    .fontSize(30)
30
31  Text('1')
32    .width('90%')
33    .height('100%')
34    .backgroundColor(Color.Green)
35    .textAlign(TextAlign.Center)
36    .fontSize(30)
37
38  Text('2')
39    .width('90%')
40    .height('100%')
41    .backgroundColor(Color.Pink)
42    .textAlign(TextAlign.Center)
43    .fontSize(30)
44}
45.loop(true)
46```
47
48![loop_true](figures/loop_true.gif)
49
50- loop为false
51
52```ts
53Swiper() {
54  // ...
55}
56.loop(false)
57```
58
59![loop_false](figures/loop_false.gif)
60
61
62## 自动轮播
63
64Swiper通过设置autoPlay属性，控制是否自动轮播子组件。该属性默认值为false。
65
66autoPlay为true时，会自动切换播放子组件，子组件与子组件之间的播放间隔通过interval属性设置。interval属性默认值为3000，单位毫秒。
67
68```ts
69Swiper() {
70  // ...
71}
72.loop(true)
73.autoPlay(true)
74.interval(1000)
75```
76
77![autoPlay](figures/autoPlay.gif)
78
79
80## 导航点样式
81
82Swiper提供了默认的导航点样式和导航点箭头样式，导航点默认显示在Swiper下方居中位置，开发者也可以通过indicator属性自定义导航点的位置和样式，导航点箭头默认不显示。
83
84通过indicator属性，开发者可以设置导航点相对于Swiper组件上下左右四个方位的位置，同时也可以设置每个导航点的尺寸、颜色、蒙层和被选中导航点的颜色。
85
86- 导航点使用默认样式
87
88```ts
89Swiper() {
90  Text('0')
91    .width('90%')
92    .height('100%')
93    .backgroundColor(Color.Gray)
94    .textAlign(TextAlign.Center)
95    .fontSize(30)
96
97  Text('1')
98    .width('90%')
99    .height('100%')
100    .backgroundColor(Color.Green)
101    .textAlign(TextAlign.Center)
102    .fontSize(30)
103
104  Text('2')
105    .width('90%')
106    .height('100%')
107    .backgroundColor(Color.Pink)
108    .textAlign(TextAlign.Center)
109    .fontSize(30)
110}
111```
112
113![indicator](figures/indicator.PNG)
114
115- 自定义导航点样式
116
117导航点直径设为30vp，左边距为0，导航点颜色设为红色。
118
119```ts
120Swiper() {
121  // ...
122}
123.indicator(
124  Indicator.dot()
125    .left(0)
126    .itemWidth(15)
127    .itemHeight(15)
128    .selectedItemWidth(30)
129    .selectedItemHeight(15)
130    .color(Color.Red)
131    .selectedColor(Color.Blue)
132)
133```
134
135![ind](figures/ind.PNG)
136
137Swiper通过设置[displayArrow](../reference/apis-arkui/arkui-ts/ts-container-swiper.md#displayarrow10)属性，可以控制导航点箭头的大小、位置、颜色，底板的大小及颜色，以及鼠标悬停时是否显示箭头。
138
139- 箭头使用默认样式
140
141```ts
142Swiper() {
143  // ...
144}
145.displayArrow(true, false)
146```
147
148![arrow1](figures/arrow1.gif)
149
150- 自定义箭头样式
151
152箭头显示在组件两侧，大小为18vp，导航点箭头颜色设为蓝色。
153
154```ts
155Swiper() {
156  // ...
157}
158.displayArrow({
159  showBackground: true,
160  isSidebarMiddle: true,
161  backgroundSize: 24,
162  backgroundColor: Color.White,
163  arrowSize: 18,
164  arrowColor: Color.Blue
165  }, false)
166```
167
168![arrow2](figures/arrow2.gif)
169
170## 页面切换方式
171
172Swiper支持手指滑动、点击导航点和通过控制器三种方式切换页面，以下示例展示通过控制器切换页面的方法。
173
174```ts
175@Entry
176@Component
177struct SwiperDemo {
178  private swiperController: SwiperController = new SwiperController();
179
180  build() {
181    Column({ space: 5 }) {
182      Swiper(this.swiperController) {
183        Text('0')
184          .width(250)
185          .height(250)
186          .backgroundColor(Color.Gray)
187          .textAlign(TextAlign.Center)
188          .fontSize(30)
189        Text('1')
190          .width(250)
191          .height(250)
192          .backgroundColor(Color.Green)
193          .textAlign(TextAlign.Center)
194          .fontSize(30)
195        Text('2')
196          .width(250)
197          .height(250)
198          .backgroundColor(Color.Pink)
199          .textAlign(TextAlign.Center)
200          .fontSize(30)
201      }
202      .indicator(true)
203
204      Row({ space: 12 }) {
205        Button('showNext')
206          .onClick(() => {
207            this.swiperController.showNext(); // 通过controller切换到后一页
208          })
209        Button('showPrevious')
210          .onClick(() => {
211            this.swiperController.showPrevious(); // 通过controller切换到前一页
212          })
213      }.margin(5)
214    }.width('100%')
215    .margin({ top: 5 })
216  }
217}
218```
219
220![controll](figures/controll.gif)
221
222
223## 轮播方向
224
225Swiper支持水平和垂直方向上进行轮播，主要通过vertical属性控制。
226
227当vertical为true时，表示在垂直方向上进行轮播；为false时，表示在水平方向上进行轮播。vertical默认值为false。
228
229
230- 设置水平方向上轮播。
231
232```ts
233Swiper() {
234  // ...
235}
236.indicator(true)
237.vertical(false)
238```
239
240
241![截图2](figures/截图2.PNG)
242
243
244- 设置垂直方向轮播。
245
246```ts
247Swiper() {
248  // ...
249}
250.indicator(true)
251.vertical(true)
252```
253
254
255![截图3](figures/截图3.PNG)
256
257
258## 每页显示多个子页面
259
260Swiper支持在一个页面内同时显示多个子组件，通过[displayCount](../reference/apis-arkui/arkui-ts/ts-container-swiper.md#displaycount8)属性设置。
261
262```ts
263Swiper() {
264  Text('0')
265    .width(250)
266    .height(250)
267    .backgroundColor(Color.Gray)
268    .textAlign(TextAlign.Center)
269    .fontSize(30)
270  Text('1')
271    .width(250)
272    .height(250)
273    .backgroundColor(Color.Green)
274    .textAlign(TextAlign.Center)
275    .fontSize(30)
276  Text('2')
277    .width(250)
278    .height(250)
279    .backgroundColor(Color.Pink)
280    .textAlign(TextAlign.Center)
281    .fontSize(30)
282  Text('3')
283    .width(250)
284    .height(250)
285    .backgroundColor(Color.Blue)
286    .textAlign(TextAlign.Center)
287    .fontSize(30)
288}
289.indicator(true)
290.displayCount(2)
291```
292
293![two](figures/two.PNG)
294
295## 自定义切换动画
296
297Swiper支持通过[customContentTransition](../reference/apis-arkui/arkui-ts/ts-container-swiper.md#customcontenttransition12)设置自定义切换动画，可以在回调中对视窗内所有页面逐帧设置透明度、缩放比例、位移、渲染层级等属性实现自定义切换动画。
298
299```ts
300@Entry
301@Component
302struct SwiperCustomAnimationExample {
303  private DISPLAY_COUNT: number = 2
304  private MIN_SCALE: number = 0.75
305
306  @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange]
307  @State opacityList: number[] = []
308  @State scaleList: number[] = []
309  @State translateList: number[] = []
310  @State zIndexList: number[] = []
311
312  aboutToAppear(): void {
313    for (let i = 0; i < this.backgroundColors.length; i++) {
314      this.opacityList.push(1.0)
315      this.scaleList.push(1.0)
316      this.translateList.push(0.0)
317      this.zIndexList.push(0)
318    }
319  }
320
321  build() {
322    Column() {
323      Swiper() {
324        ForEach(this.backgroundColors, (backgroundColor: Color, index: number) => {
325          Text(index.toString()).width('100%').height('100%').fontSize(50).textAlign(TextAlign.Center)
326            .backgroundColor(backgroundColor)
327            .opacity(this.opacityList[index])
328            .scale({ x: this.scaleList[index], y: this.scaleList[index] })
329            .translate({ x: this.translateList[index] })
330            .zIndex(this.zIndexList[index])
331        })
332      }
333      .height(300)
334      .indicator(false)
335      .displayCount(this.DISPLAY_COUNT, true)
336      .customContentTransition({
337        timeout: 1000,
338        transition: (proxy: SwiperContentTransitionProxy) => {
339          if (proxy.position <= proxy.index % this.DISPLAY_COUNT || proxy.position >= this.DISPLAY_COUNT + proxy.index % this.DISPLAY_COUNT) {
340            // 同组页面完全滑出视窗外时，重置属性值
341            this.opacityList[proxy.index] = 1.0
342            this.scaleList[proxy.index] = 1.0
343            this.translateList[proxy.index] = 0.0
344            this.zIndexList[proxy.index] = 0
345          } else {
346            // 同组页面未滑出视窗外时，对同组中左右两个页面，逐帧根据position修改属性值
347            if (proxy.index % this.DISPLAY_COUNT === 0) {
348              this.opacityList[proxy.index] = 1 - proxy.position / this.DISPLAY_COUNT
349              this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - proxy.position / this.DISPLAY_COUNT)
350              this.translateList[proxy.index] = - proxy.position * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0
351            } else {
352              this.opacityList[proxy.index] = 1 - (proxy.position - 1) / this.DISPLAY_COUNT
353              this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - (proxy.position - 1) / this.DISPLAY_COUNT)
354              this.translateList[proxy.index] = - (proxy.position - 1) * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0
355            }
356            this.zIndexList[proxy.index] = -1
357          }
358        }
359      })
360    }.width('100%')
361  }
362}
363```
364
365![customAnimation](figures/swiper-custom-animation.gif)
366
367## 相关实例
368
369针对Swiper组件开发，有以下相关实例可供参考：
370
371- [电子相册（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/ETSUI/ElectronicAlbum)
372
373- [Swiper的使用（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/ETSUI/SwiperArkTS)
374<!--RP1--><!--RP1End-->