Sard

Appearance

100%
在新窗口打开⤴

BackTop回到顶部

介绍 ​

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

代码演示 ​

基础使用 ​

返回页面顶部时，BackTop 组件需要配合 usePageBackTop 组合式函数使用。

BackTop 组件需要绑定 usePageBackTop 返回的 scrollTop 属性值和 onClick 回调。

vue
<template>
  <doc-page gray title="基础用法">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" @click="backTop" />
  </doc-page>
</template>

<script setup lang="ts">
import { usePageBackTop } from 'sard'

const { scrollTop, backTop } = usePageBackTop()
</script>
vue
<template>
  <doc-page gray title="基础用法">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" @click="backTop" />
  </doc-page>
</template>

<script setup lang="js">
import { usePageBackTop } from 'sard'
const { scrollTop, backTop } = usePageBackTop()
</script>

scroll-view 组件滚动 ​

返回 scroll-view 顶部时，BackTop 组件需要配合 useElementBackTop 组合式函数使用。

BackTop 组件需要绑定 useElementBackTop 返回的 scrollTop 属性值和 onClick 回调。

scroll-view 组件需要绑定 useElementBackTop 返回的 scrollTop 属性值和 onScroll 回调。

vue
<template>
  <doc-page gray title="scroll-view 组件滚动">
    <div ref="scroll" class="overflow-y-auto" style="height: 60vh">
      <s-list card style="margin: 0 16px; padding: 16px 0">
        <s-list-item v-for="i in 30" :key="i" :title="i" />
      </s-list>
    </div>

    <s-back-top :scroll-top="scrollTop" @click="backTop" />
  </doc-page>
</template>

<script setup lang="ts">
import { useElementBackTop } from 'sard'
import { useTemplateRef } from 'vue'

const scrollRef = useTemplateRef('scroll')
const { scrollTop, backTop } = useElementBackTop(scrollRef)
</script>
vue
<template>
  <doc-page gray title="scroll-view 组件滚动">
    <div ref="scroll" class="overflow-y-auto" style="height: 60vh">
      <s-list card style="margin: 0 16px; padding: 16px 0">
        <s-list-item v-for="i in 30" :key="i" :title="i" />
      </s-list>
    </div>

    <s-back-top :scroll-top="scrollTop" @click="backTop" />
  </doc-page>
</template>

<script setup lang="js">
import { useElementBackTop } from 'sard'
import { useTemplateRef } from 'vue'
const scrollRef = useTemplateRef('scroll')
const { scrollTop, backTop } = useElementBackTop(scrollRef)
</script>

按钮位置 ​

通过设置 right 和 bottom 属性可以自定义按钮距离右下角的距离。

vue
<template>
  <doc-page gray title="按钮位置">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" right="48px" bottom="96px" @click="backTop" />
  </doc-page>
</template>

<script setup lang="ts">
import { usePageBackTop } from 'sard'

const { scrollTop, backTop } = usePageBackTop()
</script>
vue
<template>
  <doc-page gray title="按钮位置">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" right="48px" bottom="96px" @click="backTop" />
  </doc-page>
</template>

<script setup lang="js">
import { usePageBackTop } from 'sard'
const { scrollTop, backTop } = usePageBackTop()
</script>

滚动时长 ​

usePageBackTop 组合式函数可以接收一个数值类型参数，表示滚动到页面顶部的动画时长。

scroll-view 默认没有滚动动画，通过设置 scroll-with-animation 属性可以添加滚动动画。

vue
<template>
  <doc-page gray title="滚动时长">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" @click="backTop" />
  </doc-page>
</template>

<script setup lang="ts">
import { usePageBackTop } from 'sard'

const { scrollTop, backTop } = usePageBackTop('instant')
</script>
vue
<template>
  <doc-page gray title="滚动时长">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" @click="backTop" />
  </doc-page>
</template>

<script setup lang="js">
import { usePageBackTop } from 'sard'
const { scrollTop, backTop } = usePageBackTop('instant')
</script>

可见时的高度 ​

默认情况下，当页面或 scroll-view 滚动到一定距离时，按钮才会显示。

可以设置 visible-height 为 0 让按钮一直显示。

vue
<template>
  <doc-page gray title="可见时的高度">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" :visible-height="0" @click="backTop" />
  </doc-page>
</template>

<script setup lang="ts">
import { usePageBackTop } from 'sard'

const { scrollTop, backTop } = usePageBackTop()
</script>
vue
<template>
  <doc-page gray title="可见时的高度">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" :visible-height="0" @click="backTop" />
  </doc-page>
</template>

<script setup lang="js">
import { usePageBackTop } from 'sard'
const { scrollTop, backTop } = usePageBackTop()
</script>

自定义按钮内容 ​

使用默认插槽自定义组件展示的内容。

vue
<template>
  <doc-page gray title="自定义按钮内容">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" @click="backTop">
      <span style="font-size: var(--s-font-size)">回到顶部</span>
    </s-back-top>
  </doc-page>
</template>

<script setup lang="ts">
import { usePageBackTop } from 'sard'

const { scrollTop, backTop } = usePageBackTop()
</script>
vue
<template>
  <doc-page gray title="自定义按钮内容">
    <s-list card style="margin: 0 16px; padding: 16px 0">
      <s-list-item v-for="i in 30" :key="i" :title="i" />
    </s-list>

    <s-back-top :scroll-top="scrollTop" @click="backTop">
      <span style="font-size: var(--s-font-size)">回到顶部</span>
    </s-back-top>
  </doc-page>
</template>

<script setup lang="js">
import { usePageBackTop } from 'sard'
const { scrollTop, backTop } = usePageBackTop()
</script>

API ​

BackTopProps ​

属性描述类型默认值
scroll-top当前页面或 scroll-view 滚动的高度number0
visible-height回到顶部按钮显示时的页面或 scroll-view 滚动的最小高度number200
right回到顶部按钮距离右边的距离string-
bottom回到顶部按钮距离底部的距离string-

BackTopSlots ​

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

BackTopEmits ​

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

usePageBackTop ​

ts
function usePageBackTop(behavior?: ScrollBehavior): {
  scrollTop: Ref<number, number>
  backTop: () => void
}
参数描述类型默认值
behavior滚动行为ScrollBehavior'smooth'
返回对象的属性描述类型
scrollTop需要绑定到 BackTop 组件 scroll-top 属性的值Ref<number>
backTop需要绑定到 BackTop 组件 click 事件的回调() => void

useElementBackTop ​

ts
function useElementBackTop(
  el: Ref<HTMLElement | null | undefined, HTMLElement | null | undefined>,
): {
  scrollTop: Ref<number, number>
  backTop: () => void
}
返回对象的属性描述类型
scrollTop需要绑定到 BackTop 组件 scroll-top 属性的值Ref<number>
backTop需要绑定到 BackTop 组件 click 事件的回调() => void

Released under the MIT License.

Copyright © 2023-present wuzhitao