• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 创建轮播 (Swiper)
2
3
4[Swiper](../reference/apis-arkui/arkui-ts/ts-container-swiper.md)组件提供滑动轮播显示的能力。Swiper本身是一个容器组件，当设置了多个子组件后，可以对这些子组件进行轮播显示。通常，在一些应用首页显示推荐的内容时，需要用到轮播显示的能力。
5
6针对复杂页面场景，可以使用 Swiper 组件的预加载机制，利用主线程的空闲时间来提前构建和布局绘制组件，优化滑动体验。详细指导见[Swiper高性能开发指导](../performance/swiper_optimization.md)。
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
23...
24private swiperController: SwiperController = new SwiperController()
25...
26Swiper(this.swiperController) {
27  Text('0')
28    .width('90%')
29    .height('100%')
30    .backgroundColor(Color.Gray)
31    .textAlign(TextAlign.Center)
32    .fontSize(30)
33
34  Text('1')
35    .width('90%')
36    .height('100%')
37    .backgroundColor(Color.Green)
38    .textAlign(TextAlign.Center)
39    .fontSize(30)
40
41  Text('2')
42    .width('90%')
43    .height('100%')
44    .backgroundColor(Color.Pink)
45    .textAlign(TextAlign.Center)
46    .fontSize(30)
47}
48.loop(true)
49```
50
51![loop_true](figures/loop_true.gif)
52
53- loop为false
54
55```ts
56Swiper(this.swiperController) {
57  Text('0')
58    .width('90%')
59    .height('100%')
60    .backgroundColor(Color.Gray)
61    .textAlign(TextAlign.Center)
62    .fontSize(30)
63
64  Text('1')
65    .width('90%')
66    .height('100%')
67    .backgroundColor(Color.Green)
68    .textAlign(TextAlign.Center)
69    .fontSize(30)
70
71  Text('2')
72    .width('90%')
73    .height('100%')
74    .backgroundColor(Color.Pink)
75    .textAlign(TextAlign.Center)
76    .fontSize(30)
77}
78.loop(false)
79```
80
81![loop_false](figures/loop_false.gif)
82
83
84## 自动轮播
85
86Swiper通过设置autoPlay属性，控制是否自动轮播子组件。该属性默认值为false。
87
88autoPlay为true时，会自动切换播放子组件，子组件与子组件之间的播放间隔通过interval属性设置。interval属性默认值为3000，单位毫秒。
89
90```ts
91Swiper(this.swiperController) {
92  Text('0')
93    .width('90%')
94    .height('100%')
95    .backgroundColor(Color.Gray)
96    .textAlign(TextAlign.Center)
97    .fontSize(30)
98
99  Text('1')
100    .width('90%')
101    .height('100%')
102    .backgroundColor(Color.Green)
103    .textAlign(TextAlign.Center)
104    .fontSize(30)
105
106  Text('2')
107    .width('90%')
108    .height('100%')
109    .backgroundColor(Color.Pink)
110    .textAlign(TextAlign.Center)
111    .fontSize(30)
112}
113.loop(true)
114.autoPlay(true)
115.interval(1000)
116```
117
118![autoPlay](figures/autoPlay.gif)
119
120
121## 导航点样式
122
123Swiper提供了默认的导航点样式，导航点默认显示在Swiper下方居中位置，开发者也可以通过indicatorStyle属性自定义导航点的位置和样式。
124
125通过indicatorStyle属性，开发者可以设置导航点相对于Swiper组件上下左右四个方位的位置，同时也可以设置每个导航点的尺寸、颜色、蒙层和被选中导航点的颜色。
126
127- 导航点使用默认样式
128
129```ts
130Swiper(this.swiperController) {
131  Text('0')
132    .width('90%')
133    .height('100%')
134    .backgroundColor(Color.Gray)
135    .textAlign(TextAlign.Center)
136    .fontSize(30)
137
138  Text('1')
139    .width('90%')
140    .height('100%')
141    .backgroundColor(Color.Green)
142    .textAlign(TextAlign.Center)
143    .fontSize(30)
144
145  Text('2')
146    .width('90%')
147    .height('100%')
148    .backgroundColor(Color.Pink)
149    .textAlign(TextAlign.Center)
150    .fontSize(30)
151}
152```
153
154![indicator](figures/indicator.PNG)
155
156- 自定义导航点样式
157
158导航点直径设为30vp，左边距为0，导航点颜色设为红色。
159
160```ts
161Swiper(this.swiperController) {
162  Text('0')
163    .width('90%')
164    .height('100%')
165    .backgroundColor(Color.Gray)
166    .textAlign(TextAlign.Center)
167    .fontSize(30)
168
169  Text('1')
170    .width('90%')
171    .height('100%')
172    .backgroundColor(Color.Green)
173    .textAlign(TextAlign.Center)
174    .fontSize(30)
175
176  Text('2')
177    .width('90%')
178    .height('100%')
179    .backgroundColor(Color.Pink)
180    .textAlign(TextAlign.Center)
181    .fontSize(30)
182}
183.indicator(
184  Indicator.dot()
185    .left(0)
186    .itemWidth(15)
187    .itemHeight(15)
188    .selectedItemWidth(30)
189    .selectedItemHeight(15)
190    .color(Color.Red)
191    .selectedColor(Color.Blue)
192)
193```
194
195![ind](figures/ind.PNG)
196
197
198## 页面切换方式
199
200Swiper支持手指滑动、点击导航点和通过控制器三种方式切换页面，以下示例展示通过控制器切换页面的方法。
201
202```ts
203@Entry
204@Component
205struct SwiperDemo {
206  private swiperController: SwiperController = new SwiperController();
207
208  build() {
209    Column({ space: 5 }) {
210      Swiper(this.swiperController) {
211        Text('0')
212          .width(250)
213          .height(250)
214          .backgroundColor(Color.Gray)
215          .textAlign(TextAlign.Center)
216          .fontSize(30)
217        Text('1')
218          .width(250)
219          .height(250)
220          .backgroundColor(Color.Green)
221          .textAlign(TextAlign.Center)
222          .fontSize(30)
223        Text('2')
224          .width(250)
225          .height(250)
226          .backgroundColor(Color.Pink)
227          .textAlign(TextAlign.Center)
228          .fontSize(30)
229      }
230      .indicator(true)
231
232      Row({ space: 12 }) {
233        Button('showNext')
234          .onClick(() => {
235            this.swiperController.showNext(); // 通过controller切换到后一页
236          })
237        Button('showPrevious')
238          .onClick(() => {
239            this.swiperController.showPrevious(); // 通过controller切换到前一页
240          })
241      }.margin(5)
242    }.width('100%')
243    .margin({ top: 5 })
244  }
245}
246```
247
248![controll](figures/controll.gif)
249
250
251## 轮播方向
252
253Swiper支持水平和垂直方向上进行轮播，主要通过vertical属性控制。
254
255当vertical为true时，表示在垂直方向上进行轮播；为false时，表示在水平方向上进行轮播。vertical默认值为false。
256
257
258- 设置水平方向上轮播。
259
260```ts
261Swiper(this.swiperController) {
262  ...
263}
264.indicator(true)
265.vertical(false)
266```
267
268
269![截图2](figures/截图2.PNG)
270
271
272- 设置垂直方向轮播。
273
274```ts
275Swiper(this.swiperController) {
276  ...
277}
278.indicator(true)
279.vertical(true)
280```
281
282
283![截图3](figures/截图3.PNG)
284
285
286## 每页显示多个子页面
287
288Swiper支持在一个页面内同时显示多个子组件，通过[displayCount](../reference/apis-arkui/arkui-ts/ts-container-swiper.md#属性)属性设置。
289
290```ts
291Swiper(this.swiperController) {
292  Text('0')
293    .width(250)
294    .height(250)
295    .backgroundColor(Color.Gray)
296    .textAlign(TextAlign.Center)
297    .fontSize(30)
298  Text('1')
299    .width(250)
300    .height(250)
301    .backgroundColor(Color.Green)
302    .textAlign(TextAlign.Center)
303    .fontSize(30)
304  Text('2')
305    .width(250)
306    .height(250)
307    .backgroundColor(Color.Pink)
308    .textAlign(TextAlign.Center)
309    .fontSize(30)
310  Text('3')
311    .width(250)
312    .height(250)
313    .backgroundColor(Color.Blue)
314    .textAlign(TextAlign.Center)
315    .fontSize(30)
316}
317.indicator(true)
318.displayCount(2)
319```
320
321![two](figures/two.PNG)
322
323## 相关实例
324
325针对Swiper组件开发，有以下相关实例可供参考：
326
327- [电子相册（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/ETSUI/ElectronicAlbum)
328
329- [Swiper的使用（ArkTS）（API9）](https://gitee.com/openharmony/codelabs/tree/master/ETSUI/SwiperArkTS)