uv-ui

# BackTop 返回顶部

✈

组件名：uv-back-top

点击下载&安装 (opens new window)

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

# 平台兼容性

App（vue） App（nvue） H5 小程序 VUE2 VUE3
√ √ √ √ √ √

# 基本使用

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

注意

  1. nvue 页面需要给页面最外层元素设置 ref='uv-back-top'
  2. onPageScroll 周期函数中获取值也有些区别，nvue中为e.detail.scrollTop，vue中为e.scrollTop
<template>
	<view class="wrap" ref="backTop">
		<text>滑动页面，返回顶部按钮将出现在右下角</text>
		<uv-back-top :scroll-top="scrollTop"></uv-back-top>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				scrollTop: 0
			}
		},
		onPageScroll(e) {
			this.scrollTop = e.scrollTop;
			// #ifdef APP-NVUE
			this.scrollTop = e.detail.scrollTop;
			// #endif
		}
	}
</script>
<style lang="scss" scoped>
	.wrap {
		height: 2000px;
	}
</style>

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

通过top属性设置页面滚动多少距离时，出现返回顶部的按钮

<template>
	<view class="wrap" style="height: 2000px;" ref="backTop" top="600">
		<text>滑动页面，返回顶部按钮将出现在右下角</text>
		<uv-back-top :scroll-top="scrollTop"></uv-back-top>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				scrollTop: 0
			}
		},
		onPageScroll(e) {
			this.scrollTop = e.scrollTop;
			// #ifdef APP-NVUE
			this.scrollTop = e.detail.scrollTop;
			// #endif
		}
	}
</script>

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

  • 通过icon属性设置返回顶部按钮的图标，可以是uv-ui内置的图标，或者图片路径
  • 通过text属性设置返回顶部按钮的文字提示信息，如果需要修改文字的颜色和大小，可以通过customStyle参数
<template>
	<view class="wrap" style="height: 2000px;" ref="backTop" top="600">
		<text>滑动页面，返回顶部按钮将出现在右下角</text>
		<uv-back-top :scroll-top="scrollTop" icon="arrow-up" text="返回"></uv-back-top>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				scrollTop: 0
			}
		},
		onPageScroll(e) {
			this.scrollTop = e.scrollTop;
			// #ifdef APP-NVUE
			this.scrollTop = e.detail.scrollTop;
			// #endif
		}
	}
</script>

# 其他自定义样式

  • 通过iconStyle属性自定义图标的样式，比如颜色，大小等
  • 通过customStyle属性设置返回按钮的背景颜色，大小等
  • 通过mode属性设置按钮的形状，circle为圆形，square为方形

注意

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

<template>
	<view class="wrap" style="height: 2000px;" ref="backTop" top="600">
		<text>滑动页面，返回顶部按钮将出现在右下角</text>
		<uv-back-top 
			:scroll-top="scrollTop" 
			icon="arrow-up" 
			text="返回"
			:mode="mode"
			:iconStyle="iconStyle"
			:customStyle="customStyle"
		></uv-back-top>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				scrollTop: 0,
				mode: 'square',
				customStyle: {
					fontSize: '24rpx',
					color: '#2979ff'
				},
				iconStyle: {
					fontSize: '32rpx',
					color: '#2979ff'
				}
			}
		},
		onPageScroll(e) {
			this.scrollTop = e.scrollTop;
			// #ifdef APP-NVUE
			this.scrollTop = e.detail.scrollTop;
			// #endif
		}
	}
</script>

# 完整示例

完整示例下载地址

https://ext.dcloud.net.cn/plugin?name=uv-ui (opens new window)

# API

# BackTop Props

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

# BackTop Methods

方法名 说明
backToTop 自定义内容的时，可以调用此方法返回顶部

# BackTop Slots

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

← Navbar 自定义导航栏 →