更新记录

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

支持与赞赏

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

支付宝赞助 微信赞助

隐私、权限声明

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

无

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

无

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

无

许可协议

MIT协议

暂无用户评论。