Scroll

The Scroll component scrolls the content when the layout size of a component exceeds the size of its parent component.

NOTE

• This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
• When nesting a List within this component, specify the width and height for the List under scenarios where consistently high performance is required. If the width and height are not specified, this component will load all content of the List.
• This component can scroll only when the size on the main axis is less than the content size.
• The default value of the universal attribute clip is true for the Scroll component.

Child Components

This component supports only one child component.

APIs

Scroll(scroller?: Scroller)

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Attributes

In addition to universal attributes and scrollable component common attributes, the following attributes are also supported.

scrollable

scrollable(value: ScrollDirection)

Sets the scrolling direction.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

scrollBar

scrollBar(barState: BarState)

Sets the scrollbar state. If the container component cannot be scrolled, the scrollbar is not displayed. If the size of a child component of a container component is infinite, the scrollbar cannot be dragged or scrolled with the child component.

Since API version 10, when the scrollable component has rounded corners, to prevent the scrollbar from being cut off by the corners, the scrollbar will automatically calculate the clearance distance from the top and bottom.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

scrollBarColor

scrollBarColor(color: Color | number | string)

Sets the scrollbar color.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

scrollBarWidth

scrollBarWidth(value: number | string)

Sets the scrollbar width. This attribute cannot be set in percentage. After the width is set, the scrollbar is displayed with the set width in normal state and pressed state. If the set width exceeds the height of the Scroll component on the main axis, the scrollbar reverts to the default width.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

scrollSnap¹⁰⁺

scrollSnap(value: ScrollSnapOptions)

Sets the scroll snapping mode.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

edgeEffect

edgeEffect(edgeEffect: EdgeEffect, options?: EdgeEffectOptions)

Sets the effect used when the scroll boundary is reached.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

enableScrollInteraction¹⁰⁺

enableScrollInteraction(value: boolean)

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

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

nestedScroll¹⁰⁺

nestedScroll(value: NestedScrollOptions)

Sets the nested scrolling options. You can set the nested scrolling mode in the forward and backward directions to implement scrolling linkage with the parent component.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

friction¹⁰⁺

friction(value: number | Resource)

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. A value less than or equal to 0 evaluates to the default value.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

enablePaging¹¹⁺

enablePaging(value: boolean)

Sets whether to enable the swipe-to-turn-pages feature. If both enablePaging and scrollSnap are set, scrollSnap takes effect, but enablePaging does not.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

initialOffset¹²⁺

initialOffset(value: OffsetOptions)

Sets the initial scrolling offset. This attribute takes effect only during the initial layout of the component. After the initial layout, dynamically changing the value of this attribute does not have any effect.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

ScrollDirection

System capability: SystemCapability.ArkUI.ArkUI.Full

ScrollSnapOptions¹⁰⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Events

In addition to universal events and scrollable component common events, the following events are also supported.

onScrollFrameBegin⁹⁺

onScrollFrameBegin(event: (offset: number, state: ScrollState) => { offsetRemain: number; })

Triggered when each frame scrolling starts. The input parameters indicate the amount by which the Scroll component will scroll. The event handler then works out the amount by which the component needs to scroll based on the real-world situation and returns the result.

The value of offsetRemain can be a negative value.

If the onScrollFrameBegin event and scrollBy method are used to implement nested scrolling, set the edgeEffect attribute of the scrollable child component to None. For example, if a List is nested in the Scroll component, edgeEffect of the List must be set to EdgeEffect.None.

Notes:

1. This event is triggered when scrolling is started by the Scroll component or other input settings, such as keyboard and mouse operations.
   2. This event is not triggered when the controller API is called.
   3. This event does not support the out-of-bounds bounce effect.
   4. This event is not triggered when the scroll bar is dragged.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Return value

onScroll^(deprecated)

onScroll(event: (xOffset: number, yOffset: number) => void)

Triggered to return the horizontal and vertical offsets, in vp, during scrolling when the specified scroll event occurs.

NOTE

1. This event is triggered when scrolling is started by the Scroll component or other input settings, such as keyboard and mouse operations.

2. This event is triggered when the controller API is called.

3. This event supports the out-of-bounds bounce effect.

This API is deprecated since API version 12. You are advised to use onWillScroll instead.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

onWillScroll¹²⁺

