• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ArcList
2
3<!--Kit: ArkUI-->
4<!--Subsystem: ArkUI-->
5<!--Owner: @yylong-->
6<!--Designer: @yylong-->
7<!--Tester: @liuzhenshuo-->
8<!--Adviser: @HelloCrease-->
9
10弧形列表包含一系列列表项。适合连续、多行呈现同类数据，例如图片和文本。
11
12> **说明：**
13>
14> 该组件从API version 18开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
15
16
17## 导入模块
18
19```ts
20import { ArcList, ArcListAttribute } from '@kit.ArkUI';
21```
22
23## 子组件
24
25仅支持[ArcListItem](ts-container-arclistitem.md)子组件。
26
27> **说明：**
28>
29> ArcList的子组件索引值计算规则：
30>
31> - 按子组件的顺序依次递增。
32>
33> - [if/else](../../../ui/state-management/arkts-rendering-control-ifelse.md)语句中，只有条件成立的分支内的子组件会参与索引值计算，条件不成立的分支内子组件不计算索引值。
34>
35> - [ForEach](../../../ui/state-management/arkts-rendering-control-foreach.md)/[LazyForEach](../../../ui/state-management/arkts-rendering-control-lazyforeach.md)语句中，会计算展开所有子节点索引值。
36>
37> - [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)发生变化以后，会更新子节点索引值。
38>
39> - ArcList子组件[visibility](ts-universal-attributes-visibility.md#visibility)属性设置为Hidden或None依然会计算索引值。
40
41
42## 接口
43
44ArcList(options?: ArkListOptions)
45
46创建弧形列表实例，传入弧形列表配置项参数。
47
48**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
49
50**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
51
52**参数：**
53
54| 参数名  | 类型                                  | 必填 | 说明                |
55| ------- | ----------------------------------------- | ---- | ----------------------- |
56| options | [ArkListOptions](#arklistoptions) | 否   | 为ArcList提供可选参数。 |
57
58## 属性
59
60除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性：
61
62### digitalCrownSensitivity
63
64digitalCrownSensitivity(sensitivity: Optional\<CrownSensitivity>)
65
66设置表冠响应事件灵敏度。
67
68**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
69
70**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
71
72**参数：**
73
74| 参数名      | 类型                                                         | 必填 | 说明                                                         |
75| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
76| sensitivity | [Optional&lt;CrownSensitivity&gt;](ts-appendix-enums.md#crownsensitivity18) | 是   | 表冠响应灵敏度。<br/>默认值：CrownSensitivity.MEDIUM，响应速度适中。 |
77
78### space
79
80space(space: Optional\<LengthMetrics>)
81
82设置列表子项之间的距离。
83
84**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
85
86**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
87
88**参数：**
89
90| 参数名 | 类型                                                         | 必填 | 说明                               |
91| ------ | ------------------------------------------------------------ | ---- | ---------------------------------- |
92| space  | [Optional&lt;LengthMetrics&gt;](../js-apis-arkui-graphics.md#lengthmetrics12) | 是   | 列表子项之间的间距。<br/>默认值：0<br/>ArcList子组件的[visibility](ts-universal-attributes-visibility.md#visibility)属性设置为None时不显示，但该子组件上下的space还会生效。 |
93
94### scrollBar
95
96scrollBar(status: Optional\<BarState>)
97
98设置滚动条状态。
99
100**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
101
102**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
103
104**参数：**
105
106| 参数名 | 类型                                                 | 必填 | 说明                                     |
107| ------ | ---------------------------------------------------- | ---- | ---------------------------------------- |
108| status | [Optional\<BarState>](ts-appendix-enums.md#barstate) | 是   | 滚动条状态。<br/>默认值：BarState.Auto |
109
110### cachedCount
111
112cachedCount(count: Optional\<number>)
113
114设置列表中ArcListItem的预加载数量，懒加载场景只会预加载ArcList显示区域外cachedCount的内容，非懒加载场景会全部加载。懒加载、非懒加载都只布局ArcList显示区域+ArcList显示区域外cachedCount的内容。
115
116ArcList设置cachedCount后，显示区域外上下各会预加载并布局cachedCount行ArcListItem。
117
118**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
119
120**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
121
122**参数：**
123
124| 参数名 | 类型              | 必填 | 说明                                       |
125| ------ | ----------------- | ---- | ------------------------------------------ |
126| count  | Optional\<number> | 是   | ArcListItem的预加载数量。<br/>默认值：根据屏幕内显示的节点个数设置，最大值为16。<br/>取值范围：[0, +∞) |
127
128### chainAnimation
129
130chainAnimation(enable: Optional\<boolean>)
131
132设置当前ArcList是否启用链式联动动效，开启后列表滑动以及顶部和底部拖拽时会有链式联动的效果。
133
134链式联动效果：ArcList内的ArcListItem间隔一定距离，在基本的滑动交互行为下，主动对象驱动从动对象进行联动，驱动效果遵循弹簧物理动效。
135
136链式动效生效需要满足前提条件：ArcList边缘效果为[EdgeEffect.Spring](ts-appendix-enums.md#edgeeffect)类型。
137
138**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
139
140**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
141
142**参数：**
143
144| 参数名 | 类型               | 必填 | 说明                                                         |
145| ------ | ------------------ | ---- | ------------------------------------------------------------ |
146| enable | Optional\<boolean> | 是   | 是否启用链式联动动效。<br/>默认值：false，不启用链式联动。true，启用链式联动。 |
147
148### enableScrollInteraction
149
150enableScrollInteraction(enable: Optional\<boolean>)
151
152设置是否支持滚动手势。
153
154**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
155
156**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
157
158**参数：**
159
160| 参数名 | 类型               | 必填 | 说明                                |
161| ------ | ------------------ | ---- | ----------------------------------- |
162| enable | Optional\<boolean> | 是   | 是否支持滚动手势。设置为true时可以通过手指或者鼠标滚动，设置为false时无法通过手指或者鼠标滚动，但不影响控制器[Scroller](ts-container-scroll.md#scroller)的滚动接口。<br/>默认值：true |
163
164### fadingEdge
165
166fadingEdge(enable: Optional&lt;boolean&gt;)
167
168设置是否开启边缘渐隐效果。
169
170**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
171
172**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
173
174**参数：**
175
176| 参数名  | 类型                                              | 必填 | 说明                                                         |
177| ------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
178| enable | Optional&lt;boolean&gt;                           | 是   | fadingEdge生效时，会覆盖原组件的.overlay()属性。<br/>fadingEdge生效时，建议不在该组件上设置background相关属性，会影响渐隐的显示效果。<br/>fadingEdge生效时，组件会裁剪到边界，设置组件的clip属性为false不生效。<br/>设置为true时开启边缘渐隐效果，设置为false时不开启边缘渐隐效果。<br/>默认值：false |
179
180### friction
181
182friction(friction: Optional\<number>)
183
184设置摩擦系数，手动划动滚动区域时生效，仅影响惯性滚动过程，对惯性滚动过程中的链式效果有间接影响。设置为小于等于0的值时，按默认值处理。
185
186**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
187
188**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
189
190**参数：**
191
192| 参数名   | 类型              | 必填 | 说明                         |
193| -------- | ----------------- | ---- | ---------------------------- |
194| friction | Optional\<number> | 是   | 摩擦系数。<br/>默认值：0.8<br/>取值范围：(0, +∞) |
195
196### scrollBarWidth
197
198scrollBarWidth(width: Optional\<LengthMetrics>)
199
200设置滚动条的宽度。宽度设置后，滚动条按压状态宽度为设置的宽度值。
201
202**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
203
204**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
205
206**参数：**
207
208| 参数名 | 类型                                                         | 必填 | 说明                                                        |
209| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- |
210| width  | [Optional&lt;LengthMetrics&gt;](../js-apis-arkui-graphics.md#lengthmetrics12) | 是   | 滚动条的宽度。<br/>默认值：24<br/>最小值：4<br />单位：vp |
211
212### scrollBarColor
213
214scrollBarColor(color: Optional\<ColorMetrics>)
215
216设置滚动条的颜色。
217
218**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
219
220**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
221
222**参数：**
223
224| 参数名 | 类型                                                         | 必填 | 说明                                     |
225| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------- |
226| color  | [Optional\<ColorMetrics>](../js-apis-arkui-graphics.md#colormetrics12) | 是   | 设置滚动条颜色。<br />默认值：0xA9FFFFFF |
227
228### flingSpeedLimit
229
230flingSpeedLimit(speed: Optional\<number>)
231
232限制跟手滑动结束后，惯性滚动动效开始时的最大初始速度。设置为小于等于0的值时，按默认值处理。
233
234**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
235
236**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
237
238**参数：**
239
240| 参数名 | 类型              | 必填 | 说明                            |
241| ------ | ----------------- | ---- | ------------------------------- |
242| speed  | Optional\<number> | 是   | 惯性滚动动效开始时的最大初始速度。<br/>默认值：9000<br/>单位：vp/s<br />取值范围：(0, +∞) |
243
244### childrenMainSize
245
246childrenMainSize(size: Optional\<ChildrenMainSize>)
247
248设置ArcList组件的子组件在主轴方向的大小信息。
249
250**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
251
252**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
253
254**参数：**
255
256| 参数名 | 类型                                                         | 必填 | 说明                                                         |
257| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
258| size   | [Optional\<ChildrenMainSize>](ts-container-scrollable-common.md#childrenmainsize12对象说明) | 是   | 通过[ChildrenMainSize](ts-container-scrollable-common.md#childrenmainsize12对象说明)对象向ArcList组件精确提供所有子组件在主轴方向的大小信息，能够确保ArcList组件在子组件主轴尺寸不统一、子组件的增删变动、以及使用[scrollToIndex](ts-container-scroll.md#scrolltoindex)等场景时，仍能保持其滑动位置的准确性。进而保证了[scrollTo](ts-container-scroll.md#scrollto)能够精准跳转至指定位置，[currentOffset](ts-container-scroll.md#currentoffset)准确反映当前的滑动位置，且内置滚动条能够实现平滑移动，避免任何跳跃或突变。<br/> **说明：** <br/>提供的主轴方向大小必须与子组件实际在主轴方向的大小一致，子组件在主轴方向大小发生变化或进行增删操作时，必须通过调用ChildrenMainSize对象的方法来及时通知ArcList组件。 |
259
260## 事件
261
262### onScrollIndex
263
264onScrollIndex(handler: Optional\<ArcScrollIndexHandler>)
265
266当子组件划入或划出ArcList的显示区域时，将触发此事件。在ArcList初始化时，此事件会被触发一次。当ArcList显示区域内的首个或末个子组件的索引值发生变化，或是显示区域中心的子组件发生变动时，同样会触发此事件。
267
268ArcList的边缘效果为弹簧效果时，在ArcList划动到边缘继续划动和松手回弹过程不会触发onScrollIndex事件。
269
270**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
271
272**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
273
274**参数：**
275
276| 参数名  | 类型                                                         | 必填 | 说明                                            |
277| ------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- |
278| handler | [Optional\<ArcScrollIndexHandler>](#arcscrollindexhandler) | 是   | 有子组件划入或划出ArcList显示区域时触发该回调。 |
279
280### onReachStart
281
282onReachStart(handler: Optional\<VoidCallback>)
283
284列表到达起始位置时触发。
285
286当ArcList进行初始化时，若[initialIndex](#arklistoptions)设定为0，将触发一次事件。当ArcList滚动至起始位置，亦会触发一次事件。在ArcList的边缘效果设置为弹簧效果时，滑动经过起始位置时会触发一次事件，而在回弹返回起始位置时，将再次触发一次事件。
287
288**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
289
290**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
291
292**参数：**
293
294| 参数名  | 类型                                             | 必填 | 说明                     |
295| ------- | ------------------------------------------------ | ---- | ------------------------ |
296| handler | [Optional\<VoidCallback>](ts-types.md#voidcallback12) | 是   | 列表到达起始位置时触发。 |
297
298### onReachEnd
299
300onReachEnd(handler: Optional\<VoidCallback>)
301
302列表到达末尾位置时触发。
303
304ArcList边缘效果为弹簧效果时，划动经过末尾位置时触发一次该事件，回弹回末尾位置时再触发一次该事件。
305
306**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
307
308**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
309
310**参数：**
311
312| 参数名  | 类型                                             | 必填 | 说明                     |
313| ------- | ------------------------------------------------ | ---- | ------------------------ |
314| handler | [Optional\<VoidCallback>](ts-types.md#voidcallback12) | 是   | 列表到达末尾位置时触发。 |
315
316### onScrollStart
317
318onScrollStart(handler: Optional\<VoidCallback>)
319
320列表滑动开始时触发。手指拖动列表或列表的滚动条触发的滑动开始时，会触发该事件。使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的带动画的滑动，动画开始时会触发该事件。
321
322**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
323
324**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
325
326**参数：**
327
328| 参数名  | 类型                                             | 必填 | 说明                 |
329| ------- | ------------------------------------------------ | ---- | -------------------- |
330| handler | [Optional\<VoidCallback>](ts-types.md#voidcallback12) | 是   | 列表滑动开始时触发。 |
331
332### onScrollStop
333
334onScrollStop(handler: Optional\<VoidCallback>)
335
336列表滑动停止时触发。手拖动列表或列表的滚动条触发的滑动，手离开屏幕后滑动停止时会触发该事件。使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的带动画的滑动，动画停止会触发该事件。
337
338**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
339
340**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
341
342**参数：**
343
344| 参数名  | 类型                                             | 必填 | 说明                 |
345| ------- | ------------------------------------------------ | ---- | -------------------- |
346| handler | [Optional\<VoidCallback>](ts-types.md#voidcallback12) | 是   | 列表滑动停止时触发。 |
347
348### onWillScroll
349
350onWillScroll(handler: Optional\<OnWillScrollCallback>)
351
352列表划动时每帧开始前触发，返回当前帧将要滑动的偏移量和当前滑动状态。返回的偏移量为计算得到的将要滑动的偏移量值，并非最终实际滑动偏移。
353
354**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
355
356**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
357
358**参数：**
359
360| 参数名 | 类型 | 必填 | 说明 |
361| ------ | ------ | ------ | ------|
362| handler | [Optional\<OnWillScrollCallback>](ts-container-scrollable-common.md#onwillscrollcallback12) | 是 | 列表划动时每帧开始前触发的回调。 |
363
364> **说明：**
365>
366> 调用ScrollEdge和不带动画的ScrollToIndex时，不触发onWillScroll。
367
368### onDidScroll
369onDidScroll(handler: Optional\<OnScrollCallback>)
370
371列表滑动时触发，返回当前帧滑动的偏移量和当前滑动状态。
372
373**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
374
375**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
376
377**参数：**
378
379| 参数名 | 类型 | 必填 | 说明 |
380| ------ | ------ | ------ | ------|
381| handler | [Optional\<OnScrollCallback>](ts-container-scrollable-common.md#onscrollcallback12) | 是 | 列表滑动时触发的回调。 |
382
383## ArkListOptions
384
385包含创建ArcList组件的基础参数。
386
387**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
388
389**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
390
391| 名称       | 类型                                    | 只读 | 可选 | 说明                                                     |
392| ------------ | ------------------------------------------- | ---- | --- | ------------------------------------------------------------ |
393| initialIndex | number                                      | 否   | 是 | 设置当前ArcList初次加载时视口起始位置显示的item的索引值。<br/>默认值：0<br/>**说明：** <br/>设置为负数或超过了当前ArcList最后一个item的索引值时视为无效取值，无效取值按默认值显示。 |
394| scroller     | [Scroller](ts-container-scroll.md#scroller) | 否   | 是 | 可滚动组件的控制器。用于与可滚动组件进行绑定。<br/>**说明：** <br/>不允许和其他滚动类组件，如：[ArcList](ts-container-arclist.md)、[List](ts-container-list.md)、[Grid](ts-container-grid.md)、[Scroll](ts-container-scroll.md)和[WaterFlow](ts-container-waterflow.md)绑定同一个滚动控制对象。 |
395| header       | [ComponentContent](../js-apis-arkui-ComponentContent.md)                            | 否   | 是 | 支持标题设置。                                               |
396
397## ArcScrollIndexHandler
398
399type ArcScrollIndexHandler = (start: number, end: number, center: number) => void
400
401有子组件划入或划出ArcList显示区域时触发的回调。
402
403**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。
404
405**系统能力：** SystemCapability.ArkUI.ArkUI.Circle
406
407**参数：**
408
409| 参数名 | 类型   | 必填 | 说明                                      |
410| ------ | ------ | ---- | ----------------------------------------- |
411| start  | number | 是   | ArcList显示区域内第一个子组件的索引值。   |
412| end    | number | 是   | ArcList显示区域内最后一个子组件的索引值。 |
413| center | number | 是   | ArcList显示区域内中间位置子组件的索引值。 |
414
415## 示例
416
417该示例增加了ArcList支持标题栏设置的效果，子项自动缩放显示。
418
419```ts
420// xxx.ets
421import { ComponentContent, LengthMetrics } from '@kit.ArkUI';
422import { UIContext, CircleShape } from '@kit.ArkUI';
423import { ArcList, ArcListItem, ArcListAttribute, ArcListItemAttribute } from '@kit.ArkUI';
424
425@Builder
426function buildText() {
427  Column() {
428    Text("header")
429      .fontSize('60px')
430      .fontWeight(FontWeight.Bold)
431  }.margin(0)
432}
433
434@Entry
435@Component
436struct Index {
437  @State  private numItems: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
438
439  private watchSize: string = '466px' // 手表默认宽高：466*466
440  private listSize: string = '414px' // item宽度
441
442  context: UIContext = this.getUIContext()
443  tabBar1: ComponentContent<Object> = new ComponentContent(this.context, wrapBuilder(buildText));
444
445  @Builder
446  buildList2() {
447    Stack() {
448      Column() {
449      }
450      .justifyContent(FlexAlign.Center)
451      .width(this.watchSize)
452      .height(this.watchSize)
453      .clipShape(new CircleShape({ width: '100%', height: '100%' }))
454      .backgroundColor(Color.White)
455
456      ArcList({ initialIndex: 0, header: this.tabBar1 }) {
457        ForEach(this.numItems, (item: number, index: number) => {
458          ArcListItem() {
459            Button('' + item, { type: ButtonType.Capsule })
460              .width(this.listSize)
461              .height('100px')
462              .fontSize('40px')
463              .focusable(true)
464              .focusOnTouch(true)
465              .backgroundColor(0x17A98D)
466          }.align(Alignment.Center)
467        }, (item: number, index: number) => (item + index).toString())
468      }
469      .space(LengthMetrics.px(10))
470      .borderRadius(this.watchSize)
471      .focusable(true)
472      .focusOnTouch(true)
473      .defaultFocus(true)
474    }
475    .align(Alignment.Center)
476    .width(this.watchSize)
477    .height(this.watchSize)
478    .border({color: Color.Black, width: 1})
479    .borderRadius(this.watchSize)
480  }
481
482  build() {
483    Column() {
484      this.buildList2()
485    }
486    .width('100%')
487    .height('100%')
488    .alignItems(HorizontalAlign.Center)
489    .justifyContent(FlexAlign.Center)
490  }
491}
492```
493
494![arkts-arclist](figures/arkts-arclist.png)