#我的鸿蒙开发手记#Scroll 滚动容器完全自学指南原创

李森同学

发布于 2025-5-15 11:46

浏览

0收藏

1. Scroll 到底能干什么？基础认识

Scroll，其实就是一个“能滚动的容器”，你可以把它理解成 ArkTS 里的万能滚动盒子。只要你的内容超出了父容器的空间，Scroll就能自动出现滚动条，帮你把内容滑进视野里。

使用场景举例

列表太长，要滚动才看得全；
内容宽度超屏，需要横向滑动浏览；
想做一些自定义滚动特效，比如惯性回弹、分页等。

2. Scroll 的最基础用法

很多时候我们用Scroll只是为了装一大堆内容，让它能滚动起来。下面是最基础的代码示例。

@Entry
@Component
struct SimpleScrollDemo {
  private items: string[] = [];
  onLoad() {
    for (let i = 0; i < 20; i++) {
      this.items.push(`内容 ${i + 1}`);
    }
  }


  build() {
    Scroll() {
      Column() {
        ForEach(this.items, (item: string) => {
          Text(item)
            .width('90%')
            .padding(16)
            .margin({ top: 8, bottom: 8 })
            .backgroundColor(0xF8F8F8)
            .borderRadius(8)
            .fontSize(17)
        })
      }
      .width('100%')
    }
    .height('75%')
    .backgroundColor('#F2F3F5')
    .scrollBar(BarState.On)
  }
}

说明：

Scroll 只能有一个子组件（比如 Column、Row、Stack等），但这个子组件可以无限嵌套内容。
不指定宽高时，如果内容超出了父容器，自然就能滚动。

3. 滚动方向切换：竖直还是水平？

Scroll 支持指定滚动方向，不止竖直滚动，水平/双向都可以用！

@Entry
@Component
struct DirectionScrollDemo {
  private imgs: string[] = ['A', 'B', 'C', 'D', 'E', 'F']

  build() {
    Column() {
      // 横向滚动内容
      Scroll() {
        Row() {
          ForEach(this.imgs, (item: string) => {
            Text('图片' + item)
              .width(120)
              .height(100)
              .fontSize(24)
              .backgroundColor('#BBDEFB')
              .textAlign(TextAlign.Center)
              .margin({ right: 18 })
              .borderRadius(14)
          })
        }
        .height(100)
        .padding({ left: 12 })
      }
      .scrollable(ScrollDirection.Horizontal)
      .height(120)
      .backgroundColor('#E3F2FD')
    }
    .width('100%')  // 确保根容器宽度撑满
  }
}

#我的鸿蒙开发手记#Scroll 滚动容器完全自学指南-鸿蒙开发者社区
技巧：

.scrollable(ScrollDirection.Horizontal) 控制水平方向；
默认是竖直滚动（Vertical），也可以设置为 ScrollDirection.None 禁止滚动。

4. 滚动条个性化

想让滚动条“更明显”，或者跟界面风格一致，可以用这些方法：

@Entry
@Component
struct CustomScrollbarDemo {
  build() {
    Scroll()
      .scrollable(ScrollDirection.Vertical)
      .scrollBar(BarState.On)
      .scrollBarColor('#007AFF')
      .scrollBarWidth(8) {
      Column() {
        ForEach(Array.from({length: 30}, (_, i) => i + 1), (idx: number) => {
          Text(`Item #${idx}`)
            .width('92%')
            .height(60)
            .margin({ bottom: 8 })
            .backgroundColor('#E5F3FF')
            .borderRadius(12)
            .fontSize(17)
        })
      }
      .width('100%')
      .padding({ top: 16 })
    }
    .height('70%')
    .backgroundColor('#E0F7FA')
  }
}

说明：

.scrollBar(BarState.On) 滚动条常驻显示；
.scrollBarColor()、.scrollBarWidth() 可以自定义滚动条样式。

5. 控制滚动位置：Scroller 控制器实战

Scroll 不只是让用户用手滑，还可以用代码精确控制滚动，比如自动回到顶部、滚动到底部、跳转到指定位置等。

@Entry
@Component
struct ScrollControlDemo {
  scroller: Scroller = new Scroller()

  build() {
    Column({ space: 12 }) {
      // 滚动区域
      Scroll() {
        Column() {
          // 使用 ForEach 构建列表项
          ForEach(
            Array.from({ length: 16 }, (_: number, i: number) => `内容${i + 1}`),
            (item: string) => {
              Text(item)
                .width('95%')
                .padding(14)
                .backgroundColor(0xE2E6EF)
                .fontSize(16)
                .borderRadius(9)
                .margin({ top: 5, bottom: 5 })
            }
          )
        }
        .width('100%')
      }
      .scrollable(ScrollDirection.Vertical) // 设置垂直滚动
      .height(260) // 设置滚动区域高度

      // 滚动控制按钮
      Row({ space: 18 }) {
        Button('回到顶部')
          .onClick(() => {
            this.scroller.scrollTo({ xOffset: 0, yOffset: 0, animation: true })
          })

        Button('滚动到底部')
          .onClick(() => {
            this.scroller.scrollEdge(Edge.Bottom)
          })

        Button('下移120')
          .onClick(() => {
            this.scroller.scrollBy(0, 120)
          })
      }
    }
    .padding(18)
    .backgroundColor('#F7F8FA') // 页面背景色
    .width('100%')
    .height('100%')
  }
}

#我的鸿蒙开发手记#Scroll 滚动容器完全自学指南-鸿蒙开发者社区