onWillScroll(handler: ScrollOnWillScrollCallback)

Triggered before scrolling.

The callback provides the amount of offset that is about to be scrolled in the current frame, along with the current scroll status and the source of the scrolling operation. The offset provided in the callback is the calculated intended scrolling offset, not the final actual scrolling offset. You can specify the intended scrolling offset for the Scroll through the return value of this callback.

NOTE

1. This event is triggered when scrolling is started by the Scroll component or other input settings, such as keyboard and mouse operations.

2. This event is triggered when the controller API is called.

3. This event supports the out-of-bounds bounce effect.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

onDidScroll¹²⁺

onDidScroll(handler: ScrollOnScrollCallback)

Triggered when the Scroll component scrolls.

The return value is the scrolling offset amount in the current frame, along with the current scroll state.

NOTE

1. This event is triggered when scrolling is started by the Scroll component or other input settings, such as keyboard and mouse operations.

2. This event is triggered when the controller API is called.

3. This event supports the out-of-bounds bounce effect.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

onScrollEdge

onScrollEdge(event: (side: Edge) => void)

Triggered when scrolling reaches the edge.

NOTE

1. This event is triggered when scrolling reaches the edge after being started by the Scroll component or other input settings, such as keyboard and mouse operations.
   2. This event is triggered when the controller API is called.
   3. This event supports the out-of-bounds bounce effect.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

onScrollEnd^(deprecated)

onScrollEnd(event: () => void)

Triggered when scrolling stops.

NOTE

1. This event is triggered when scrolling is stopped by the Scroll component or other input settings, such as keyboard and mouse operations.
   2. This event is triggered when the controller API is called, accompanied by a transition animation.

This event is deprecated since API version 9. Use the onScrollStop event instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

onScrollStart⁹⁺

onScrollStart(event: () => void)

Triggered when scrolling starts and is initiated by the user's finger dragging the Scroll component or its scrollbar. This event is also triggered when the animation contained in the scrolling triggered by Scroller starts.

NOTE

1. This event is triggered when scrolling is started by the Scroll component or other input settings, such as keyboard and mouse operations.
   2. This event is triggered when the controller API is called, accompanied by a transition animation.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

onScrollStop⁹⁺

onScrollStop(event: () => void)

Triggered when scrolling stops after the user's finger leaves the screen. This event is also triggered when the animation contained in the scrolling triggered by Scroller stops.

NOTE

1. This event is triggered when scrolling is stopped by the Scroll component or other input settings, such as keyboard and mouse operations.
   2. This event is triggered when the controller API is called, accompanied by a transition animation.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

ScrollOnScrollCallback¹²⁺

type ScrollOnScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState) => void

Represents the callback triggered when the Scroll component scrolls.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

NOTE

If the onScrollFrameBegin event and scrollBy method are used to implement nested scrolling, set the edgeEffect attribute of the scrollable child component to None. For example, if a List is nested in the Scroll component, edgeEffect of the List must be set to EdgeEffect.None.

ScrollOnWillScrollCallback¹²⁺

type ScrollOnWillScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState, scrollSource: ScrollSource) => void | OffsetResult

Callback triggered before scrolling.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Scroller

Implements a controller for a scrollable container component. You can bind this component to a container component and use it to control the scrolling of that component. One controller can control only one container component. The supported container components are List, Scroll, ScrollBar, Grid, and WaterFlow.

NOTE

1. The binding of a Scroller instance to a scrollable container component occurs during the component creation phase.
   
2. Scroller APIs can only be effectively called after the Scroller instance is bound to a scrollable container component. Otherwise, depending on the API called, it may have no effect or throw an exception.
   
3. For example, with aboutToAppear, this callback is executed after a new instance of a custom component is created and before its build() method is called. Therefore, if a scrollable component is defined within the build method of a custom component, the internal scrollable component has not yet been created during the aboutToAppear callback of that custom component, and therefore the Scroller APIs cannot be called effectively.
   
4. For example, with onAppear, this callback is triggered after the component is mounted and displayed. Therefore, when the onAppear callback of a scrollable component is executed, the scrollable component has already been created and successfully bound to the Scroller instance, allowing the Scroller APIs to be called effectively.

Objects to Import

scroller: Scroller = new Scroller()

constructor

