鸿蒙滚动容器Scroll

滚动容器 Scroll

当子组件的布局尺寸超过Scroll的尺寸时，内容可以滚动

滚动容器 Scroll用法说明

1,给滚动容器 Scroll设置尺寸
2,设置溢出的子组件(只支持一个子组件)，特别注意只能有一个子组件
3,滚动方向(支持横向和纵向，默认纵向)，Vertical 纵向滚动； Horizontal横向滚动

特别说明：通过scrollable(ScrollDirection.Vertical)可以配置滚动方向。
如果我们设置为横向滚动，Scroll容器下的应该是Row组件
如果是纵向滚动，Scroll容器下的应该是Column组件

基本语法

Scroll(){
        // Scroll容器只能有一个子组件
        Column(){
          // 内容放在这里，尺寸超过Scroll就会滚动
        }
      }.width('100%').height(200).scrollable(ScrollDirection.Vertical)
     //  Vertical 纵向滚动； Horizontal横向滚动

不使用滚动容器是不会滚动的，如下：

@Entry
@Component
struct Index {
  build() {
     Column(){
       Column(){
         ForEach(Array.from({length:20}),(item:string,index:number)=>{
            Text('我是文本'+ index.toString()).height(50).backgroundColor("#909").width('100%').margin({bottom:10})
         })
       }.margin({left:10,right:10})
        // 设置左右两侧的间距
    }
  }
}

Scroll容器内容超出滚动

@Entry
@Component
struct Index {
  build() {
     Column(){
       // 通过Scroll容器，内容超出400的时候；就会出现滚动
       Scroll(){
         Column(){
           ForEach(Array.from({length:20}),(item:string,index:number)=>{
             Text('我是文本'+ index.toString()).height(50).backgroundColor("#909").width('100%').margin({bottom:10})
           })
         }.padding({left:10,right:10})
       }.height(400)
    }
  }
}

滚动条的常用属性

scrollable：设置滚动方向（垂直、水平或禁用滚动）。
类型：ScrollDirection（枚举：Vertical、Horizontal、None）

scrollBar：是否显示滚动条。或者说:控制滚动条显示策略（自动/始终显示/隐藏）。
类型：BarState（枚举：Auto、On、Off）
.scrollBar(BarState.Off) 不会显示滚动条了
.scrollBar(BarState.Auto) 滚动的时候会显示滚动条，不滚动的时候就不显示滚动条

scrollBarColor：自定义滚动条颜色。
类型：ResourceColor
.scrollBarColor("#909") 

scrollBarWidth：作用：设置滚动条宽度（如 '8vp'）
类型：number / string

使用上面的属性

@Entry
@Component
struct Index {
  build() {
     Column(){
       // 通过Scroll容器，内容超出400的时候；就会出现滚动
       Scroll(){
         Column(){
           ForEach(Array.from({length:20}),(item:string,index:number)=>{
             Text('我是文本'+ index.toString()).height(50).backgroundColor("#909").width('100%').margin({bottom:10})
           })
         }.padding({left:10,right:10})
       }.height(400).scrollBar(BarState.Auto).scrollBarColor("#911119").scrollBarWidth(10)
     }
  }
}

滚动行为控制

2. 滚动行为控制
edgeEffect
类型：EdgeEffect（枚举：Spring、Fade、None）
作用：滚动到边缘时的效果（弹性回弹/渐隐/无效果）。

friction
类型：number
作用：设置滚动摩擦系数，影响滚动惯性速度。

nestedScroll
类型：NestedScrollOptions
作用：控制嵌套滚动的优先级（如子组件优先滚动）。

控制滚动条的位置

控制滚动的的位置，我们需要下面三部
1.创建Scroll对象(实例化)

myScrollObj:Scroller = new Scroller()

2.将创建的实例绑定给Scroll组件

Scroll(this.myScrollObj){}

3.点击按钮，滚动到最顶部的位置

Button('获取滚动条的位置').onClick(()=>{
  // 让滚动条在最顶部的位置 Edge.Top 等价于 Edge.Start，表示在最顶部或者最左侧
  this.myScrollObj.scrollEdge(Edge.Start)
})

@Entry
@Component
struct Index {
  // 1.创建Scroll对象(实例化)
  myScrollObj:Scroller = new Scroller()
  build() {
     Column(){
       // 2.将创建的实例绑定给Scroll组件
       Scroll(this.myScrollObj){
         Column(){
           ForEach(Array.from({length:20}),(item:string,index:number)=>{
             Text('我是文本'+ index.toString()).height(50).backgroundColor("#909").width('100%').margin({bottom:10})
           })
         }.padding({left:10,right:10})
       }.height(400).scrollBar(BarState.Auto).scrollBarColor("#911119").scrollBarWidth(10).edgeEffect(EdgeEffect.Fade)

       Button('获取滚动条的位置').onClick(()=>{
         // 让滚动条在最顶部的位置 Edge.Top 等价于 Edge.Start，表示在最顶部或者最左侧
         this.myScrollObj.scrollEdge(Edge.Start)
       })
     }
  }
}

获取滚动距离顶部的距离

@Entry
@Component
struct Index {
  // 1.创建Scroll对象(实例化)
  myScrollObj:Scroller = new Scroller()
  build() {
     Column(){
       // 2.将实例绑定给Scroll组件
       Scroll(this.myScrollObj){
         Column(){
           ForEach(Array.from({length:20}),(item:string,index:number)=>{
             Text('我是文本'+ index.toString()).height(50).backgroundColor("#909").width('100%').margin({bottom:10})
           })
         }.padding({left:10,right:10})
       }.height(400).scrollBar(BarState.Auto).scrollBarColor("#911119").scrollBarWidth(10).edgeEffect(EdgeEffect.Fade)

       Button('获取滚动距离顶部的距离').onClick(()=>{
        // 获取距离顶部的距离
        const y = this.myScrollObj.currentOffset().yOffset
        // const x = this.myScrollObj.currentOffset().xOffset 获取距离左侧的距离
         AlertDialog.show({
           message:`距离定的距离${y}`
         })
       })
     }
  }
}

常用事件

事件回调
onScroll从API version12开始废弃不再使用，推荐使用onWillScroll事件替代。使用onWillScroll（12+版本）
类型：(offset: number, event: ScrollEvent) => void
作用：当滚动时触发，监听滚动位置变化，返回当前滚动偏移量。

onScrollStart
类型：() => void
作用：滚动开始时触发。

onScrollStop
类型：() => void
作用：滚动停止时触发。

onReachStart / onReachEnd
类型：() => void
作用：滚动到起始或末尾时触发。

鸿蒙官方文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V14/ts-container-scrollable-common-V14#onreachstart11