一、引言

在鸿蒙应用开发中，当页面内容超出屏幕显示范围时，滚动功能是必不可少的。Scroll 组件作为鸿蒙提供的基础滚动容器，能够轻松实现内容的滚动展示。本文将通过一个完整的实战案例，带你快速掌握 Scroll 组件的核心用法。

二、Scroll 组件基础概念

简单来说，Scroll 组件是一个可滚动的容器组件。当它的子元素高度（或宽度）超过 Scroll 组件自身的大小时，滚动条就会出现，用户可以通过滑动来查看被隐藏的内容。

2.1 核心特性

• 自动滚动：子元素超出容器范围时自动启用滚动。
• 方向可控：支持垂直滚动和水平滚动。
• 边缘效果：支持回弹效果，提升交互体验。
• 单一子元素：Scroll 组件的直接子元素只能有一个。

三、实战案例：垂直滚动列表

下面我们通过一个具体的示例来演示 Scroll 组件的使用。在这个案例中，我们使用 ForEach 循环遍历一个数组，动态渲染多个高度为 100vp 的文本组件。

3.1 示例代码

@Entry
@Component
struct ScrollDemo {
  // 定义数据源
  private items: string[] = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5', 'Item 6', 'Item 7', 'Item 8'];

  build() {
    Scroll() {
      Column() {
        // 通过 ForEach 遍历数组，渲染多个文本组件
        ForEach(this.items, (item: string) => {
          Text(item)
            .width('100%')
            .height(100) // 每个文本组件高度为 100vp
            .backgroundColor('#FFD700')
            .textAlign(TextAlign.Center)
            .fontSize(20)
            .margin({ bottom: 10 })
        }, (item: string) => item)
      }
      .width('100%')
    }
    .scrollable(ScrollDirection.Vertical) // 设置滚动方向为垂直
    .edgeEffect(EdgeEffect.Spring) // 设置边缘回弹效果
    .width('100%')
    .height('100%')
  }
}

运行效果：

3.2 代码解析

1. 数据源：定义了一个包含 8 个字符串的数组 items，用于模拟列表数据。
2. Scroll 容器：作为最外层的滚动容器，包裹 Column 组件。
3. Column 布局：作为 Scroll 的唯一直接子元素，内部通过 ForEach 循环渲染文本组件。
4. 文本组件：每个 Text 组件的高度被设置为 100vp，并设置了背景色、文字对齐和字体大小。
5. 滚动方向：通过 .scrollable(ScrollDirection.Vertical) 将滚动方向设置为垂直。
6. 边缘效果：通过 .edgeEffect(EdgeEffect.Spring) 启用回弹效果。

四、核心属性详解

4.1 滚动方向（scrollable）

Scroll 组件通过 scrollable 属性控制滚动方向，支持以下取值：

• ScrollDirection.Vertical：垂直滚动（默认值）
• ScrollDirection.Horizontal：水平滚动
• ScrollDirection.None：禁止滚动

// 设置为水平滚动
Scroll() {
  Row() {
    // 水平排列的子元素
  }
}
.scrollable(ScrollDirection.Horizontal)

4.2 边缘滑动效果（edgeEffect）

edgeEffect 属性用于设置滚动到边缘时的反馈效果：

• EdgeEffect.Spring：回弹效果（默认值），滚动到边缘时会有弹性回弹的动画。
• EdgeEffect.None：无效果，滚动到边缘时直接停止，没有回弹动画。

// 去掉回弹效果
Scroll() {
  // 子元素
}
.edgeEffect(EdgeEffect.None)

五、注意事项

5.1 直接子元素只能有一个

这是使用 Scroll 组件时最容易犯的错误。Scroll 组件的直接子元素只能有一个。如果需要放置多个子组件，必须用一个容器组件（如 Column、Row、Flex 等）将它们包裹起来。

错误示例：

// ❌ 错误：Scroll 下有两个平行的子元素
Scroll() {
  Text('第一个元素')
  Text('第二个元素') // 这里会报错
}

正确示例：

// ✅ 正确：用一个 Column 包裹所有子元素
Scroll() {
  Column() {
    Text('第一个元素')
    Text('第二个元素')
  }
}

5.2 性能优化

当列表数据量较大时，建议使用 LazyForEach 替代 ForEach，以实现按需加载，提升滚动性能。

六、总结

本文通过一个完整的实战案例，详细介绍了鸿蒙 Scroll 组件的使用方法。我们学习了：

• Scroll 组件的基本概念和核心特性
• 如何通过 ForEach 遍历渲染高度为 100vp 的文本组件
• 滚动方向、边缘效果等核心属性的配置
• 使用 Scroll 组件时的注意事项

掌握了这些知识，你就可以在鸿蒙应用中灵活运用 Scroll 组件，构建流畅的滚动页面了。