BackTop 返回顶部

该组件一个用于长页面，滑动一定距离后，出现返回顶部按钮，方便快速返回顶部的场景。

平台差异说明

App(vue)	App(nvue)	H5	微信小程序
√	√	√	√

基本使用

由于返回顶部需要实时监听滚动条的位置，从而判断返回的按钮该出现还是隐藏，由于组件无法得知页面的滚动条信息，只能在页面的onPageScroll生命周期 中获得滚动条的位置，故需要在页面监听onPageScroll生命周期，实时获得滚动条的位置，通过Props传递给组件。

<template>
  <view class="wrap">
    <text>滑动页面，返回顶部按钮将出现在右下角</text>
    <su-back-top :scroll-top="scrollTop"></su-back-top>
  </view>
</template>

<script setup>
  import { ref } from 'vue'
  import { onPageScroll } from '@dcloudio/uni-app'

  // 创建响应式数据 scrollTop
  const scrollTop = ref(0)

  // onPageScroll 方法来更新 scrollTop 的值
  onPageScroll((e) => {
    scrollTop.value = e.scrollTop
  })
</script>

<style lang="scss" scoped>
  .wrap {
    height: 200vh;
  }
</style>

改变返回顶部按钮的出现时机

可以通过top参数，修改页面滚动多少距离时，出现返回顶部的按钮

<su-back-top :scroll-top="scrollTop" top="600"></su-back-top>

自定义返回顶部的图标和提示

• 通过icon修改返回顶部按钮的图标，可以是uView内置的图标，或者图片路径(需要1.3.0及以上版本)
• 通过text参数修改返回顶部按钮的文字提示信息，如果需要修改文字的颜色和大小，可以通过custom-style参数

<su-back-top :scroll-top="scrollTop" icon="arrow-up" tips="返回"></su-back-top>

其他自定义样式

• 通过icon-style参数自定义图标的样式，比如颜色，大小等
• 通过custom-style修改返回按钮的背景颜色，大小等
• 通过mode修改按钮的形状，circle为圆形，square为方形

注意：如果通过icon参数传入图片路径的话，需要通过icon-style参数设置图片的width和height属性

<template>
  <view class="wrap">
    <text>滑动页面，返回顶部按钮将出现在右下角</text>
    <su-back-top :scrollTop="scrollTop" :mode="mode" :icon-style="iconStyle"></su-back-top>
  </view>
</template>

<script setup>
  import { ref, reactive } from 'vue'
  import { onPageScroll } from '@dcloudio/uni-app'

  // 使用 ref 创建响应式基本类型数据
  const scrollTop = ref(0)
  const mode = ref('square')

  // 使用 reactive 创建响应式对象数据
  const iconStyle = reactive({
    fontSize: '32rpx',
    color: '#2979ff'
  })

  // onPageScroll 方法来更新 scrollTop 的值
  onPageScroll((e) => {
    scrollTop.value = e.scrollTop
  })
</script>

<style lang="scss" scoped>
  .wrap {
    height: 200vh;
  }
</style>

示例源码

点击可以查看 右侧演示页面的源码

API

Props

参数	说明	类型	默认值	可选值
mode	按钮形状	String	circle	square
icon	uView内置图标名称，或图片路径	String	arrow-upward	-
tips	返回顶部按钮的提示文字	String	-	-
duration	返回顶部过程中的过渡时间，单位ms	String | Number	100	-
scroll-top	页面的滚动距离，通过onPageScroll生命周期获取	String | Number	0	-
top	滚动条滑动多少距离时显示，单位rpx	String | Number	400	-
bottom	返回按钮位置到屏幕底部的距离，单位rpx	String | Number	200	-
right	返回按钮位置到屏幕右边的距离，单位rpx	String | Number	40	-
z-index	返回顶部按钮的层级	String | Number	9	-
icon-style	图标的样式，对象形式	Object	-	-
custom-style	按钮外层的自定义样式	Object	-	-

Slot

名称	说明
-	自定义返回按钮的所有内容