介绍
返回页面顶部的操作按钮。
引入
js
import BackTop from 'sard-uniapp/components/back-top/back-top.vue'代码演示
基础使用
返回页面顶部时,BackTop 组件需要配合 usePageBackTop 组合式函数使用。
BackTop 组件需要绑定 usePageBackTop 返回的 scrollTop 属性值和 onClick 回调。
另外,为了让 uniapp 编译器能够初始化 onPageScroll 页面钩子,需要显式在页面组件调用 onPageScroll 组合式函数。
vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="基础用法">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top :scroll-top="scrollTop" @click="onClick" />
</doc-page>
</template>
<script setup lang="ts">
import { useCurrentPageLock, usePageTopPopup } from 'sard-uniapp'
import { onBackPress } from '@dcloudio/uni-app'
import { onPageScroll } from '@dcloudio/uni-app'
import { usePageBackTop } from 'sard-uniapp'
const { scrollTop, onClick } = usePageBackTop()
onPageScroll(() => void 0)
const { isLocked } = useCurrentPageLock()
const { shouldStopBack, hidePopup } = usePageTopPopup()
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup()
return true
}
})
</script>vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="基础用法">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top :scroll-top="scrollTop" @click="onClick" />
</doc-page>
</template>
<script setup lang="js">
import { useCurrentPageLock, usePageTopPopup } from "sard-uniapp";
import { onBackPress } from "@dcloudio/uni-app";
import { onPageScroll } from "@dcloudio/uni-app";
import { usePageBackTop } from "sard-uniapp";
const { scrollTop, onClick } = usePageBackTop();
onPageScroll(() => void 0);
const { isLocked } = useCurrentPageLock();
const { shouldStopBack, hidePopup } = usePageTopPopup();
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup();
return true;
}
});
</script>scroll-view 组件滚动
返回 scroll-view 顶部时,BackTop 组件需要配合 useScrollViewBackTop 组合式函数使用。
BackTop 组件需要绑定 useScrollViewBackTop 返回的 scrollTop 属性值和 onClick 回调。
scroll-view 组件需要绑定 useScrollViewBackTop 返回的 scrollTop 属性值和 onScroll 回调。
vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="scroll-view 组件滚动">
<scroll-view
scroll-y
:scroll-top="scrollTop"
style="height: 60vh"
@scroll="onScroll"
>
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
</scroll-view>
<sar-back-top :scroll-top="scrollTop" @click="onClick" />
</doc-page>
</template>
<script setup lang="ts">
import { useCurrentPageLock, usePageTopPopup } from 'sard-uniapp'
import { onBackPress } from '@dcloudio/uni-app'
import { useScrollViewBackTop } from 'sard-uniapp'
const { scrollTop, onScroll, onClick } = useScrollViewBackTop()
const { isLocked } = useCurrentPageLock()
const { shouldStopBack, hidePopup } = usePageTopPopup()
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup()
return true
}
})
</script>vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="scroll-view 组件滚动">
<scroll-view
scroll-y
:scroll-top="scrollTop"
style="height: 60vh"
@scroll="onScroll"
>
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
</scroll-view>
<sar-back-top :scroll-top="scrollTop" @click="onClick" />
</doc-page>
</template>
<script setup lang="js">
import { useCurrentPageLock, usePageTopPopup } from "sard-uniapp";
import { onBackPress } from "@dcloudio/uni-app";
import { useScrollViewBackTop } from "sard-uniapp";
const { scrollTop, onScroll, onClick } = useScrollViewBackTop();
const { isLocked } = useCurrentPageLock();
const { shouldStopBack, hidePopup } = usePageTopPopup();
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup();
return true;
}
});
</script>按钮位置
通过设置 right 和 bottom 属性可以自定义按钮距离右下角的距离。
vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="按钮位置">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top
:scroll-top="scrollTop"
right="96rpx"
bottom="192rpx"
@click="onClick"
/>
</doc-page>
</template>
<script setup lang="ts">
import { useCurrentPageLock, usePageTopPopup } from 'sard-uniapp'
import { onBackPress } from '@dcloudio/uni-app'
import { onPageScroll } from '@dcloudio/uni-app'
import { usePageBackTop } from 'sard-uniapp'
const { scrollTop, onClick } = usePageBackTop()
onPageScroll(() => void 0)
const { isLocked } = useCurrentPageLock()
const { shouldStopBack, hidePopup } = usePageTopPopup()
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup()
return true
}
})
</script>vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="按钮位置">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top
:scroll-top="scrollTop"
right="96rpx"
bottom="192rpx"
@click="onClick"
/>
</doc-page>
</template>
<script setup lang="js">
import { useCurrentPageLock, usePageTopPopup } from "sard-uniapp";
import { onBackPress } from "@dcloudio/uni-app";
import { onPageScroll } from "@dcloudio/uni-app";
import { usePageBackTop } from "sard-uniapp";
const { scrollTop, onClick } = usePageBackTop();
onPageScroll(() => void 0);
const { isLocked } = useCurrentPageLock();
const { shouldStopBack, hidePopup } = usePageTopPopup();
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup();
return true;
}
});
</script>滚动时长
usePageBackTop 组合式函数可以接收一个数值类型参数,表示滚动到页面顶部的动画时长。
scroll-view 默认没有滚动动画,通过设置 scroll-with-animation 属性可以添加滚动动画。
vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="滚动时长">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top :scroll-top="scrollTop" @click="onClick" />
</doc-page>
</template>
<script setup lang="ts">
import { useCurrentPageLock, usePageTopPopup } from 'sard-uniapp'
import { onBackPress } from '@dcloudio/uni-app'
import { onPageScroll } from '@dcloudio/uni-app'
import { usePageBackTop } from 'sard-uniapp'
const { scrollTop, onClick } = usePageBackTop(0)
onPageScroll(() => void 0)
const { isLocked } = useCurrentPageLock()
const { shouldStopBack, hidePopup } = usePageTopPopup()
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup()
return true
}
})
</script>vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="滚动时长">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top :scroll-top="scrollTop" @click="onClick" />
</doc-page>
</template>
<script setup lang="js">
import { useCurrentPageLock, usePageTopPopup } from "sard-uniapp";
import { onBackPress } from "@dcloudio/uni-app";
import { onPageScroll } from "@dcloudio/uni-app";
import { usePageBackTop } from "sard-uniapp";
const { scrollTop, onClick } = usePageBackTop(0);
onPageScroll(() => void 0);
const { isLocked } = useCurrentPageLock();
const { shouldStopBack, hidePopup } = usePageTopPopup();
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup();
return true;
}
});
</script>可见时的高度
默认情况下,当页面或 scroll-view 滚动到一定距离时,按钮才会显示。
可以设置 visible-height 为 0 让按钮一直显示。
vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="可见时的高度">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top
:scroll-top="scrollTop"
:visible-height="0"
@click="onClick"
/>
</doc-page>
</template>
<script setup lang="ts">
import { useCurrentPageLock, usePageTopPopup } from 'sard-uniapp'
import { onBackPress } from '@dcloudio/uni-app'
import { onPageScroll } from '@dcloudio/uni-app'
import { usePageBackTop } from 'sard-uniapp'
const { scrollTop, onClick } = usePageBackTop()
onPageScroll(() => void 0)
const { isLocked } = useCurrentPageLock()
const { shouldStopBack, hidePopup } = usePageTopPopup()
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup()
return true
}
})
</script>vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="可见时的高度">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top
:scroll-top="scrollTop"
:visible-height="0"
@click="onClick"
/>
</doc-page>
</template>
<script setup lang="js">
import { useCurrentPageLock, usePageTopPopup } from "sard-uniapp";
import { onBackPress } from "@dcloudio/uni-app";
import { onPageScroll } from "@dcloudio/uni-app";
import { usePageBackTop } from "sard-uniapp";
const { scrollTop, onClick } = usePageBackTop();
onPageScroll(() => void 0);
const { isLocked } = useCurrentPageLock();
const { shouldStopBack, hidePopup } = usePageTopPopup();
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup();
return true;
}
});
</script>自定义按钮内容
使用默认插槽自定义组件展示的内容。
vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="自定义按钮内容">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top :scroll-top="scrollTop" @click="onClick">
<text style="font-size: var(--sar-text-base)">回到顶部</text>
</sar-back-top>
</doc-page>
</template>
<script setup lang="ts">
import { useCurrentPageLock, usePageTopPopup } from 'sard-uniapp'
import { onBackPress } from '@dcloudio/uni-app'
import { onPageScroll } from '@dcloudio/uni-app'
import { usePageBackTop } from 'sard-uniapp'
const { scrollTop, onClick } = usePageBackTop()
onPageScroll(() => void 0)
const { isLocked } = useCurrentPageLock()
const { shouldStopBack, hidePopup } = usePageTopPopup()
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup()
return true
}
})
</script>vue
<template>
<page-meta :page-style="isLocked ? 'overflow: hidden' : ''"></page-meta>
<doc-page title="自定义按钮内容">
<sar-list card root-style="margin: 0 32rpx; padding: 32rpx 0;">
<sar-list-item v-for="i in 30" :key="i" :title="i" />
</sar-list>
<sar-back-top :scroll-top="scrollTop" @click="onClick">
<text style="font-size: var(--sar-text-base)">回到顶部</text>
</sar-back-top>
</doc-page>
</template>
<script setup lang="js">
import { useCurrentPageLock, usePageTopPopup } from "sard-uniapp";
import { onBackPress } from "@dcloudio/uni-app";
import { onPageScroll } from "@dcloudio/uni-app";
import { usePageBackTop } from "sard-uniapp";
const { scrollTop, onClick } = usePageBackTop();
onPageScroll(() => void 0);
const { isLocked } = useCurrentPageLock();
const { shouldStopBack, hidePopup } = usePageTopPopup();
onBackPress(() => {
if (shouldStopBack.value) {
hidePopup();
return true;
}
});
</script>API
BackTopProps
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| root-class | 组件根元素类名 | string | - |
| root-style | 组件根元素样式 | StyleValue | - |
| scroll-top | 当前页面或 scroll-view 滚动的高度 | number | 0 |
| visible-height | 回到顶部按钮显示时的页面或 scroll-view 滚动的最小高度 | number | 200 |
| right | 回到顶部按钮距离右边的距离 | string | - |
| bottom | 回到顶部按钮距离底部的距离 | string | - |
BackTopSlots
| 插槽 | 描述 | 属性 |
|---|---|---|
| default | 自定义默认内容 | - |
BackTopEmits
| 事件 | 描述 | 类型 |
|---|---|---|
| click | 点击时触发 | (event: any) => void |
usePageBackTop
ts
function usePageBackTop(duration?: number): {
scrollTop: Ref<number>
onClick: () => void
}| 参数 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| duration | 滚动动画时长,单位 ms | number | 300 |
| 返回对象的属性 | 描述 | 类型 |
|---|---|---|
| scrollTop | 需要绑定到 BackTop 组件 scroll-top 属性的值 | Ref<number> |
| onClick | 需要绑定到 BackTop 组件 click 事件的回调 | () => void |
useScrollViewBackTop
ts
function useScrollViewBackTop(): {
scrollTop: Ref<number>
onScroll: (event: any) => void
onClick: () => void
}| 返回对象的属性 | 描述 | 类型 |
|---|---|---|
| scrollTop | 需要绑定到 BackTop 和 ScrollView 组件 scroll-top 属性的值 | Ref<number> |
| onScroll | 需要绑定到 ScrollView 组件 scroll 事件的回调 | (event: any) => void |
| onClick | 需要绑定到 BackTop 组件 click 事件的回调 | () => void |
主题定制
CSS 变量
scss
page,
.sar-portal {
--sar-back-top-right: 48rpx;
--sar-back-top-bottom: 96rpx;
--sar-back-top-z-index: 1000;
--sar-back-top-height: 96rpx;
--sar-back-top-min-width: 96rpx;
--sar-back-top-padding-x: 24rpx;
--sar-back-top-border-radius: var(--sar-rounded-full);
--sar-back-top-font-size: 48rpx;
--sar-back-top-color: var(--sar-white);
--sar-back-top-bg: var(--sar-primary);
--sar-back-top-box-shadow: var(--sar-shadow-lg);
--sar-back-top-active-opacity: var(--sar-active-opacity);
--sar-back-top-duration: var(--sar-duration);
}