前言Scroll是 ArkUI 中最常用的可滚动容器组件当内容超出屏幕高度时Scroll 提供滚动能力。本篇以小分享 App 的HomePage和DiscoverPage为例讲解 Scroll 组件的核心属性、嵌套技巧和性能优化。详细 API 可参考 HarmonyOS Scroll 官方文档。一、Scroll 基本用法1.1 基础结构Scroll 通常包裹一个 ColumnColumn 内放置多个子元素Scroll() { Column({ space: 20 }) { // 子元素 1 // 子元素 2 // 子元素 3 } .padding({ bottom: 80 }) } .layoutWeight(1) .scrollBar(BarState.Off)1.2 小分享 App 中的 Scroll小分享 App 的HomePage使用 Scroll 包裹整个内容区Scroll() { Column({ space: 20 }) { // Banner 营销位 this.BannerSection() // 六宫格分类导航 this.CategoryGrid() // 最近使用横向列表 this.RecentSection() } .padding({ bottom: 80 }) } .layoutWeight(1) .scrollBar(BarState.Off)二、Scroll 核心属性2.1 scrollBar 滚动条取值效果BarState.Off隐藏滚动条BarState.On始终显示BarState.Auto滚动时自动显示2.2 scrollable 滚动方向取值效果ScrollDirection.Vertical纵向滚动ScrollDirection.Horizontal横向滚动ScrollDirection.Both双向滚动ScrollDirection.None禁止滚动2.3 edgeEffect 边界效果取值效果EdgeEffect.Spring弹簧效果EdgeEffect.None无效果三、Scroll 嵌套 Column 的布局技巧3.1 内容区撑开Scroll 外层必须设置layoutWeight(1)或固定高度否则无法滚动Column() { // Header (固定高度) Row() { ... } // 内容区 (撑开剩余空间) Scroll() { Column({ space: 20 }) { // ... } } .layoutWeight(1) // 必须撑开 .scrollBar(BarState.Off) }3.2 底部留白Scroll 内的 Column 底部设置 padding避免内容被底部导航栏遮挡Column({ space: 20 }) { // ... } .padding({ bottom: 80 }) // 底部留 80vp3.3 全屏背景色Scroll 的父容器要设置背景色Scroll 本身不设置Column() { Scroll() { Column({ space: 20 }) { // ... } } .layoutWeight(1) } .width(100%) .height(100%) .backgroundColor(#F5F5F5) // 父容器设背景色四、Scroll 事件处理4.1 onScroll 滚动监听Scroll() { Column() { ... } } .onScroll((xOffset: number, yOffset: number) { hilog.info(DOMAIN, testTag, Scroll offset: x%{public}d, y%{public}d, xOffset, yOffset); })4.2 onScrollBegin 滚动开始Scroll() { Column() { ... } } .onScrollBegin((xOffset: number, yOffset: number) { // 可以在这里阻止滚动 return { xOffset, yOffset }; })4.3 onScrollEnd 滚动结束Scroll() { Column() { ... } } .onScrollEnd(() { hilog.info(DOMAIN, testTag, %{public}s, Scroll ended); })五、横向滚动 Scroll5.1 横向滚动示例小分享 App 的DiscoverPage使用横向 Scroll 展示推荐模板Scroll() { Row({ space: 12 }) { ForEach(this.recommendTemplates, (item: RecommendTemplateItem, index: number) { Column({ space: 8 }) { Column() { Text() .fontSize(36) } .width(120) .height(80) .backgroundColor(item.color) .borderRadius(12) .justifyContent(FlexAlign.Center) .alignItems(HorizontalAlign.Center) Text(item.title) .fontSize(12) .fontColor(#666666) } .onClick(() { router.pushUrl({ url: pages/TemplateDetailPage }); }) }, (item: RecommendTemplateItem, index: number) item.title) } .padding({ left: 20, right: 20 }) } .scrollable(ScrollDirection.Horizontal) // 横向滚动 .scrollBar(BarState.Off)5.2 横向滚动要点横向滚动要点如下Scroll 内放 Row 而非 Column设置scrollable(ScrollDirection.Horizontal)Row 不设width(100%)由内容撑开每个子元素设固定宽度六、Scroll 性能优化6.1 避免过深嵌套Scroll 嵌套过深会导致性能下降// ❌ 避免过深嵌套 Scroll() { Column() { Column() { Column() { // ... } } } } // ✅ 尽量扁平化 Scroll() { Column({ space: 20 }) { // 直接放置子元素 } }6.2 使用 LazyForEach大量数据时使用LazyForEach替代ForEachScroll() { Column() { LazyForEach(this.dataSource, (item: DataItem) { // 懒加载渲染 }, (item: DataItem) item.id) } }6.3 避免频繁的状态更新// ❌ 每次滚动都更新状态 Scroll() { // ... } .onScroll(() { this.scrollOffset yOffset; // 频繁触发重建 }) // ✅ 使用局部变量 Scroll() { // ... } .onScroll(() { const offset yOffset; // 局部变量不触发重建 })七、Scroll 常见问题7.1 问题 1Scroll 不滚动原因Scroll 没有固定高度或内容没有超出 Scroll 高度。解决方案给 Scroll 外层容器设layoutWeight(1)或固定高度确保内容总高度 Scroll 可视区高度7.2 问题 2Scroll 嵌套 List原因Scroll 和 List 都有滚动能力嵌套会导致手势冲突。解决方案去掉外层 Scroll使用 List 的 section 功能。7.3 问题 3滚动条不显示原因设置了scrollBar(BarState.Off)或系统默认隐藏。解决方案改为scrollBar(BarState.On)或scrollBar(BarState.Auto)。八、本篇核心知识点8.1 Scroll 核心属性Scroll 核心属性总结如下scrollBar(BarState.Off)隐藏滚动条scrollable(ScrollDirection.Vertical)滚动方向edgeEffect(EdgeEffect.Spring)边界弹簧效果layoutWeight(1)撑开父容器8.2 实战开发要点实战开发中需要重点关注以下几个要点Scroll 外层必须设固定高度或 layoutWeight(1)内容区底部留白避免被遮挡横向滚动时设scrollable(ScrollDirection.Horizontal)大量数据使用 LazyForEach总结本文详细讲解了 HarmonyOS Scroll 组件的核心属性、嵌套布局、横向滚动、事件处理和性能优化。下一篇我们将看 ForEach 循环渲染列表与 key 生成策略。附录完整实现细节1. 核心 API 参考API作用说明本文涉及的核心 API功能实现参见华为官方文档2. 完整代码示例// 核心功能代码 // 详见正文中的完整实现3. 常见问题排查问题原因解决方案编译错误import 路径错误检查路径和 API 版本运行时异常参数不合法使用 try/catch 捕获性能问题主线程耗时操作使用异步 API4. 最佳实践错误处理完善使用 try/catch 包裹资源及时释放避免内存泄漏异步操作使用 async/await权限配置完整按需申请5. 完整代码文件索引文件路径说明本文涉及的代码文件见正文6. 实现要点总结核心实现要点API 的正确使用方法和参数说明完整的代码实现流程常见问题的排查方案性能优化和安全建议7. 总结本文详细讲解了小分享 App 中对应功能的完整实现。通过本文的学习读者可以掌握 HarmonyOS 开发的核心 API 使用方法和最佳实践。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力