鸿蒙原生 ArkTS 布局精讲Scroll 方向控制垂直 / 水平 / 双向一、引言在移动端应用开发中滚动Scroll是最基础也最频繁使用的交互方式之一。无论是刷不完的朋友圈、横向滑动的商品推荐栏还是横纵双向自由探索的图片墙其底层都离不开 Scroll 容器的支持。HarmonyOS NEXT 自 API 24 起ArkUI 框架的 Scroll 组件日趋成熟在滚动性能、手势流畅度、嵌套协调等方面均有显著提升。然而在实际开发中很多开发者对 Scroll 的方向控制仍然存在认知盲区如何正确设置滚动方向为什么有时内容溢出了却无法滚动ScrollDirection.Vertical、Horizontal和FREE有什么区别双向滚动场景下子组件的宽高应该如何设置本文将以一个完整的示例应用为主线手把手带你吃透 Scroll 方向控制。无论你是刚入门鸿蒙开发的新手还是有一定经验想查漏补缺的进阶者这篇文章都能让你有所收获。二、Scroll 组件核心概念2.1 什么是 ScrollScroll是 ArkUI 提供的一个可滚动容器组件它允许在有限的视口Viewport内容纳超出自身尺寸的内容用户通过手指拖拽即可查看被遮挡的部分。┌─────────────────────┐ ← Scroll 容器视口固定宽高 │ 可见区域 │ │ ┌───────────────┐ │ │ │ Item 1 │ │ │ │ Item 2 │ │ │ │ Item 3 │ │ ← 实际内容超出视口需滚动查看 │ │ ... │ │ │ └───────────────┘ │ │ ↓ 拖动 │ └─────────────────────┘关键约束Scroll 只能包含一个直接子组件通常使用Column垂直、Row水平或Flex双向作为内容容器再在该容器中放置多个子元素。2.2 核心 APIScroll(scroller?:Scroller).scrollable(value:ScrollDirection)⚠️注意在 API 24 中滚动方向使用.scrollable()方法不是.scrollDirection()。这是新手最容易踩的坑之一。2.3 ScrollDirection 枚举API 24枚举值说明典型场景ScrollDirection.Vertical仅垂直方向滚动新闻列表、聊天记录、评论流ScrollDirection.Horizontal仅水平方向滚动横向标签栏、商品卡片轮播ScrollDirection.FREE自由双向滚动API 20图片网格、地图、画布ScrollDirection.None禁止滚动固定内容区域2.4 Scroll 的其他常用属性属性用途示例值scrollBar滚动条显示策略BarState.Auto / On / OffscrollBarColor滚动条颜色Color.GrayscrollBarWidth滚动条宽度6edgeEffect边缘回弹效果EdgeEffect.Spring / Fade / NoneenableScrollInteraction是否允许滚动交互true / falsefriction滚动摩擦系数0.6值越小越滑三、实战构建 Scroll 方向演示应用下面通过一个完整的示例来直观理解三种方向配置。页面整体结构如下┌──────────────────────────────────┐ │ Scroll 方向控制演示 │ │ 当前方向描述文字 │ ├────────┬────────┬───────────────┤ │ 垂直方向│ 水平方向│ 双向滚动 │ ← Tabs 切换 ├────────┴────────┴───────────────┤ │ ┌──────────────────────────┐ │ │ │ Scroll 内容区域 │ │ │ │ 拖拽查看效果 │ │ │ └──────────────────────────┘ │ │ 布局要点总结 │ │ 核心 API │ ← 信息卡片 └──────────────────────────────────┘3.1 数据模型与色块组件我们首先定义一个ColorItem接口来描述每个色块的数据结构interfaceColorItem{label:string;// 色块编号如 V-01bgColor:string;// 背景色width:number;// 色块宽度vpheight:number;// 色块高度vp}编写一个工具方法批量生成色块数据每个色块被赋予不同的背景色和编号前缀V / H / B 分别代表三种方向buildColorItems(prefix:string,count:number):ColorItem[]{constitems:ColorItem[][];constcolors[#FF6B6B,#FFA94D,#FFD43B,#69DB7C,#38D9A9,#4DABF7,#748FFC,#9775FA,#F06595,#FF8787,#FFC078,#FCC419,#8CE99A,#66D9E8,#74C0FC,#91A7FF,#B197FC,#F783AC,#FF8A8A,#FFD399];for(leti0;icount;i){items.push({label:${prefix}-${String(i1).padStart(2,0)},bgColor:colors[i%colors.length],width:160,height:80});}returnitems;}色块渲染则抽离为一个Builder方法方便在三个 Tab 中复用BuilderColorBlock(item:ColorItem){Column(){Text(item.label).fontSize(16).fontColor(Color.White).fontWeight(FontWeight.Bold)Text(拖动可滚动).fontSize(10).fontColor(rgba(255,255,255,0.7)).margin({top:4})}.width(item.width).height(item.height).backgroundColor(item.bgColor).borderRadius(8).justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center).shadow({radius:4,color:rgba(0,0,0,0.15),offsetY:2})}3.2 垂直滚动ScrollDirection.Vertical原理当子组件的height超过 Scroll 容器的height时且方向设置为Vertical用户即可在纵向上拖拽滚动。Scroll(this.verticalScroller){Column({space:12}){ForEach(this.buildColorItems(V,20),(item:ColorItem){this.ColorBlock(item)})}.width(100%).height(2000)// ★ 远超 Scroll 容器的视口高度300vp}.scrollable(ScrollDirection.Vertical)// 设置为垂直滚动.width(100%).height(300).border({width:1,color:#007DFF,style:BorderStyle.Solid}).borderRadius(12).padding(8).backgroundColor(#F5F9FF)要点说明外层Scroll的height设为300vp作为「视口」高度。内层Column的height设为2000vp远超视口高度产生溢出。通过.scrollable(ScrollDirection.Vertical)显式声明方向。垂直滚动是 Scroll 的默认方向不写.scrollable()也默认为垂直。视觉表现20 个彩色方块纵向排列用户上下拖动即可依次查看 V-01 到 V-20。真实场景映射微信朋友圈的时间线、微博信息流、商品评论列表——这些都是典型的垂直滚动场景。3.3 水平滚动ScrollDirection.Horizontal原理当子组件的width超过 Scroll 容器的width时且方向设置为Horizontal用户即可在横向上拖拽滚动。Scroll(this.horizontalScroller){Row({space:12}){ForEach(this.buildColorItems(H,20),(item:ColorItem){this.ColorBlock(item)})}.width(4000)// ★ 远超 Scroll 容器的宽度.height(100%)}.scrollable(ScrollDirection.Horizontal)// 设置为水平滚动.width(100%).height(300).border({width:1,color:#00A86B,style:BorderStyle.Solid}).borderRadius(12).padding(8).backgroundColor(#F0FFF5)要点说明使用Row作为子容器所有色块水平排列。Row的width设为4000vp而 Scroll 容器宽度为父容器宽产生水平溢出。注意Row不需要显式设置宽度约束让子元素内容撑开即可。.scrollable(ScrollDirection.Horizontal)声明水平方向。视觉表现20 个色块排成一行用户左右拖动滚动条在底部浮现。真实场景映射淘宝/京东顶部的分类导航栏、音乐 App 的推荐歌曲横滑区域、股票 App 的 K 线时间轴。3.4 双向自由滚动ScrollDirection.FREE原理当子组件的width和height同时超过 Scroll 容器的对应尺寸时且方向设置为FREE用户即可在横纵两个方向上自由滚动。⚠️重要演进在 API 9 之前双向滚动使用ScrollDirection.Free已废弃自 API 20 起推荐使用ScrollDirection.FREE。注意大小写差异。Scroll(this.bothScroller){Flex({direction:FlexDirection.Row,wrap:FlexWrap.Wrap,// ★ 自动换行产生垂直方向溢出justifyContent:FlexAlign.Start,alignContent:FlexAlign.Start,}){ForEach(this.buildColorItems(B,40),(item:ColorItem){this.ColorBlock(item)})}.width(2000)// ★ 宽高均远超 Scroll 容器.height(2000)}.scrollable(ScrollDirection.FREE)// 自由双向滚动.width(100%).height(300).border({width:1,color:#FF6B35,style:BorderStyle.Solid}).borderRadius(12).padding(8).backgroundColor(#FFF8F0)要点说明使用FlexFlexWrap.Wrap实现自动换行的网格布局同时产生水平和垂直方向的溢出。Flex的width(2000)和height(2000)均远超 Scroll 容器尺寸这是触发双向滚动的必要条件。40 个色块以 4 行 × 10 列的网格排列行满自动换行。.scrollable(ScrollDirection.FREE)声明为自由方向。常见误区错误写法问题后果只设width(2000)height 用默认值仅在水平方向溢出只触发水平滚动只设height(2000)width 用默认值仅在垂直方向溢出只触发垂直滚动两者都不超 Scroll 尺寸无溢出根本无法滚动使用ScrollDirection.Free小写 fAPI 9 已废弃编译器警告真实场景映射手机相册的网格视图、地图应用的缩放平移、Excel/表格数据查看器。3.5 用 Tabs 整合三种方向为了让三种方向在同一页面中直观对比我们使用Tabs组件进行切换Tabs({index:this.currentTabIndex}){TabContent(){/* 垂直滚动 */}.tabBar(垂直方向)TabContent(){/* 水平滚动 */}.tabBar(水平方向)TabContent(){/* 双向滚动 */}.tabBar(双向滚动)}// ★ onChange 作为链式方法不是构造参数.onChange((index:number){this.currentTabIndexindex;})⚠️API 24 注意onChange事件需要通过链式调用绑定而不是放在Tabs的构造参数对象中。这是很多从低版本迁移上来的开发者容易出错的地方。每个 Tab 切换时顶部的描述文字也会同步变化getDirectionDescription():string{return[垂直滚动 — 内容在纵向上超出容器高度时触发滚动,水平滚动 — 内容在横向上超出容器宽度时触发滚动,双向滚动 — 内容在横向和纵向均超出容器尺寸时触发滚动][this.currentTabIndex];}四、滚动控制器Scroller进阶每个 Scroll 绑定一个Scroller实例可以实现编程式滚动控制。注意在 API 23 中Scroller已内置到全局作用域无需 import。privatescroller:ScrollernewScroller();// 滚动到顶部this.scroller.scrollEdge(Edge.Top);// 滚动到底部this.scroller.scrollEdge(Edge.Bottom);// 滚动到指定偏移量带动画this.scroller.scrollTo({xOffset:0,yOffset:500});// 获取当前偏移量constoffsetthis.scroller.currentOffset();console.info(x:${offset.xOffset}, y:${offset.yOffset});// 惯性滑动this.scroller.fling(-3000);五、常见踩坑记录❌ 问题 1内容溢出了但无法滚动现象子组件明明比 Scroll 大但拖不动。原因有两种可能——方向设置错误期望水平滚动但忘了写.scrollable(ScrollDirection.Horizontal)默认垂直方向自然无法水平拖动。子组件尺寸没有真正超出有时子组件设置了width(100%)但父容器宽度等于屏幕宽导致没有溢出。解决水平滚动确认内层子组件width超过 Scroll 宽度双向滚动确认width和height均超过。❌ 问题 2ScrollDirection.Both编译报错现象编译器报错Property Both does not exist on type typeof ScrollDirection。原因Both不是合法值。API 20 中双向滚动使用ScrollDirection.FREE全大写。// ✅ 正确.scrollable(ScrollDirection.FREE)// ❌ 错误写法.scrollable(ScrollDirection.Both)// 不存在.scrollable(ScrollDirection.Free)// API 9 已废弃❌ 问题 3.scrollDirection()方法不存在现象编译器报错Property scrollDirection does not exist on type ScrollAttribute。原因正确的方法名是.scrollable()不是.scrollDirection()。❌ 问题 4Tabs 的onChange不生效现象在 Tabs 构造参数中传onChange函数编译器报错。原因API 24 中TabsOptions不再将onChange作为构造属性。// ✅ 正确Tabs({index:0}){/* ... */}.onChange((index){/* ... */})// ❌ 错误Tabs({index:0,onChange:(i){}}){}❌ 问题 5Scroller导入报错现象import { Scroller } from kit.ArkUI报has no exported member。原因API 23 中Scroller类型已内置到全局作用域无需显式导入。// ✅ 无需 import直接使用privatescroller:ScrollernewScroller();六、核心知识速查表方向方法子容器溢出条件垂直.scrollable(Vertical)Columnheight 容器高度水平.scrollable(Horizontal)Rowwidth 容器宽度双向.scrollable(FREE)Flex等width且height均超出避坑清单✅ 方法名是scrollable()不是scrollDirection()✅ 双向滚动用ScrollDirection.FREE不是Both✅ Scroller 全局可用无需 import✅ Tabs 的onChange用链式不用构造参数✅ 子容器宽/高必须超过Scroll 容器对应尺寸✅ 每个 Scroll 绑定独立的 Scroller 实例七、进阶方向掌握了 Scroll 方向控制之后可以进一步探索Scroll LazyForEach百万级长列表的懒加载渲染Scroll Grid构建可横向滚动的网格布局嵌套滚动通过nestedScroll属性协调父子滚动组件的联动自定义下拉刷新基于onWillScroll/onDidScroll事件实现滚动条美化通过scrollBarColor和scrollBarWidth调优视觉风格八、参考资料HarmonyOS 开发者文档 — Scroll 组件HarmonyOS 开发者文档 — Tabs 组件HarmonyOS 开发者文档 — ScrollDirection 枚举OpenHarmony GitHub — Scroll 源码本文所有代码已在 HarmonyOS NEXT API 24 环境下编译通过。如果你在实践过程中遇到问题欢迎留言交流。