constructor()

A constructor used to create a Scroller object.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

scrollTo

scrollTo(value: { xOffset: number | string, yOffset: number | string, animation?: { duration?: number, curve?: Curve | ICurve, canOverScroll?: boolean } | boolean })

Scrolls to the specified position.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

scrollEdge

scrollEdge(value: Edge, options?: ScrollEdgeOptions)

Scrolls to the edge of the container, regardless of the scroll axis direction. Edge.Top and Edge.Start produce the same effect, and Edge.Bottom and Edge.End produce the same effect. By default, the Scroll component comes with an animation, while the Grid, List, and WaterFlow components do not.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

fling¹²⁺

fling(velocity: number): void

Performs inertial scrolling based on the initial velocity passed in.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Error codes

For details about the error codes, see Universal Error Codes.

scrollPage⁹⁺

scrollPage(value: ScrollPageOptions)

Scrolls to the next or previous page.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

scrollPage^(deprecated)

scrollPage(value: { next: boolean, direction?: Axis })

Scrolls to the next or previous page. This API is deprecated since API version 9. You are advised to use scrollPage⁹⁺ instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

currentOffset

currentOffset(): OffsetResult

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

System capability: SystemCapability.ArkUI.ArkUI.Full

scrollToIndex

scrollToIndex(value: number, smooth?: boolean, align?: ScrollAlign, options?: ScrollToIndexOptions)

Scrolls to a specified index, with support for setting an extra offset for the scroll.

When smooth is set to true, all passed items are loaded and counted in layout calculation. This may result in performance issues if a large number of items are involved.

NOTE

This API only works for the Grid, List, and WaterFlow components.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

scrollBy⁹⁺

scrollBy(dx: Length, dy: Length)

Scrolls by the specified amount.

NOTE

This API is available for the Scroll, List, Grid, and WaterFlow components.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

isAtEnd¹⁰⁺

isAtEnd(): boolean

Checks whether the component has scrolled to the bottom.

NOTE

This API is available for the Scroll, List, Grid, and WaterFlow components.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

getItemRect¹¹⁺

getItemRect(index: number): RectResult

Obtains the size and position of a child component relative to its container.

NOTE

This API is available for the Scroll, List, Grid, and WaterFlow components.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

• The value of index must be the index of a child component visible in the display area. Otherwise, the value is considered invalid.
• The size and position returned for an invalid value are both 0.

Return value

Error codes

For details about the error codes, see Universal Error Codes.

getItemIndex¹⁴⁺

getItemIndex(x: number, y: number): number

Obtains the index of a child component based on coordinates.

NOTE

This API is available for the List, Grid, and WaterFlow components.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NOTE

The returned index is -1 for invalid coordinates.

Return value

Error codes

For details about the error codes, see Universal Error Codes.

OffsetResult¹¹⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

ScrollAnimationOptions¹²⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

ScrollAlign¹⁰⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

ScrollToIndexOptions¹²⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

ScrollPageOptions¹⁴⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

OffsetOptions¹²⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

ScrollEdgeOptions¹²⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Example

Example 1: Setting the Scroller

This example demonstrates the use of some attributes of the Scroll component and the Scroller.

// xxx.ets
import { curves } from '@kit.ArkUI'

@Entry
@Component
struct ScrollExample {
  scroller: Scroller = new Scroller()
  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

