HarmonyOS6 ArkTS Scroll

文章目录Scroll 组件概述核心 API 说明1. 滚动控制器 Scroller2. 滚动方向 ScrollDirection3. 滚动条配置 BarState4. 边缘效果 EdgeEffect5. 核心事件完整代码功能模块说明1. 页面整体滚动2. 垂直滚动模块3. 水平滚动模块4. 事件监听总结Scroll 组件概述Scroll是 HarmonyOS ArkTS 中最基础、最核心的滚动容器组件用于包裹超出屏幕显示范围的内容支持垂直滚动 / 水平滚动滚动条自定义颜色、宽度、显示策略边缘回弹效果惯性滚动与摩擦系数调节手动滚动控制回到边缘、指定距离滚动、翻页、惯性滚动滚动状态监听滚动中、开始、停止、触边滚动生效条件内容尺寸 容器尺寸。核心 API 说明1. 滚动控制器 Scroller用于主动控制滚动行为、获取滚动偏移量一个控制器只能绑定一个滚动组件。privatescroller:ScrollernewScroller();常用方法scrollEdge(Edge)滚动到指定边缘Top/Bottom/Left/Right/Start/EndscrollBy(dx, dy)相对当前位置滚动指定距离scrollPage({next, animation})滚动一页fling(velocity)惯性滚动currentOffset()获取偏移量xOffset / yOffset2. 滚动方向 ScrollDirectionScrollDirection.Vertical垂直滚动默认ScrollDirection.Horizontal水平滚动ScrollDirection.None禁止滚动3. 滚动条配置 BarStateBarState.On始终显示BarState.Off始终隐藏BarState.Auto滚动时显示静止时隐藏4. 边缘效果 EdgeEffectEdgeEffect.SPRING弹簧回弹效果EdgeEffect.NONE无边缘效果5. 核心事件onDidScroll滚动过程实时触发onScrollStart滚动开始时触发onScrollStop滚动停止时触发onScrollEdge滚动到边缘时触发完整代码// ScrollCompleteExample.ets Entry Component struct ScrollCompleteExample { // 页面整体滚动控制器 private pageScroller: Scroller new Scroller(); private vScroller: Scroller new Scroller(); private hScroller: Scroller new Scroller(); private scrollList: number[] []; aboutToAppear() { for (let i 1; i 30; i) { this.scrollList.push(i); } } State vOffset: number 0; State hOffset: number 0; build() { Scroll(this.pageScroller) { Column({ space: 20 }) { Text(垂直滚动示例) .fontSize(20) .fontWeight(FontWeight.Bold) .alignSelf(ItemAlign.Center) .fontColor(#2A2A2A); Text(垂直滚动偏移量${Math.round(this.vOffset)} vp) .width(90%) .height(40) .backgroundColor(#3878F3) .fontColor(#FFFFFF) .textAlign(TextAlign.Center) .fontSize(14) .borderRadius(8); Scroll(this.vScroller) { Column({ space: 12 }) { ForEach(this.scrollList, (item: number) { Text(垂直项 ${item}) .width(100%) .height(100) .backgroundColor(#FFFFFF) .fontSize(16) .fontWeight(FontWeight.Medium) .fontColor(#2A2A2A) .textAlign(TextAlign.Center) .borderRadius(12) .shadow({ radius: 4, color: #00000010, offsetX: 0, offsetY: 2 }); }, (item: number) item.toString()) } .width(100%) .padding(10); } .scrollable(ScrollDirection.Vertical) .scrollBar(BarState.On) .scrollBarColor(#3878F3) .scrollBarWidth(6) .friction(0.75) .edgeEffect(EdgeEffect.Spring) .enableScrollInteraction(true) .width(90%) .height(300) .backgroundColor(#F5F7FA) .borderRadius(12) .onDidScroll(() this.vOffset this.vScroller.currentOffset().yOffset ?? 0) .onScrollStart(() console.info(垂直滚动开始)) .onScrollStop(() console.info(垂直滚动停止)) .onScrollEdge((side) console.info(触边)); Scroll() { Row({ space: 10 }) { Button(回到顶部) .width(100) .backgroundColor(#3878F3) .fontColor(#FFFFFF) .onClick(() this.vScroller.scrollEdge(Edge.Top, { velocity: 600 })); Button(滚动到底部) .width(100) .backgroundColor(#3878F3) .fontColor(#FFFFFF) .onClick(() this.vScroller.scrollEdge(Edge.Bottom, { velocity: 600 })); Button(上滑200vp) .width(100) .backgroundColor(#68B4FF) .fontColor(#FFFFFF) .onClick(() this.vScroller.scrollBy(0, -200)); Button(下滑200vp) .width(100) .backgroundColor(#68B4FF) .fontColor(#FFFFFF) .onClick(() this.vScroller.scrollBy(0, 200)); } .padding(5); } .scrollable(ScrollDirection.Horizontal) .width(90%); Text(水平滚动示例) .fontSize(20) .fontWeight(FontWeight.Bold) .alignSelf(ItemAlign.Center) .fontColor(#2A2A2A); Text(水平滚动偏移量${Math.round(this.hOffset)} vp) .width(90%) .height(40) .backgroundColor(#86909C) .fontColor(#FFFFFF) .textAlign(TextAlign.Center) .fontSize(14) .borderRadius(8); Scroll(this.hScroller) { Row({ space: 12 }) { ForEach(this.scrollList, (item: number) { Text(水平项 ${item}) .width(150) .height(200) .backgroundColor(#FFFFFF) .fontSize(16) .fontWeight(FontWeight.Medium) .fontColor(#2A2A2A) .textAlign(TextAlign.Center) .borderRadius(12) .shadow({ radius: 4, color: #00000010, offsetX: 2, offsetY: 0 }); }, (item: number) item.toString()) } .width(4800) .height(100%) .padding({ left: 10, right: 10 }); } .scrollable(ScrollDirection.Horizontal) .scrollBar(BarState.Auto) .scrollBarColor(#86909C) .scrollBarWidth(4) .friction(0.6) .edgeEffect(EdgeEffect.None) .enableScrollInteraction(true) .width(90%) .height(220) .backgroundColor(#F5F7FA) .borderRadius(12) .onDidScroll(() this.hOffset this.hScroller.currentOffset().xOffset ?? 0) .onScrollStart(() console.info(水平滚动开始)) .onScrollStop(() console.info(水平滚动停止)) .onScrollEdge((side) console.info(触边)); Scroll() { Row({ space: 10 }) { Button(滚到最左) .width(100) .backgroundColor(#86909C) .fontColor(#FFFFFF) .onClick(() this.hScroller.scrollEdge(Edge.Start)); Button(滚到最右) .width(100) .backgroundColor(#86909C) .fontColor(#FFFFFF) .onClick(() this.hScroller.scrollEdge(Edge.End)); Button(左滑200vp) .width(100) .backgroundColor(#DDEBFF) .fontColor(#2A2A2A) .onClick(() this.hScroller.scrollBy(-200, 0)); Button(右滑200vp) .width(100) .backgroundColor(#DDEBFF) .fontColor(#2A2A2A) .onClick(() this.hScroller.scrollBy(200, 0)); } .padding(5); } .scrollable(ScrollDirection.Horizontal) .width(90%); Scroll() { Row({ space: 20 }) { Button(垂直下一页) .width(120) .backgroundColor(#F5A623) .fontColor(#FFFFFF) .onClick(() this.vScroller.scrollPage({ next: true, animation: true })); Button(水平下一页) .width(120) .backgroundColor(#F5A623) .fontColor(#FFFFFF) .onClick(() this.hScroller.scrollPage({ next: true, animation: true })); Button(垂直惯性滚动) .width(120) .backgroundColor(#F5A623) .fontColor(#FFFFFF) .onClick(() this.vScroller.fling(-3000)); Button(水平惯性滚动) .width(120) .backgroundColor(#F5A623) .fontColor(#FFFFFF) .onClick(() this.hScroller.fling(3000)); } .padding(5); } .scrollable(ScrollDirection.Horizontal) .width(90%) .margin({ top: 10, bottom: 20 }); } .width(100%) .backgroundColor(#F0F2F5) .padding(10); } .scrollable(ScrollDirection.Vertical) .scrollBar(BarState.Off) .width(100%) .height(100%) .edgeEffect(EdgeEffect.Spring); } }运行效果功能模块说明1. 页面整体滚动使用Scroll包裹最外层布局实现整页上下滚动解决内容超出屏幕无法查看的问题。关闭滚动条提升界面美观度。2. 垂直滚动模块固定容器高度内容超长自动滚动。自定义蓝色滚动条。支持回到顶部、回到底部、指定距离滑动、翻页、惯性滚动。实时显示滚动偏移量。3. 水平滚动模块强制内容宽度确保水平滚动生效。滚动条自动显示/隐藏。支持滚到最左、滚到最右、左右滑动、翻页、惯性滚动。4. 事件监听滚动开始/停止日志输出触边检测实时偏移量展示总结Scroll 是 HarmonyOS6 开发必用基础组件本文完整实现官方文档所有核心能力垂直/水平滚动滚动条自定义边缘回弹与惯性控制Scroller 手动滚动全量滚动事件监听如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力