鸿蒙平台 uni-app x scroll-view 嵌套滚动冲突解决方

鸿蒙专家

在鸿蒙平台使用 uni-app x 开发时，scroll-view 是聊天记录、商品列表、Tab 切换、横向轮播和下拉刷新等场景的常用容器。鸿蒙从 4.61 版本开始支持该组件。它看起来简单，但嵌套滚动冲突、下拉刷新元素位置、废弃属性等问题在鸿蒙上需要单独适配。

一、scroll-view 核心能力
scroll-view 支持横向滚动、竖向滚动、下拉刷新和嵌套滚动。滚动方向由 direction 控制：none 禁止滚动，all 横竖同时可滚动，horizontal 横向，vertical 竖向。滚动位置、阈值、回弹效果和下拉刷新等通过属性配置。事件对象为 UniScrollEvent，可以通过 @scroll、@scrollend 等获取滚动位置。基础竖向滚动、横向滚动、下拉刷新、上拉加载、滚动到指定位置等场景，都是围绕这些属性组合实现。其中上拉加载监听 @scrolltolower，配合 :lower-threshold='100' 设置触发距离；滚动到指定位置可用 :scroll-top 或 scroll-into-view，配合 :scroll-with-animation='true' 实现动画。

二、鸿蒙平台专属适配
自定义下拉刷新元素的位置在鸿蒙上与其他平台不同。Android 和 iOS 平台，自定义下拉刷新元素不能放在 scroll-view 的首个子元素位置；鸿蒙平台则要放在最后一个子元素的位置，否则顶部可能出现空白区域。

2. <scroll-view refresher-default-style='none' :refresher-enabled='true'>
3.   <view v-for='i in 20'>...</view>
4.   <view slot='refresher'>
5.     <text>下拉刷新</text>
6.   </view>
7. </scroll-view>

复制代码

嵌套滚动冲突可以通过嵌套模式解决。外层 scroll-view 设置 type='nested'，子节点只能放 nested-scroll-header 和 nested-scroll-body；内层 scroll-view 设置 associative-container='nested-scroll-view'。

2. <scroll-view type='nested'>
3.   <nested-scroll-header>
4.     <view>头部</view>
5.   </nested-scroll-header>
6.   <nested-scroll-body>
7.     <scroll-view associative-container='nested-scroll-view'>
8.       <view>内容</view>
9.     </scroll-view>
10.   </nested-scroll-body>
11. </scroll-view>

复制代码

嵌套滚动策略为：向下滚动（手指上滑）先滚外层，再滚内层；向上滚动（手指下滑）先滚内层，再滚外层。

除了嵌套模式，鸿蒙平台还支持嵌套滚动协商。通过 nested-scroll-child='listview' 关联子元素，监听 @startnestedscroll、@nestedprescroll、@stopnestedscroll 三个事件。@startnestedscroll 在子元素开始滚动时触发，return true 建立协商；@nestedprescroll 在子元素滚动时通过 consumed(x,y) 告知消耗量；@stopnestedscroll 在子元素滚动结束时触发。

2. <scroll-view nested-scroll-child='listview'
3.             @startnestedscroll='onStartNestedScroll'
4.             @nestedprescroll='onNestedPreScroll'
5.             @stopnestedscroll='onStopNestedScroll'>
6.   <list-view id='listview' custom-nested-scroll='true'>
7.     ...
8.   </list-view>
9. </scroll-view>

复制代码

与鸿蒙原生 Scroll 组件对比，原生写法如下：

2. Scroll() {
3.   Column() {
4.     ForEach(this.list, (item: string) => {
5.       Text(item).fontSize(16).padding(15)
6.     })
7.   }
8. }
9. .scrollable(ScrollDirection.Vertical)
10. .scrollBar(BarState.On)

复制代码

uni-app x 的 scroll-view 功能更丰富。下拉刷新、嵌套滚动、scroll-into-view 这些功能在原生 Scroll 上都需要自己实现。

三、踩坑与总结
不要使用已废弃的 scroll-x 和 scroll-y 属性，改用 direction 属性。例如竖向滚动写 direction='vertical'，横向滚动写 direction='horizontal'。在鸿蒙平台开发时，重点检查自定义下拉刷新元素是否放在末尾、嵌套滚动是否按 nested 模式配置，以及是否误用了废弃属性。掌握这些差异后，聊天列表、商品流、Tab 切换等滚动场景可以更稳定地落地。