小组件滚动效果开发最佳实践
更新时间：2025-12-19 10:40:51
背景介绍
在小组件半屏场景下，当组件自身的手势（如滑动、拖拽、缩放）与半屏容器的手势（如整体拖动、收起、展开）叠加时，容易出现冲突。本文档介绍如何实现组件手势与容器手势的协调，提供流畅的交互体验。
组件默认滚动行为
1. ScrollView
使用场景
scroll-view
是最常用的滚动组件，支持横向和纵向滚动。在半屏场景下，scroll-view
需要实现：- 滚动优先：内容可滚动时，优先响应滚动
- 触顶触底衔接：滚动到顶部/底部时，继续滑动可触发容器手势
基本用法
xhsml
<scroll-view scroll-y="{{true}}">
<view xhs:for="{{list}}" xhs:key="index">
{{item}}
</view>
</scroll-view>
滚动衔接效果
在小组件场景下，系统会自动实现滚动与容器手势的平滑衔接：
- 向上滑动：内容滚动 → 滚动到底部后继续滑动 → 容器向全屏过渡
- 向下滑动：内容滚动 → 滚动到顶部后继续滑动 → 容器向半屏过渡
完整示例
2. Swiper
使用场景
swiper
组件用于实现轮播效果，支持横向和纵向滑动。在半屏场景下，需要确保轮播手势不被容器手势干扰。基本用法
xhsml
<swiper
indicator-dots="{{true}}"
autoplay="{{true}}"
interval="{{3000}}">
<swiper-item xhs:for="{{bannerList}}" xhs:key="index">
<image src="{{item.url}}" mode="aspectFill"></image>
</swiper-item>
</swiper>
手势协调
系统会自动识别轮播区域，在轮播区域内优先响应轮播手势，避免与容器手势冲突。
完整示例
3. PickerView
使用场景
picker-view
用于实现滚轮选择器，支持多列联动。在半屏场景下，需要确保滚轮滑动不被容器手势干扰。基本用法
xhsml
<picker-view
value="{{pickerValue}}"
bindchange="onPickerChange">
<picker-view-column>
<view xhs:for="{{years}}" xhs:key="index">{{item}}</view>
</picker-view-column>
<picker-view-column>
<view xhs:for="{{months}}" xhs:key="index">{{item}}</view>
</picker-view-column>
</picker-view>
手势协调
系统会自动识别选择器区域，在选择器区域内优先响应滚轮滑动，避免误触发容器手势。
完整示例
4. MoveableArea & MoveableView
使用场景
movable-area
和 movable-view
用于实现可拖拽元素。在半屏场景下，需要确保拖拽手势不被容器手势干扰。基本用法
xhsml
<movable-area>
<movable-view
x="{{x}}"
y="{{y}}"
direction="all"
bindchange="onMovableChange">
<view class="movable-content">可拖拽元素</view>
</movable-view>
</movable-area>
手势协调
系统会自动识别可移动区域，在区域内优先响应拖拽手势，避免与容器手势冲突。
完整示例
5. Canvas
使用场景
canvas
用于绘制图形和实现复杂交互。在半屏场景下，需要确保画布内的手势操作不被容器手势干扰。基本用法
xhsml
<canvas type="2d" canvas-id="myCanvas" bindtouchstart="onCanvasTouchStart" bindtouchmove="onCanvasTouchMove" bindtouchend="onCanvasTouchEnd"> </canvas>
手势协调
系统会自动识别画布区域，在画布区域内优先响应触摸事件，确保绘图和交互的流畅性。
完整示例
6. Map
使用场景
map
用于显示地图和实现地图交互。在半屏场景下，需要确保地图的缩放、拖拽、旋转等手势不被容器手势干扰。基本用法
xhsml
<map
longitude="{{longitude}}"
latitude="{{latitude}}"
scale="{{scale}}"
markers="{{markers}}"
bindtap="onMapTap">
</map>
手势协调
系统会自动识别地图区域，在地图区域内优先响应地图手势（缩放、拖拽、旋转），避免误触发容器手势。
完整示例
7. TouchInterceptorContainerView
使用场景
touch-interceptor-container-view
是一个专门用于拦截并消费触摸事件的轻量级容器。当需要明确指定某个区域优先消费手势时，可以使用该组件。基本用法
xhsml
<xhs-touch-interceptor-container-view class="interceptor-area">
<!-- 需要优先消费手势的内容 -->
<view class="custom-gesture-handler">
<!-- 自定义手势处理逻辑 -->
</view>
</xhs-touch-interceptor-container-view>
使用场景
- 自定义手势区域：需要实现特殊手势交互的区域
- 手势优先级控制：明确指定某个区域优先消费手势
- 复杂交互场景：需要精细控制手势分发的场景
完整示例
核心原理
工作原理
组件库通过感知组件的位置和滚动状态，在合适的时机协调手势分发：
- 组件自动注册：可滚动组件自动注册到手势协调系统
- 状态感知：系统实时感知组件内的的滚动状态
- 优先级兼容：其中ScrollView组件，会在内容触达边界时，自动交换给容器本身响应滚动
自动支持
以下组件在小组件场景下会自动支持手势协调，无需额外配置：
最佳实践
1. ScrollView 触顶触底衔接
在小组件场景下，
scroll-view
会自动支持触顶触底衔接功能，无需额外配置：2. 嵌套滚动场景
当存在嵌套滚动时，系统会自动识别每个滚动区域，在各自区域内优先响应相应组件的手势：
3. 手势优先级控制
使用
touch-interceptor-container-view
明确控制手势优先级：4. 性能优化
总结
通过手势协调机制，我们可以实现组件手势与容器手势的智能协调，提供流畅的交互体验。
遵循本文档的最佳实践，可以轻松实现流畅的半屏交互体验。
该文档是否对您有帮助？