1# ArcList 2 3The **ArcList** component is a circular layout container that displays a series of list items in an arc shape. It is suitable for presenting homogeneous data, such as images and text, in a continuous, multi-row format. 4 5> **NOTE** 6> 7> This component is supported since API version 18. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12```ts 13import { ArcList, ArcListAttribute } from '@kit.ArkUI'; 14``` 15 16## Child Components 17 18Only the [ArcListItem](ts-container-arclistitem.md) component is supported. 19 20> **NOTE** 21> 22> Below are the rules for calculating the indexes of the child components of **ArcList**: 23> 24> - The index increases in ascending order of child components. 25> 26> - In the [if/else](../../../quick-start/arkts-rendering-control-ifelse.md) statement, only the child components for which the condition evaluates to true participate in the index calculation. 27> 28> - In the [ForEach](../../../quick-start/arkts-rendering-control-foreach.md) or [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md) statement, the indexes of all expanded subnodes are calculated. 29> 30> - If the values of [if/else](../../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md) change, the indexes of subnodes are updated. 31> 32> - Child components of **ArcList** whose [visibility](ts-universal-attributes-visibility.md#visibility) attribute is set to **Hidden** or **None** are still included in the index calculation. 33 34 35## APIs 36 37ArcList(options?: ArkListOptions) 38 39Creates an instance of the **ArcList** component with optional configuration parameters. 40 41**Atomic service API**: This API can be used in atomic services since API version 18. 42 43**System capability**: SystemCapability.ArkUI.ArkUI.Circle 44 45**Parameters** 46 47| Name | Type | Mandatory| Description | 48| ------- | ----------------------------------------- | ---- | ----------------------- | 49| options | [ArkListOptions](#arklistoptions) | No | Parameters for configuring the **ArcList**.| 50 51## Attributes 52 53In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 54 55### digitalCrownSensitivity 56 57digitalCrownSensitivity(sensitivity: Optional\<CrownSensitivity>) 58 59Sets the sensitivity of the digital crown's response to events. 60 61**Atomic service API**: This API can be used in atomic services since API version 18. 62 63**System capability**: SystemCapability.ArkUI.ArkUI.Circle 64 65**Parameters** 66 67| Name | Type | Mandatory| Description | 68| ----------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 69| sensitivity | [Optional<CrownSensitivity>](ts-appendix-enums.md#crownsensitivity18) | Yes | Sensitivity of the digital crown's response.<br>Default value: **CrownSensitivity.MEDIUM**, indicating moderate response speed| 70 71### space 72 73space(space: Optional\<LengthMetrics>) 74 75Sets the spacing between list items. 76 77**Atomic service API**: This API can be used in atomic services since API version 18. 78 79**System capability**: SystemCapability.ArkUI.ArkUI.Circle 80 81**Parameters** 82 83| Name| Type | Mandatory| Description | 84| ------ | ------------------------------------------------------------ | ---- | ---------------------------------- | 85| space | [Optional<LengthMetrics>](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Spacing between list items.<br>Default value: **0**<br>Child components of **ArcList** whose [visibility](ts-universal-attributes-visibility.md#visibility) attribute is set to **None** are not displayed, but the spacing above and below them still takes effect.| 86 87### scrollBar 88 89scrollBar(status: Optional\<BarState>) 90 91Sets the state of the scrollbar. 92 93**Atomic service API**: This API can be used in atomic services since API version 18. 94 95**System capability**: SystemCapability.ArkUI.ArkUI.Circle 96 97**Parameters** 98 99| Name| Type | Mandatory| Description | 100| ------ | ---------------------------------------------------- | ---- | ---------------------------------------- | 101| status | [Optional\<BarState>](ts-appendix-enums.md#barstate) | Yes | State of the scrollbar.<br>Default value: **BarState.Auto**| 102 103### cachedCount 104 105cachedCount(count: Optional\<number>) 106 107Sets the number of arc list items to be preloaded (cached). In a lazy loading scenario, only the content equivalent to **cachedCount** outside the visible area of the arc list is preloaded. In a non-lazy loading scenario, all items are loaded at once. For both lazy and non-lazy loading, only the content within the visible area of the arc list plus the content equivalent to **cachedCount** outside the visible area is laid out. 108 109When **cachedCount** is set for the arc list, the system preloads and lays out the **cachedCount**-specified number of rows of arc list items both above and below the currently visible area of the arc list. 110 111**Atomic service API**: This API can be used in atomic services since API version 18. 112 113**System capability**: SystemCapability.ArkUI.ArkUI.Circle 114 115**Parameters** 116 117| Name| Type | Mandatory| Description | 118| ------ | ----------------- | ---- | ------------------------------------------ | 119| count | Optional\<number> | Yes | Number of list items to preload.<br>Default value: number of nodes visible on the screen, with the maximum value of 16.<br>Value range: [0, +∞).| 120 121### chainAnimation 122 123chainAnimation(enable: Optional\<boolean>) 124 125Sets whether to enable chained animations, which provide a visually connected, or "chained," effect when the **ArcList** component is scrolled or its top or bottom edge is dragged. 126 127The list items are separated with even space, and one item animation starts after the previous animation during basic sliding interactions. The chained animation effect is similar with spring physics. 128 129For chained animations to work properly, the edge scrolling effect of the **ArcList** component must be set to [EdgeEffect.Spring](ts-appendix-enums.md#edgeeffect). 130 131**Atomic service API**: This API can be used in atomic services since API version 18. 132 133**System capability**: SystemCapability.ArkUI.ArkUI.Circle 134 135**Parameters** 136 137| Name| Type | Mandatory| Description | 138| ------ | ------------------ | ---- | ------------------------------------------------------------ | 139| enable | Optional\<boolean> | Yes | Whether to enable chained animations.<br>**false** (default): Chained animations are disabled. **true**: Chained animations are enabled.| 140 141### enableScrollInteraction 142 143enableScrollInteraction(enable: Optional\<boolean>) 144 145Sets whether to support scroll gestures. When this attribute is set to **false**, scrolling by finger or mouse is not supported, but the [Scroller](ts-container-scroll.md#scroller) controller API is not affected. 146 147**Atomic service API**: This API can be used in atomic services since API version 18. 148 149**System capability**: SystemCapability.ArkUI.ArkUI.Circle 150 151**Parameters** 152 153| Name| Type | Mandatory| Description | 154| ------ | ------------------ | ---- | ----------------------------------- | 155| enable | Optional\<boolean> | Yes | Whether to support scroll gestures.<br>Default value: **true**| 156 157### fadingEdge 158 159fadingEdge(enable: Optional<boolean>) 160 161Sets whether to enable the edge fading effect. 162 163**Atomic service API**: This API can be used in atomic services since API version 18. 164 165**System capability**: SystemCapability.ArkUI.ArkUI.Circle 166 167**Parameters** 168 169| Name | Type | Mandatory| Description | 170| ------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 171| enable | Optional<boolean> | Yes | Whether to enable the edge fading effect.<br>When **fadingEdge** is set to **true**, it overrides the **.overlay()** attribute of the component.<br>With **fadingEdge** set to **true**, avoid setting background-related attributes on the component, as this may affect the display of the fading effect.<br>With **fadingEdge** set to **true**, the component is clipped to the boundary, and setting the component's **clip** attribute to **false** will not take effect.<br>Default value: **false**, which means not to enable the edge fading effect.| 172 173### friction 174 175friction(friction: Optional\<number>) 176 177Sets the friction coefficient. It applies only to gestures in the scrolling area, and it affects only indirectly the scroll chaining during the inertial scrolling process. If this attribute is set to a value less than or equal to 0, the default value is used. 178 179**Atomic service API**: This API can be used in atomic services since API version 18. 180 181**System capability**: SystemCapability.ArkUI.ArkUI.Circle 182 183**Parameters** 184 185| Name | Type | Mandatory| Description | 186| -------- | ----------------- | ---- | ---------------------------- | 187| friction | Optional\<number> | Yes | Friction coefficient.<br>Default value: **0.8**<br>Value range: (0, +∞).| 188 189### scrollBarWidth 190 191scrollBarWidth(width: Optional\<LengthMetrics>) 192 193Sets the width of the scrollbar. Once the width is set, the scrollbar will use this width in its pressed state. 194 195**Atomic service API**: This API can be used in atomic services since API version 18. 196 197**System capability**: SystemCapability.ArkUI.ArkUI.Circle 198 199**Parameters** 200 201| Name| Type | Mandatory| Description | 202| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 203| width | [Optional<LengthMetrics>](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Width of the scrollbar.<br>Default value: **24**<br>Minimum value: 4<br>Unit: vp| 204 205### scrollBarColor 206 207scrollBarColor(color: Optional\<ColorMetrics>) 208 209Sets the color of the scrollbar. 210 211**Atomic service API**: This API can be used in atomic services since API version 18. 212 213**System capability**: SystemCapability.ArkUI.ArkUI.Circle 214 215**Parameters** 216 217| Name| Type | Mandatory| Description | 218| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------- | 219| color | [Optional\<ColorMetrics>](../js-apis-arkui-graphics.md#colormetrics12) | Yes | Color of the scrollbar.<br>Default value: **0xA9FFFFFF**| 220 221### flingSpeedLimit 222 223flingSpeedLimit(speed: Optional\<number>) 224 225Sets the maximum initial speed for inertial scrolling after a fling gesture. If this attribute is set to a value less than or equal to 0, the default value is used. 226 227**Atomic service API**: This API can be used in atomic services since API version 18. 228 229**System capability**: SystemCapability.ArkUI.ArkUI.Circle 230 231**Parameters** 232 233| Name| Type | Mandatory| Description | 234| ------ | ----------------- | ---- | ------------------------------- | 235| speed | Optional\<number> | Yes | Maximum initial speed for inertial scrolling.<br>Default value: **9000**.<br>Unit: vp/s.<br>Value range: (0, +∞).| 236 237### childrenMainSize 238 239childrenMainSize(size: Optional\<ChildrenMainSize>) 240 241Sets the size information of the child components of the **ArcList** component along the main axis. 242 243**Atomic service API**: This API can be used in atomic services since API version 18. 244 245**System capability**: SystemCapability.ArkUI.ArkUI.Circle 246 247**Parameters** 248 249| Name| Type | Mandatory| Description | 250| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 251| size | [Optional\<ChildrenMainSize>](ts-container-scrollable-common.md#childrenmainsize12) | Yes | Precise size information for all child components along the main axis. This ensures accurate scrolling positions in scenarios where child components have varying sizes, are added or removed, or when APIs like [scrollToIndex](ts-container-scroll.md#scrolltoindex) are used. It guarantees that [scrollTo](ts-container-scroll.md#scrollto) can accurately navigate to the specified position, [currentOffset](ts-container-scroll.md#currentoffset) accurately reflects the current scrolling position, and the built-in scrollbar moves smoothly without any jumps abrupt changes.<br> **NOTE**<br>The provided sizes must match the actual sizes of the child components. Any changes to the sizes, or any additions or removals of child components, must be notified to the **ArcList** component through the **ChildrenMainSize** object.| 252 253## Events 254 255### onScrollIndex 256 257onScrollIndex(handler: Optional\<ArcScrollIndexHandler>) 258 259Triggered when a child component enters or leaves the visible area of the **ArcList** component. This event is triggered during initialization of the **ArcList** component and when the index of the first or last child component in the visible area changes, or when the center child component changes. 260 261If the edge scrolling effect of the **ArcList** component is set to spring, this event is not triggered during continued scrolling at the edge or during the bounce-back process 262 263**Atomic service API**: This API can be used in atomic services since API version 18. 264 265**System capability**: SystemCapability.ArkUI.ArkUI.Circle 266 267**Parameters** 268 269| Name | Type | Mandatory| Description | 270| ------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 271| handler | [Optional\<ArcScrollIndexHandler>](#arcscrollindexhandler) | Yes | Callback triggered when a child component enters or leaves the visible area of the **ArcList** component.| 272 273### onReachStart 274 275onReachStart(handler: Optional\<VoidCallback>) 276 277Triggered when the list reaches the start position. 278 279This event is triggered during initialization of the **ArcList** component if [initialIndex](#arklistoptions) is set to **0**, and whenever the list scrolls to the start position. If the edge scrolling effect is set to spring, this event is triggered when scrolling past the start position and again when bouncing back to it. 280 281**Atomic service API**: This API can be used in atomic services since API version 18. 282 283**System capability**: SystemCapability.ArkUI.ArkUI.Circle 284 285| Name | Type | Mandatory| Description | 286| ------- | ------------------------------------------------ | ---- | ------------------------ | 287| handler | [Optional\<VoidCallback>](ts-types.md#voidcallback12) | Yes | Callback triggered when the list reaches the start position.| 288 289### onReachEnd 290 291onReachEnd(handler: Optional\<VoidCallback>) 292 293Triggered when the list reaches the end position. 294 295If the edge scrolling effect is set to spring, this event is triggered when scrolling past the end position and again when bouncing back to it. 296 297**Atomic service API**: This API can be used in atomic services since API version 18. 298 299**System capability**: SystemCapability.ArkUI.ArkUI.Circle 300 301| Name | Type | Mandatory| Description | 302| ------- | ------------------------------------------------ | ---- | ------------------------ | 303| handler | [Optional\<VoidCallback>](ts-types.md#voidcallback12) | Yes | Callback triggered when the list reaches the end position.| 304 305### onScrollStart 306 307onScrollStart(handler: Optional\<VoidCallback>) 308 309Triggered when the list starts scrolling initiated by the user's finger dragging the list or its scrollbar. This event is also triggered when the animation contained in the scrolling triggered by [Scroller](ts-container-scroll.md#scroller) starts. 310 311**Atomic service API**: This API can be used in atomic services since API version 18. 312 313**System capability**: SystemCapability.ArkUI.ArkUI.Circle 314 315| Name | Type | Mandatory| Description | 316| ------- | ------------------------------------------------ | ---- | -------------------- | 317| handler | [Optional\<VoidCallback>](ts-types.md#voidcallback12) | Yes | Callback triggered when the list starts scrolling.| 318 319### onScrollStop 320 321onScrollStop(handler: Optional\<VoidCallback>) 322 323Triggered when the list stops scrolling after the user's finger leaves the screen. This event is also triggered when the animation contained in the scrolling triggered by [Scroller](ts-container-scroll.md#scroller) stops. 324 325**Atomic service API**: This API can be used in atomic services since API version 18. 326 327**System capability**: SystemCapability.ArkUI.ArkUI.Circle 328 329| Name | Type | Mandatory| Description | 330| ------- | ------------------------------------------------ | ---- | -------------------- | 331| handler | [Optional\<VoidCallback>](ts-types.md#voidcallback12) | Yes | Callback triggered when the list stops scrolling.| 332 333### onWillScroll 334 335onWillScroll(handler: Optional\<OnWillScrollCallback>) 336 337Triggered before each frame when the list is being scrolled. The return value is the offset amount by which the list will scroll and the current scroll state. The returned offset is obtained by calculation, not the actual offset. 338 339**Atomic service API**: This API can be used in atomic services since API version 18. 340 341**System capability**: SystemCapability.ArkUI.ArkUI.Circle 342 343**Parameters** 344 345| Name| Type| Mandatory| Description| 346| ------ | ------ | ------ | ------| 347| handler | [Optional\<OnWillScrollCallback>](ts-container-scrollable-common.md#onwillscrollcallback12) | Yes| Callback triggered before each frame when the list is being scrolled.| 348 349> **NOTE** 350> 351> When **ScrollEdge** or **ScrollToIndex** that does not involve animation is called, **onWillScroll** is not triggered. 352 353### onDidScroll 354onDidScroll(handler: Optional\<OnScrollCallback>) 355 356Triggered when the list scrolls. The return value is the offset amount by which the list has scrolled and the current scroll state. 357 358**Atomic service API**: This API can be used in atomic services since API version 18. 359 360**System capability**: SystemCapability.ArkUI.ArkUI.Circle 361 362**Parameters** 363 364| Name| Type| Mandatory| Description| 365| ------ | ------ | ------ | ------| 366| handler | [Optional\<OnScrollCallback>](ts-container-scrollable-common.md#onscrollcallback12) | Yes| Callback triggered when the list scrolls.| 367 368## ArkListOptions 369 370Provides basic parameters for creating an **ArcList** component. 371 372**Atomic service API**: This API can be used in atomic services since API version 18. 373 374**System capability**: SystemCapability.ArkUI.ArkUI.Circle 375 376| Name | Type | Mandatory| Description | 377| ------------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | 378| initialIndex | number | No | Item displayed at the beginning of the viewport when the **ArcList** component is loaded for the first time, that is, the first item to be displayed.<br>Default value: **0**<br>**NOTE**<br>If the set value is a negative number or is greater than the index of the last item, the value is invalid. In this case, the default value will be used.| 379| scroller | [Scroller](ts-container-scroll.md#scroller) | No | Scroller, which can be bound to scrollable components for scrolling control.<br>**NOTE**<br>The same scroller cannot be bound to multiple scrollable components.| 380| header | [ComponentContent](../js-apis-arkui-ComponentContent.md) | No | Header component. | 381 382## ArcScrollIndexHandler 383 384type ArcScrollIndexHandler = (start: number, end: number, center: number) => void 385 386Represents the callback triggered when a child component enters or leaves the visible area of the **ArcList** component. 387 388**Atomic service API**: This API can be used in atomic services since API version 18. 389 390**System capability**: SystemCapability.ArkUI.ArkUI.Circle 391 392| Name| Type | Mandatory| Description | 393| ------ | ------ | ---- | ----------------------------------------- | 394| start | number | Yes | Index of the first child component in the visible area of the **ArcList** component. | 395| end | number | Yes | Index of the last child component in the visible area of the **ArcList** component.| 396| center | number | Yes | Index of the center child component in the visible area of the **ArcList** component.| 397 398## Example 399 400This example demonstrates an **ArcList** component with a header component and auto-scaling child items. 401 402```ts 403// xxx.ets 404import { ComponentContent, LengthMetrics } from "@kit.ArkUI"; 405import { UIContext } from '@kit.ArkUI'; 406import { ArcList, ArcListItem, ArcListAttribute, ArcListItemAttribute } from '@kit.ArkUI'; 407 408@Builder 409function buildText() { 410 Column() { 411 Text("header") 412 .fontSize('60px') 413 .fontWeight(FontWeight.Bold) 414 }.margin(0) 415} 416 417@Entry 418@Component 419struct Index { 420 @State private numItems: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; 421 422 private watchSize: string = '466px' // Default watch size: 466*466 423 private listSize: string = '414px' // Item width 424 425 context: UIContext = this.getUIContext() 426 tabBar1: ComponentContent<Object> = new ComponentContent(this.context, wrapBuilder(buildText)); 427 428 @Builder 429 buildList2() { 430 Stack() { 431 Column() { 432 } 433 .justifyContent(FlexAlign.Center) 434 .width(this.watchSize) 435 .height(this.watchSize) 436 .clip(new Circle({ width: '100%', height: '100%' })) 437 .backgroundColor(Color.White) 438 439 ArcList({ initialIndex: 0, header: this.tabBar1 }) { 440 ForEach(this.numItems, (item: number, index: number) => { 441 ArcListItem() { 442 Button('' + item, { type: ButtonType.Capsule }) 443 .width(this.listSize) 444 .height('100px') 445 .fontSize('40px') 446 .focusable(true) 447 .focusOnTouch(true) 448 .backgroundColor(0x17A98D) 449 }.align(Alignment.Center) 450 }, (item: string, index: number) => item + index) 451 } 452 .space(LengthMetrics.px(10)) 453 .borderRadius(this.watchSize) 454 .focusable(true) 455 .focusOnTouch(true) 456 .defaultFocus(true) 457 } 458 .align(Alignment.Center) 459 .width(this.watchSize) 460 .height(this.watchSize) 461 .border({color: Color.Black, width: 1}) 462 .borderRadius(this.watchSize) 463 } 464 465 build() { 466 Column() { 467 this.buildList2() 468 } 469 .width('100%') 470 .height('100%') 471 .alignItems(HorizontalAlign.Center) 472 .justifyContent(FlexAlign.Center) 473 } 474} 475``` 476 477 478