  build() {
    Stack({ alignContent: Alignment.TopStart }) {
      Scroll(this.scroller) {
        Column() {
          ForEach(this.arr, (item: number) => {
            Text(item.toString())
              .width('90%')
              .height(150)
              .backgroundColor(0xFFFFFF)
              .borderRadius(15)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .margin({ top: 10 })
          }, (item: string) => item)
        }.width('100%')
      }
      .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction.
      .scrollBar(BarState.On) // The scrollbar is always displayed.
      .scrollBarColor(Color.Gray) // The scrollbar color is gray.
      .scrollBarWidth(10) // The scrollbar width is 10.
      .friction(0.6)
      .edgeEffect(EdgeEffect.None)
      .onWillScroll((xOffset: number, yOffset: number, scrollState: ScrollState) => {
        console.info(xOffset + ' ' + yOffset)
      })
      .onScrollEdge((side: Edge) => {
        console.info('To the edge')
      })
      .onScrollStop(() => {
        console.info('Scroll Stop')
      })

      Button('scroll 150')
        .height('5%')
        .onClick(() => { // Click to scroll down by 150.0 vp.
          this.scroller.scrollBy(0, 150)
        })
        .margin({ top: 10, left: 20 })
      Button('scroll 100')
        .height('5%')
        .onClick(() => { // Click to scroll down by 100.0 vp.
          const yOffset: number = this.scroller.currentOffset().yOffset;
          this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100 })
        })
        .margin({ top: 60, left: 20 })
      Button('scroll 100')
        .height('5%')
        .onClick(() => {// Click to scroll down by 100.0 vp. An animation is applied to the scrolling.
          let curve = curves.interpolatingSpring(10, 1, 228, 30) // Create a step curve.
          const yOffset: number = this.scroller.currentOffset().yOffset;
          this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100, animation: { duration: 1000, curve: curve } })
        })
        .margin({ top: 110, left: 20 })
      Button('back top')
        .height('5%')
        .onClick(() => { // Click to go back to the top.
          this.scroller.scrollEdge(Edge.Top)
        })
        .margin({ top: 160, left: 20 })
      Button('next page')
        .height('5%')
        .onClick(() => { // Click to go to the next page.
          this.scroller.scrollPage({ next: true ,animation: true })
        })
        .margin({ top: 210, left: 20 })
      Button('fling -3000')
        .height('5%')
        .onClick(() => { // Trigger a fling with an initial velocity of -3000 vp/s.
          this.scroller.fling(-3000)
        })
        .margin({ top: 260, left: 20 })
      Button('scroll to bottom 700')
        .height('5%')
        .onClick(() => {// After the button is clicked, the component scrolls to the bottom edge at a velocity of 700 vp/s.
          this.scroller.scrollEdge(Edge.Bottom, { velocity: 700 })
        })
        .margin({ top: 310, left: 20 })
    }.width('100%').height('100%').backgroundColor(0xDCDCDC)
  }
}

Example 2: Implementing Nested Scrolling (Method 1)

This example uses the onScrollFrameBegin event to achieve nested scrolling between an inner List component and an outer Scroll component.

import { LengthMetrics } from '@kit.ArkUI'

@Entry
@Component
struct NestedScroll {
  @State listPosition: number = 0; // 0 indicates scrolling to the top of the list, 1 indicates scrolling to the middle of the list, and 2 indicates scrolling to the bottom of the list.
  private arr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
  private scrollerForScroll: Scroller = new Scroller()
  private scrollerForList: Scroller = new Scroller()

  build() {
    Flex() {
      Scroll(this.scrollerForScroll) {
        Column() {
          Text("Scroll Area")
            .width("100%")
            .height("40%")
            .backgroundColor(0X330000FF)
            .fontSize(16)
            .textAlign(TextAlign.Center)
            .onClick(() => {
              this.scrollerForList.scrollToIndex(5, false, ScrollAlign.START, { extraOffset: LengthMetrics.vp(5) })
            })

          List({ space: 20, scroller: this.scrollerForList }) {
            ForEach(this.arr, (item: number) => {
              ListItem() {
                Text("ListItem" + item)
                  .width("100%")
                  .height("100%")
                  .borderRadius(15)
                  .fontSize(16)
                  .textAlign(TextAlign.Center)
                  .backgroundColor(Color.White)
              }.width("100%").height(100)
            }, (item: string) => item)
          }
          .width("100%")
          .height("50%")
          .edgeEffect(EdgeEffect.None)
          .friction(0.6)
          .onReachStart(() => {
            this.listPosition = 0
          })
          .onReachEnd(() => {
            this.listPosition = 2
          })
          .onScrollFrameBegin((offset: number) => {
            if ((this.listPosition == 0 && offset <= 0) || (this.listPosition == 2 && offset >= 0)) {
              this.scrollerForScroll.scrollBy(0, offset)
              return { offsetRemain: 0 }
            }
            this.listPosition = 1
            return { offsetRemain: offset };
          })

          Text("Scroll Area")
            .width("100%")
            .height("40%")
            .backgroundColor(0X330000FF)
            .fontSize(16)
            .textAlign(TextAlign.Center)
        }
      }
      .width("100%").height("100%")
    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding(20)
  }
}

Example 3: Implementing Nested Scrolling (Method 2)

This example uses the nestedScroll attribute to achieve nested scrolling between an inner List component and an outer Scroll component.

@Entry
@Component
struct StickyNestedScroll {
  @State arr: number[] = []

