Sard Uniapp

Appearance

在新窗口打开⤴

BackTop回到顶部1.6+

介绍 ​

返回页面顶部的操作按钮。

引入 ​

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 滚动的高度number0
visible-height回到顶部按钮显示时的页面或 scroll-view 滚动的最小高度number200
right回到顶部按钮距离右边的距离string-
bottom回到顶部按钮距离底部的距离string-

BackTopSlots ​

插槽描述属性
default自定义默认内容-

BackTopEmits ​

事件描述类型
click点击时触发(event: any) => void

usePageBackTop ​

ts
function usePageBackTop(duration?: number): {
  scrollTop: Ref<number>
  onClick: () => void
}
参数描述类型默认值
duration滚动动画时长，单位 msnumber300
返回对象的属性描述类型
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);
}

Released under the MIT License.

Copyright © 2023-present wuzhitao