HarmonyOS ArkUI Scroll 组件完全指南

前言

当页面内容超出屏幕高度时，就需要滚动容器来承载。HarmonyOS ArkUI 提供了Scroll和List两种主要的滚动组件。很多初学者傻傻分不清楚什么时候该用哪个。本篇聚焦Scroll组件的深入用法，并明确它与List的边界。

一、Scroll 基础用法

1.1 最简单的 Scroll

@Entry@Componentstruct BasicScrollDemo{privateitems:number[]=[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19];build(){// Scroll 只能有一个直接子节点Scroll(){Column({space:12}){// 模拟大量内容ForEach(this.items,(index:number)=>{Row(){Text(`第${index+1}行内容`).fontSize(15).fontColor('#333333')}.width('100%').height(56).padding({left:16,right:16}).backgroundColor(index%2===0?'#FFFFFF':'#F8F9FA').borderRadius(8)})}.padding({left:16,right:16,top:8,bottom:8}).width('100%')}.width('100%').height('100%').scrollable(ScrollDirection.Vertical)// 垂直滚动（默认）.scrollBar(BarState.Auto)// 自动显隐滚动条.edgeEffect(EdgeEffect.Fade)// 边缘回弹效果：渐隐}}

1.2 本项目中的 Scroll 使用

GasStationPage.ets的bindBuilder()中用了 Scroll：

@BuilderbindBuilder(){Column(){Scroll(){if(this.stationInfoList&&this.stationInfoList.length>0){List(){ForEach(this.stationInfoList,(station:StationData)=>{ListItem(){Row({space:Constants.SPACE_12}){this.stationInfoCard(station);}.width(Constants.FULL_PERCENT);};},(station:StationData)=>station.id+station.name)}.width(Constants.FULL_PERCENT);}}.backgroundColor($r('app.color.start_window_background')).borderRadius(Constants.BORDER_RADIUS).margin({left:Constants.MARGIN_LEFT_16,right:Constants.MARGIN_RIGHT_16}).scrollable(ScrollDirection.Vertical).edgeEffect(EdgeEffect.Fade).scrollBar(BarState.Off)// 关闭滚动条.layoutWeight(Constants.ONE).height(Constants.MY_BUILDER_HEIGHT)}.height(Constants.MY_BUILDER_COLUMN_HEIGHT);}

提示：项目中用了Scroll嵌套List的结构，是因为bindSheet的高度是动态的，外层 Scroll 负责整体滚动控制，内层 List 负责数据项渲染。

二、Scroll 的核心属性

2.1 滚动方向

Scroll(){// ...内容}.scrollable(ScrollDirection.Vertical)// 垂直滚动（默认）.scrollable(ScrollDirection.Horizontal)// 水平滚动.scrollable(ScrollDirection.Free)// 自由滚动（双向）.scrollable(ScrollDirection.None)// 禁止滚动

2.2 滚动条样式

Scroll(){/* ... */}.scrollBar(BarState.Auto)// 滚动时显示，停止后隐藏.scrollBar(BarState.On)// 始终显示.scrollBar(BarState.Off)// 始终隐藏（项目中使用）.scrollBarColor('#1A6FF5')// 滚动条颜色.scrollBarWidth(4)// 滚动条宽度

2.3 边缘效果

三、用 Scroller 编程式控制滚动

3.1 创建并绑定 Scroller

@Entry@Componentstruct ScrollControlDemo{// 创建 Scroller 控制器privatescroller:Scroller=newScroller();@StatescrollY:number=0;@StateshowBackTop:boolean=false;privateitems:number[]=[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19];build(){Stack(){Scroll(this.scroller){// 绑定控制器Column({space:12}){ForEach(this.items,(index:number)=>{Column({space:4}){Text(`加油站${index+1}`).fontSize(16).fontWeight(FontWeight.Medium)Text('北京市海淀区 · 距您 1.2km').fontSize(13).fontColor('#999999')}.width('100%').padding(16).backgroundColor('#FFFFFF').borderRadius(12).alignItems(HorizontalAlign.Start)})}.padding(16).width('100%')}.width('100%').height('100%').scrollBar(BarState.Off).onScroll((xOffset:number,yOffset:number)=>{// 监听滚动位置this.scrollY+=yOffset;this.showBackTop=this.scrollY>300;// 滚动超过300时显示回顶按钮})// 回到顶部按钮（浮层）if(this.showBackTop){Button('↑').width(44).height(44).borderRadius(22).backgroundColor('#1A6FF5').fontColor('#FFFFFF').fontSize(20).onClick(()=>{// 动画滚动到顶部this.scroller.scrollTo({xOffset:0,yOffset:0,animation:{duration:300,curve:Curve.EaseOut}});this.scrollY=0;}).position({right:16,bottom:80})}}.width('100%').height('100%')}}

3.2 常用 Scroller API

四、水平滚动：TabBar 横向菜单

4.1 实现分类横向滚动

@Entry@Componentstruct HorizontalScrollDemo{@StateselectedIndex:number=0;privatecategories:string[]=['全部','中国石化','中国石油','壳牌','道达尔','BP石油','中海油','昆仑能源'];build(){Column({space:16}){// 横向滚动分类栏Scroll(){Row({space:8}){ForEach(this.categories,(cat:string,index:number)=>{Text(cat).fontSize(14).fontColor(this.selectedIndex===index?'#FFFFFF':'#666666').padding({left:16,right:16,top:8,bottom:8}).backgroundColor(this.selectedIndex===index?'#1A6FF5':'#F0F0F0').borderRadius(20).onClick(()=>{this.selectedIndex=index;})})}.padding({left:16,right:16})}.scrollable(ScrollDirection.Horizontal).scrollBar(BarState.Off).width('100%')// 内容区Text(`当前分类：${this.categories[this.selectedIndex]}`).fontSize(16).fontColor('#333333').padding(16)}.width('100%').padding({top:16})}}

五、Scroll vs List：如何选择？

需要滚动的内容类型？ │ ├── 数量固定、内容多样（混合布局）────→ Scroll │ ├── 数量巨大（1000条以上）──────────→ List（虚拟化） │ ├── 需要分组标题、侧边索引栏 ────────→ List │ └── 数量有限（<100条）且布局一致 ──→ List 或 Scroll 均可

总结

Scroll是 ArkUI 中最通用的滚动容器，适合内容固定、布局混合的场景；通过Scroller控制器可以实现"回到顶部"、自动滚动等编程式控制。对于大量同类数据的渲染，推荐使用List（下一篇 List 深入讲解）。掌握scrollable、edgeEffect、scrollBar三个核心属性，加上onScroll事件监听，你就能应对绝大多数滚动场景。