  @Styles
  listCard() {
    .backgroundColor(Color.White)
    .height(72)
    .width("100%")
    .borderRadius(12)
  }

  build() {
    Scroll() {
      Column() {
        Text("Scroll Area")
          .width("100%")
          .height("40%")
          .backgroundColor('#0080DC')
          .textAlign(TextAlign.Center)
        Tabs({ barPosition: BarPosition.Start }) {
          TabContent() {
            List({ space: 10 }) {
              ForEach(this.arr, (item: number) => {
                ListItem() {
                  Text("item" + item)
                    .fontSize(16)
                }.listCard()
              }, (item: string) => item)
            }.width("100%")
            .edgeEffect(EdgeEffect.Spring)
            .nestedScroll({
              scrollForward: NestedScrollMode.PARENT_FIRST,
              scrollBackward: NestedScrollMode.SELF_FIRST
            })
          }.tabBar("Tab1")

          TabContent() {
          }.tabBar("Tab2")
        }
        .vertical(false)
        .height("100%")
      }.width("100%")
    }
    .edgeEffect(EdgeEffect.Spring)
    .friction(0.6)
    .backgroundColor('#DCDCDC')
    .scrollBar(BarState.Off)
    .width('100%')
    .height('100%')
  }

  aboutToAppear() {
    for (let i = 0; i < 30; i++) {
      this.arr.push(i)
    }
  }
}

Example 4: Implementing Nested Scrolling with Parent-to-Child Scrolling Propagation

This example demonstrates how to propagate scrolling from a parent component to a child component using the enableScrollInteraction attribute and the onScrollFrameBegin event.

@Entry
@Component
struct NestedScroll {
  private headerHeight: number = 0;
  private arr: number[] = []
  private scrollerForParent: Scroller = new Scroller()
  private scrollerForChild: Scroller = new Scroller()

  aboutToAppear(): void {
    for (let i = 0; i < 10; i++) {
      this.arr.push(i)
    }
  }

