鸿蒙UI开发之滚动组件overscroll-decor安装和使用介绍
overscroll-decor是鸿蒙UI开发中用于实现过度滚动回弹动画的开源库，兼容性广且轻量级。通过ohpminstall@ohos/overscroll-decor安装，以GridView为例，利用OverScrollDecor.Model设置属性即可获得类似iOS的丝滑回弹体验，支持自定义滚动行为和视觉效果。
在鸿蒙UI开发中，滚动列表的交互体验一直是开发者关注的重点。今天要介绍的overscroll-decor，就是专门解决过度滚动（overscroll）动画效果的一个开源库。它能让你的RecyclerView、ListView、ScrollView、GridView等组件拥有类似iOS的丝滑回弹体验，而且几乎可以套用到所有Android本机可滚动视图上——当然，在鸿蒙环境下，它的用法大同小异。
功能特点
先聊聊这个库的亮点。几个关键点值得拿出来说：
- 兼容性广：支持Android API 14及以上版本，覆盖了绝大多数设备。
- 轻量级：体积小，没有任何额外依赖，对应用性能几乎零影响。
- 可扩展性强：允许开发者完全自定义过度滚动的行为和视觉效果，想怎么玩都行。
- 社区支持：作为开源项目，有活跃的社区和持续的更新维护，遇到问题不至于抓瞎。
下载安装
安装方式很简单，一条命令搞定：
ohpm install @ohos/overscroll-decor
主要接口列表
具体有哪些接口可用？下面这个表格列得清清楚楚，方便你快速查阅：
| 接口 | 方法说明 |
|---|---|
| getHeight() | 获取组件高度 |
| setHeight() | 设置组件高度 |
| getWidth() | 获取组件宽度 |
| setWidth() | 设置组件宽度 |
| getMargin() | 获取组件边缘度 |
| setMargin() | 设置组件边缘度 |
| getOrientation() | 获取组件方向 |
| setOrientation() | 设置组件方向 |
| isScrollBar() | 判断是否是滚动条 |
| setScrollBar() | 设置滚动条 |
| isOverScrollBounceEffect() | 是否有滚动反弹效果 |
| setOverScrollBounceEffect() | 设置滚动反弹效果 |
| isUpOverScroll() | 是否向上滚动 |
| setUpOverScroll() | 设置向上滚动 |
| getOffsetX() | 获取离开X的值 |
| setOffsetX() | 设置离开X的值 |
| getOffsetY() | 获取离开Y的值 |
| setOffsetY() | 设置离开Y的值 |
| getTextColor() | 获取字体颜色 |
| setTextColor() | 设置字体颜色 |
| getDragColorTop() | 获取拖动顶部颜色 |
| setDragColorTop() | 设置拖动顶部颜色 |
使用说明
接下来看看具体怎么用。所有滚动容器视图的使用方法都大同小异，这里以GridView为例，分四步走：
1、初始化：实例化OverScrollDecor.Model 对象
private model: OverScrollDecor.Model = new OverScrollDecor.Model()
2、属性设置：通过Model类对象设置UI属性来自定义所需风格
private aboutToAppear() {
this.model
.setUpOverScroll(true)
.setOrientation(OverScrollDecor.ORIENTATION.VERTICAL)
.setOverScrollBounceEffect(true)
.setScrollBar(true)
.setWidth("100%")
.setHeight("80%")
}
3、子组件绘制：
@Builder SpecificChild() {
Column({ space: 10 }) {
......
}.width('100%')
}
4、界面绘制：
build() {
Stack({ alignContent: Alignment.TopStart }) {
......
OverScrollDecor({ model: this.model!!, child: () => { this.SpecificChild() } })
......
}
属性说明
最后再梳理一下默认属性，方便你快速上手时调整：
- 滚动组件高：默认
px2vp(2340)，即mHeight: number | string = px2vp(2340) - 滚动组件宽：默认
px2vp(lpx2px(720))，即mWidth: number | string = px2vp(lpx2px(720)) - 滚动组件外边距：默认16，即
mMargin: number = 16 - 组件滚动方向：默认VERTICAL，即
mOrientation: ORIENTATION = 0 - 滚动条设置：默认true，即
mScrollBar: boolean = true - 边缘滚动效果设置：默认false，即
mOverScrollBounceEffect: boolean = false - 滚动设置：默认true，即
mUpOverScroll: boolean = true
这些默认值基本能满足大多数场景，如果你需要更个性化的交互反馈，直接修改对应属性即可。整体而言，overscroll-decor上手成本很低，效果却很讨喜，值得在你的鸿蒙项目里试一试。
Photoshop 2026 是 Adobe 推出的专业图像处理与视觉设计软件，支持 Windows、macOS 和 iPad 等平台，广泛应用于摄影修图、电商设计、平面海报、数字绘画及视觉合成等创作场景。
Blender 是一款免费开源、跨平台的专业 3D 创作软件，集建模、动画、渲染、视频编辑与视觉合成等功能于一体，广泛应用于影视动画、游戏设计和建筑可视化等领域。软件支持 Cycles 物理渲染器与 Eevee 实时渲染引擎，并提供多边形建模、骨骼绑定、物理模拟等专业工具。Blender 兼容 Windows、macOS 和 Linux 系统，安装包轻巧、运行流畅，依托活跃的全球开发者社区持续更新，是从初学者到专业创作者都值得选择的正版 3D 创作工具。
极度公式是一款跨平台专业LaTeX公式识别编辑软件，支持OCR公式识别和多平台编辑。和使用说明，避免使用，享受完整功能与稳定支持。做扫描整理、文字提取和表格转换时，它能把识别后的处理步骤接得更顺，资料录入这类场景会省下不少时间。
一款文字处理软件，一种订阅式的跨平台办公软件，基于云平台提供多种服务，通过将 Excel 和 Outlook 等应用与 OneDrive 和 Microsoft Teams 等强大的云服务相结合，Office 365 可让任何人使用任何设备随时随地创建和共享内容。
CodeExpander 是一款快捷短语输入增强工具，通过键入缩写自动展开为自定义文段，提升工作效率。任务管理和过程控制会更完整，持续下载、批量同步或需要稳定传输流程的场景会更适合它。
Mountain Duck 是一款能将多个网盘挂载到本地的工具，像本地磁盘一样使用网盘。清理链路的完整性会更好一些，做应用卸载、残留处理和空间整理时，通常能少走很多手动排查步骤。
Photoshop 2026 是 Adobe 推出的专业图像处理与视觉设计软件，支持 Windows、macOS 和 iPad 等平台，广泛应用于摄影修图、电商设计、平面海报、数字绘画及视觉合成等创作场景。
Blender 是一款免费开源、跨平台的专业 3D 创作软件，集建模、动画、渲染、视频编辑与视觉合成等功能于一体，广泛应用于影视动画、游戏设计和建筑可视化等领域。软件支持 Cycles 物理渲染器与 Eevee 实时渲染引擎，并提供多边形建模、骨骼绑定、物理模拟等专业工具。Blender 兼容 Windows、macOS 和 Linux 系统，安装包轻巧、运行流畅，依托活跃的全球开发者社区持续更新，是从初学者到专业创作者都值得选择的正版 3D 创作工具。
极度公式是一款跨平台专业LaTeX公式识别编辑软件，支持OCR公式识别和多平台编辑。和使用说明，避免使用，享受完整功能与稳定支持。做扫描整理、文字提取和表格转换时，它能把识别后的处理步骤接得更顺，资料录入这类场景会省下不少时间。
一款文字处理软件，一种订阅式的跨平台办公软件，基于云平台提供多种服务，通过将 Excel 和 Outlook 等应用与 OneDrive 和 Microsoft Teams 等强大的云服务相结合，Office 365 可让任何人使用任何设备随时随地创建和共享内容。
Wise Folder Hider Pro 是一款专业级文件和文件夹隐藏加密软件，为私密数据添加多重保护。高频操作更强调就近处理，浏览、整理和跨目录移动文件时，来回切换和重复点击都会少很多。
CodeExpander 是一款快捷短语输入增强工具，通过键入缩写自动展开为自定义文段，提升工作效率。任务管理和过程控制会更完整，持续下载、批量同步或需要稳定传输流程的场景会更适合它。