ArcList

The 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.

NOTE

This component is supported since API version 18. Updates will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { ArcList, ArcListAttribute } from '@kit.ArkUI';

Child Components

Only the ArcListItem component is supported.

NOTE

Below are the rules for calculating the indexes of the child components of ArcList:

• The index increases in ascending order of child components.

• In the if/else statement, only the child components for which the condition evaluates to true participate in the index calculation.

• In the ForEach or LazyForEach statement, the indexes of all expanded subnodes are calculated.

• If the values of if/else, ForEach, and LazyForEach change, the indexes of subnodes are updated.

• Child components of ArcList whose visibility attribute is set to Hidden or None are still included in the index calculation.

APIs

ArcList(options?: ArkListOptions)

Creates an instance of the ArcList component with optional configuration parameters.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Attributes

In addition to the universal attributes, the following attributes are supported.

digitalCrownSensitivity

digitalCrownSensitivity(sensitivity: Optional<CrownSensitivity>)

Sets the sensitivity of the digital crown’s response to events.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

space

space(space: Optional<LengthMetrics>)

Sets the spacing between list items.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

scrollBar

scrollBar(status: Optional<BarState>)

Sets the state of the scrollbar.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

cachedCount

cachedCount(count: Optional<number>)

Sets 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.

When 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.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

chainAnimation

chainAnimation(enable: Optional<boolean>)

Sets 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.

The 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.

For chained animations to work properly, the edge scrolling effect of the ArcList component must be set to EdgeEffect.Spring.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

enableScrollInteraction

enableScrollInteraction(enable: Optional<boolean>)

Sets whether to support scroll gestures. When this attribute is set to false, scrolling by finger or mouse is not supported, but the Scroller controller API is not affected.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

fadingEdge

fadingEdge(enable: Optional&lt;boolean&gt;)

Sets whether to enable the edge fading effect.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

friction

friction(friction: Optional<number>)

Sets 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.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

scrollBarWidth

scrollBarWidth(width: Optional<LengthMetrics>)

Sets the width of the scrollbar. Once the width is set, the scrollbar will use this width in its pressed state.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

scrollBarColor

scrollBarColor(color: Optional<ColorMetrics>)

Sets the color of the scrollbar.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

flingSpeedLimit

flingSpeedLimit(speed: Optional<number>)

Sets 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.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

childrenMainSize

childrenMainSize(size: Optional<ChildrenMainSize>)

Sets the size information of the child components of the ArcList component along the main axis.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Events

onScrollIndex

onScrollIndex(handler: Optional<ArcScrollIndexHandler>)

Triggered 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.

If 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

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

onReachStart

onReachStart(handler: Optional<VoidCallback>)

Triggered when the list reaches the start position.

This event is triggered during initialization of the ArcList component if initialIndex 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.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

onReachEnd

onReachEnd(handler: Optional<VoidCallback>)

Triggered when the list reaches the end position.

If 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.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

onScrollStart

onScrollStart(handler: Optional<VoidCallback>)

Triggered 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 starts.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

onScrollStop

onScrollStop(handler: Optional<VoidCallback>)

Triggered 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 stops.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

onWillScroll

onWillScroll(handler: Optional<OnWillScrollCallback>)

Triggered 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.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

NOTE

When ScrollEdge or ScrollToIndex that does not involve animation is called, onWillScroll is not triggered.

onDidScroll

onDidScroll(handler: Optional<OnScrollCallback>)

Triggered when the list scrolls. The return value is the offset amount by which the list has scrolled and the current scroll state.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

ArkListOptions

Provides basic parameters for creating an ArcList component.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

ArcScrollIndexHandler

type ArcScrollIndexHandler = (start: number, end: number, center: number) => void

Represents the callback triggered when a child component enters or leaves the visible area of the ArcList component.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Example

This example demonstrates an ArcList component with a header component and auto-scaling child items.

// xxx.ets
import { ComponentContent, LengthMetrics } from "@kit.ArkUI";
import { UIContext } from '@kit.ArkUI';
import { ArcList, ArcListItem, ArcListAttribute, ArcListItemAttribute } from '@kit.ArkUI';

@Builder
function buildText() {
  Column() {
    Text("header")
      .fontSize('60px')
      .fontWeight(FontWeight.Bold)
  }.margin(0)
}

@Entry
@Component
struct Index {
  @State  private numItems: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];

  private watchSize: string = '466px' // Default watch size: 466*466
  private listSize: string = '414px' // Item width

  context: UIContext = this.getUIContext()
  tabBar1: ComponentContent<Object> = new ComponentContent(this.context, wrapBuilder(buildText));

  @Builder
  buildList2() {
    Stack() {
      Column() {
      }
      .justifyContent(FlexAlign.Center)
      .width(this.watchSize)
      .height(this.watchSize)
      .clip(new Circle({ width: '100%', height: '100%' }))
      .backgroundColor(Color.White)

      ArcList({ initialIndex: 0, header: this.tabBar1 }) {
        ForEach(this.numItems, (item: number, index: number) => {
          ArcListItem() {
            Button('' + item, { type: ButtonType.Capsule })
              .width(this.listSize)
              .height('100px')
              .fontSize('40px')
              .focusable(true)
              .focusOnTouch(true)
              .backgroundColor(0x17A98D)
          }.align(Alignment.Center)
        }, (item: string, index: number) => item + index)
      }
      .space(LengthMetrics.px(10))
      .borderRadius(this.watchSize)
      .focusable(true)
      .focusOnTouch(true)
      .defaultFocus(true)
    }
    .align(Alignment.Center)
    .width(this.watchSize)
    .height(this.watchSize)
    .border({color: Color.Black, width: 1})
    .borderRadius(this.watchSize)
  }

  build() {
    Column() {
      this.buildList2()
    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
    .justifyContent(FlexAlign.Center)
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙Dialog Box (Dialog)

harmony 鸿蒙DialogV2

harmony 鸿蒙DownloadFileButton