  build() {
    Scroll(this.scrollerForParent) {
      Column() {
        Text("Scroll Area")
          .width("100%")
          .height("40%")
          .backgroundColor(0X330000FF)
          .fontSize(16)
          .textAlign(TextAlign.Center)
          .onClick(() => {
            this.scrollerForChild.scrollToIndex(5)
          })
          .onSizeChange((oldValue: SizeOptions, newValue: SizeOptions) => {
            this.headerHeight = newValue.height! as number
          })
        List({ space: 20, scroller: this.scrollerForChild }) {
          ForEach(this.arr, (item: number) => {
            ListItem() {
              Text("ListItem" + item)
                .width("100%")
                .height("100%")
                .borderRadius(15)
                .fontSize(16)
                .textAlign(TextAlign.Center)
                .backgroundColor(Color.White)
            }.width("100%").height(100)
          }, (item: string) => item)
        }
        .width("100%")
        .height("100%")
        .edgeEffect(EdgeEffect.None)
        .scrollBar(BarState.Off)
        .enableScrollInteraction(false)

        Text("Scroll Area")
          .width("100%")
          .height("40%")
          .backgroundColor(0X330000FF)
          .fontSize(16)
          .textAlign(TextAlign.Center)
      }
    }
    .scrollBar(BarState.Off)
    .edgeEffect(EdgeEffect.Spring)
    .onScrollFrameBegin((offset: number, state: ScrollState) => {
      let retOffset = offset;
      let currOffset = this.scrollerForParent.currentOffset().yOffset;
      let newOffset = currOffset + offset;
      if (offset > 0) {
        if (this.scrollerForChild.isAtEnd()) {
          return { offsetRemain: offset }
        }
        if (newOffset > this.headerHeight) {
          retOffset = this.headerHeight - currOffset
        }
        this.scrollerForChild.scrollBy(0, offset - retOffset)
      } else {
        if (this.scrollerForChild.currentOffset().yOffset <= 0) {
          return { offsetRemain: offset }
        }
        if (newOffset < this.headerHeight) {
          retOffset = this.headerHeight - currOffset
        }
        this.scrollerForChild.scrollBy(0, offset - retOffset)
      }
      return { offsetRemain: retOffset }
    })
    .width("100%")
    .height("100%")
    .backgroundColor(0xDCDCDC)
  }
}

Example 5: Setting Scroll Snapping

This example shows how to set scroll snapping for a Scroll component.

@Entry
@Component
struct Index {
  scroller: Scroller = new Scroller;
  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
  build() {
    Scroll(this.scroller) {
      Column() {
        ForEach(this.arr, (item: number) => {
          Text(item.toString())
            .width('90%')
            .height(200)
            .backgroundColor(0xFFFFFF)
            .borderWidth(1)
            .borderColor(Color.Black)
            .borderRadius(15)
            .fontSize(16)
            .textAlign(TextAlign.Center)
        }, (item: string) => item)
      }.width('100%').backgroundColor(0xDCDCDC)
    }
    .backgroundColor(Color.Yellow)
    .height('100%')
    .edgeEffect(EdgeEffect.Spring)
    .scrollSnap({snapAlign:ScrollSnapAlign.START, snapPagination:400, enableSnapToStart:true, enableSnapToEnd:true})
  }
}

Example 6: Obtaining the Index of a Child Component

This example demonstrates how to obtain the index of a child component in a List component.

// xxx.ets
@Entry
@Component
struct ListExample {
  private arr: number[] = []
  private scroller: ListScroller = new ListScroller()
  @State listSpace: number = 10
  @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100)
  @State listIndex: number = -1
  @State mess:string = "null"
  @State itemBackgroundColorArr: boolean[] = [false]
  aboutToAppear(){
    // Initialize the data source.
    for (let i = 0; i < 10; i++) {
      this.arr.push(i)
    }
    this.listChildrenSize.splice(0, 5, [100, 100, 100, 100, 100])
  }
  build() {
    Column() {
      List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) {
        ForEach(this.arr, (item: number) => {
          ListItem() {
            Text('item-' + item)
              .height( item < 5 ? 100 : this.listChildrenSize.childDefaultSize)
              .width('90%')
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .borderRadius(10)
              .backgroundColor( this.itemBackgroundColorArr[item] ? 0x68B4FF: 0xFFFFFF)
          }
        }, (item: string) => item)
      }
      .backgroundColor(Color.Gray)
      .layoutWeight(1)
      .scrollBar(BarState.On)
      .childrenMainSize(this.listChildrenSize)
      .alignListItem(ListItemAlign.Center)
      .gesture(
        PanGesture()
          .onActionUpdate((event: GestureEvent) => {
            if (event.fingerList[0] != undefined && event.fingerList[0].localX != undefined && event.fingerList[0].localY != undefined) {
              this.listIndex = this.scroller.getItemIndex(event.fingerList[0].localX, event.fingerList[0].localY)
              this.itemBackgroundColorArr[this.listIndex] = true;
            }
          })
      )
      .gesture(
        TapGesture({ count: 1 })
          .onAction((event: GestureEvent) => {
            if (event) {
              this.itemBackgroundColorArr.splice(0,this.itemBackgroundColorArr.length);
            }
          })
      )

      Text('You are currently at index '+ this.listIndex)
        .fontColor(Color.Red)
        .height(50)
    }
  }
}

Example 7: Setting Edge Fading

This example demonstrates how to implement a Scroll component with an edge fading effect and set the length of the fading edge.

// xxx.ets
import { LengthMetrics } from '@kit.ArkUI'
@Entry
@Component
struct ScrollExample {
  scroller: Scroller = new Scroller()
  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]

  build() {
    Stack({ alignContent: Alignment.TopStart }) {
      Scroll(this.scroller) {
        Column() {
          ForEach(this.arr, (item: number) => {
            Text(item.toString())
              .width('90%')
              .height(150)
              .backgroundColor(0xFFFFFF)
              .borderRadius(15)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .margin({ top: 10 })
          }, (item: string) => item)
        }.width('100%')
      }
      .fadingEdge(true,{fadingEdgeLength:LengthMetrics.vp(80)})



    }.width('100%').height('100%').backgroundColor(0xDCDCDC)
  }
}