更新记录
1.0.0(2026-11-17) 下载此版本
新增
- 首次发布
- 返回顶部组件,滚动超过
threshold阈值自动出现,点击平滑回顶 right/bottom自定义悬浮位置,size控制按钮直径,均以 rpx 为单位color/backgroundColor直接配色,text支持图标下方文字,showIcon可只留文字- 点击默认调用
uni.pageScrollTo回顶,usePageScroll="false"可适配 scroll-view 场景自行处理 - 显隐带缩放淡入淡出过渡,隐藏态
pointer-events: none不拦截页面点击 - 箭头基于 CSS 边框旋转实现,无图标字体、图片依赖
平台兼容性
uni-app(5.0)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| - | √ | √ | √ | √ | - | √ | √ | √ |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| √ | √ | √ | - | - | - | - | - | - | - | - | - |
ry-backtop 返回顶部
返回顶部组件:传入页面或 scroll-view 的实时滚动距离,超过 threshold 阈值自动出现,点击平滑回到顶部,显隐带缩放淡入淡出过渡。位置、尺寸、颜色、文字全部可配,一套 API 覆盖长列表、详情页、设置页等所有需要快速回顶的场景。
需要 uni-app x(uvue)版本请使用 ry-backtop-x。
安装
三种方式任选其一。
方式一:uni_modules 导入(推荐)
通过 HBuilderX 从插件市场导入 uni_modules,组件位于 uni_modules/ry-backtop/components/ry-backtop/ 下,easycom 自动注册,无需 import。
方式二:源码放到 components 目录
下载源码后,把组件放到项目的 components/ry-backtop/ry-backtop.vue,保持该目录结构,即符合 easycom 默认规则,自动注册。
方式三:手动导入
组件放在其他任意位置时,显式导入注册即可,与 easycom 不冲突(显式导入优先生效):
import ryBacktop from '@/components/ry-backtop/ry-backtop.vue'
使用示例
页面滚动
通过页面 onPageScroll 实时传入滚动距离,点击由组件内部调用 uni.pageScrollTo 回顶:
<template>
<!-- 1. 最简用法 -->
<ry-backtop :scroll-top="scrollTop"></ry-backtop>
<!-- 2. 带文字、自定义配色与尺寸 -->
<ry-backtop :scroll-top="scrollTop" text="顶部" :size="120" background-color="#07c160"></ry-backtop>
<!-- 3. 自定义悬浮位置与显示阈值 -->
<ry-backtop :scroll-top="scrollTop" :right="60" :bottom="200" :threshold="100"></ry-backtop>
<!-- 4. 只留文字不带箭头 -->
<ry-backtop :scroll-top="scrollTop" text="回顶部" :show-icon="false"></ry-backtop>
</template>
<script setup>
import { ref } from 'vue'
import { onPageScroll } from '@dcloudio/uni-app'
const scrollTop = ref(0)
onPageScroll((opts) => {
scrollTop.value = opts.scrollTop
})
</script>
scroll-view 场景
scroll-view 内使用时,通过 @scroll 事件传入滚动距离,点击回顶改由 @click 自行处理:
<template>
<scroll-view scroll-y @scroll="">
<!-- 长内容 -->
</scroll-view>
<ry-backtop :scroll-top="scrollTop" :use-page-scroll="false" @click="onBacktop"></ry-backtop>
</template>
<script setup>
import { ref } from 'vue'
const scrollTop = ref(0)
const scrollPos = ref(0)
const = (e) => {
scrollTop.value = e.detail.scrollTop
}
const onBacktop = () => {
// 先同步为当前位置再置 0,解决相同值不触发滚动的问题
scrollPos.value = scrollTop.value
setTimeout(() => {
scrollPos.value = 0
}, 50)
}
</script>
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(容器滚动)实时传入,组件自身不监听滚动,避免多端差异threshold与scroll-top单位为 px(滚动事件返回值),right/bottom/size单位为 rpx- 隐藏态通过
pointer-events: none放行点击,不会遮挡页面右下角内容 - 箭头与文字基于 CSS 边框与文本绘制,无图标字体依赖
技术支持
- 微信:howe1144(一定在线,紧急问题首选)
- QQ 群:415367029(常规问题,群友互助,作者可能在线)
- ***(很少在线)
- 插件市场评论区:回复不及时,仅适合不着急的留言反馈
支持与赞赏
如果你觉得本插件解决了你的问题,可以考虑支持作者:
| 支付宝赞助 | 微信赞助 |
|---|---|
![]() |
![]() |

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


下载 10
赞赏 0
下载 12773538
赞赏 1960
赞赏
京公网安备:11010802035340号