更新记录

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(常规问题,群友互助,作者可能在线)
  • ***(很少在线)
  • 插件市场评论区:回复不及时,仅适合不着急的留言反馈

支持与赞赏

如果你觉得本插件解决了你的问题,可以考虑支持作者:

支付宝赞助 微信赞助

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议

暂无用户评论。