更新记录
1.0.0(2026-11-17) 下载此版本
新增
- 首次发布
- 返回顶部组件(uni-app x / uvue 版),滚动超过
threshold阈值自动出现,点击平滑回顶 right/bottom自定义悬浮位置,size控制按钮直径,均以 rpx 为单位color/backgroundColor直接配色,text支持图标下方文字,showIcon可只留文字- 点击默认调用
uni.pageScrollTo回顶,usePageScroll="false"可适配 scroll-view 场景自行处理 - 箭头基于 CSS 边框旋转实现,无图标字体、图片依赖,兼容 App-Android / iOS / 鸿蒙
平台兼容性
uni-app x(5.0)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √ |
ry-backtop-x 返回顶部(uni-app x)
返回顶部组件(uni-app x / uvue 版):传入页面或 scroll-view 的实时滚动距离,超过 threshold 阈值自动出现,点击平滑回到顶部。位置、尺寸、颜色、文字全部可配,一套 API 覆盖长列表、详情页、设置页等所有需要快速回顶的场景。
需要 uni-app(Vue3)版本请使用 ry-backtop。
安装
三种方式任选其一。
方式一:uni_modules 导入(推荐)
通过 HBuilderX 从插件市场导入 uni_modules,组件位于 uni_modules/ry-backtop-x/components/ry-backtop/ 下,easycom 自动注册,无需 import。
方式二:源码放到 components 目录
下载源码后,把组件放到项目的 components/ry-backtop/ry-backtop.uvue,保持该目录结构,即符合 easycom 默认规则,uni-app x 自动注册。
方式三:手动导入
组件放在其他任意位置时,显式导入注册即可,与 easycom 不冲突(显式导入优先生效):
import ryBacktop from '@/components/ry-backtop/ry-backtop.uvue'
使用示例
页面滚动(Web 端)
uni-app x 的 Web 端页面自然滚动,通过 onPageScroll 实时传入滚动距离,点击由组件内部调用 uni.pageScrollTo 回顶:
<template>
<ry-backtop :scroll-top="scrollTop"></ry-backtop>
</template>
<script setup>
import { ref } from 'vue'
const scrollTop = ref(0)
onPageScroll((opts : OnPageScrollOptions) => {
scrollTop.value = opts.scrollTop
})
</script>
scroll-view 场景(App / 鸿蒙端推荐)
App 端页面滚动由页面根节点的 scroll-view 模拟,滚动容器场景统一推荐此模式:组件放在 scroll-view 外层,@scroll 实时传入滚动距离,use-page-scroll="false" 关闭内部回顶,改由 @click 自行控制 scroll-view 的 scroll-top:
<template>
<view class="page">
<scroll-view scroll-y :scroll-top="toTop" :scroll-with-animation="true" @scroll="">
<!-- 长内容 -->
</scroll-view>
<ry-backtop :scroll-top="scrollTop" :use-page-scroll="false" @click="backToTop"></ry-backtop>
</view>
</template>
<script setup>
import { ref, nextTick } from 'vue'
const scrollTop = ref(0)
const toTop = ref(0)
const = (e : ScrollEvent) => {
scrollTop.value = e.detail.scrollTop
}
const backToTop = () => {
// 先同步为当前位置再置 0,解决 view 层不同步导致相同值不滚动的问题
toTop.value = scrollTop.value
nextTick(() => {
toTop.value = 0
})
}
</script>
更多自定义
<template>
<!-- 带文字、自定义配色与尺寸 -->
<ry-backtop :scroll-top="scrollTop" text="顶部" :size="120" background-color="#07c160"></ry-backtop>
<!-- 自定义悬浮位置与显示阈值 -->
<ry-backtop :scroll-top="scrollTop" :right="60" :bottom="200" :threshold="100"></ry-backtop>
<!-- 只留文字不带箭头 -->
<ry-backtop :scroll-top="scrollTop" text="回顶部" :show-icon="false"></ry-backtop>
</template>
API
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| scroll-top | Number | 0 | 当前滚动距离(页面 onPageScroll 或 scroll-view @scroll 事件提供,单位 px) |
| threshold | Number | 200 | 显示阈值:滚动距离超过该值(px)才显示按钮 |
| right | Number | 40 | 距页面右侧距离(rpx) |
| bottom | Number | 60 | 距页面底部距离(rpx) |
| size | Number | 96 | 按钮直径(rpx) |
| text | String | '' | 图标下方文字,空串不显示 |
| color | String | #ffffff | 图标与文字颜色 |
| background-color | String | #2f6bff | 背景颜色 |
| show-icon | Boolean | true | 是否显示向上箭头图标 |
| duration | Number | 300 | 点击回顶的滚动动画时长(ms) |
| use-page-scroll | Boolean | true | 点击时是否自动调用 uni.pageScrollTo 回顶,scroll-view 场景设为 false 改由 @click 自行处理 |
| z-index | Number | 99 | 悬浮层级 |
Events
| 事件 | 说明 |
|---|---|
| click | 点击按钮时触发 |
注意事项
scroll-top必须由页面onPageScroll(页面滚动)或 scroll-view@scroll(容器滚动)实时传入,组件自身不监听滚动,避免多端差异- App 端页面滚动由页面根节点的 scroll-view 模拟:App / 鸿蒙端推荐 scroll-view 模式,并把组件放在 scroll-view 外层兄弟节点;Web 端可直接用页面滚动模式
threshold与scroll-top单位为 px(滚动事件返回值),right/bottom/size单位为 rpx- 箭头与文字基于 CSS 边框与文本绘制,无图标字体依赖,鸿蒙端无需额外配置
技术支持
- 微信:howe1144(一定在线,紧急问题首选)
- QQ 群:415367029(常规问题,群友互助,作者可能在线)
- ***(很少在线)
- 插件市场评论区:回复不及时,仅适合不着急的留言反馈
支持与赞赏
如果你觉得本插件解决了你的问题,可以考虑支持作者:
| 支付宝赞助 | 微信赞助 |
|---|---|
![]() |
![]() |

收藏人数:
下载插件并导入HBuilderX
赞赏(0)


下载 3
赞赏 0
下载 12771027
赞赏 1959
赞赏
京公网安备:11010802035340号