回到顶部 BackTop

回到梦开始的地方。

基本用法

将组件放在应用中任意位置，默认监听 window 的滚动。

visibilityHeight 设置距离滚动容器顶部的距离，默认 200px， 到达此距离后，BackTop 组件才会展示。

right 和 bottom 属性设置组件内容距离视口右侧和底部的距离。

Scroll down to see the BackTop button

<template>
	<div>
		<h3>Scroll down to see the BackTop button</h3>
		<px-back-top />
		<px-back-top :visibility-height="400" :right="120" />
	</div>
</template>

自定义触发元素

通过 buttonProps 配置内置按钮，使用 icon 插槽自定义图标。你甚至可以使用 trigger 插槽替换全部内容

Customize the inner button with buttonProps and replace the icon via the icon slot.

<template>
	<div>
		<p>
			Customize the inner button with <code>buttonProps</code> and replace the icon via the
			<code>icon</code> slot.
		</p>
		<px-back-top :button-props="{ theme: 'primary', shape: 'circle' }" :bottom="100">
			<template #icon>
				<IconArrowUp />
			</template>
		</px-back-top>
		<px-back-top :bottom="160">
			<template #trigger>
				<px-button> Scroll to Top! </px-button>
			</template>
		</px-back-top>
	</div>
</template>

<script setup lang="ts">
import { IconArrowUp } from '@pixelium/web-vue/icon-pa/es'
</script>

自定义滚动容器

通过将 root 设置为选择器或 HTMLElement，组件会监听指定的滚动容器而非 window。

💡 Tip：当 root 为 CSS 选择器字符串时，会通过 document.querySelector 进行解析。如果未匹配到任何元素，组件将回退到 window。

Scrollable container below. BackTop listens to the container when root is set.

This container is scrollable — scroll inside it to trigger the BackTop button.

<template>
	<div>
		<p>
			Scrollable container below. BackTop listens to the container when <code>root</code> is
			set.
		</p>
		<div
			class="scroll-root"
			style="height: 220px; overflow: auto; border: 1px solid var(--px-neutral-6)"
		>
			<div style="height: 800px; background: linear-gradient(180deg, #fff, #f4f7fb)">
				<p style="padding: 12px">
					This container is scrollable — scroll inside it to trigger the BackTop button.
				</p>
			</div>
		</div>
		<!-- BackTop will listen to the .scroll-root element -->
		<px-back-top root=".scroll-root" :bottom="220">
			<template #trigger>
				<px-button theme="warning"> Custom Root ↑</px-button>
			</template>
		</px-back-top>
	</div>
</template>

API

BackTopProps

属性	类型	可选	默认值	描述	版本
root	HTMLElement | string | Window	是	Window	滚动容器，可为 HTMLElement、CSS 选择器字符串或 window；默认监听 window。	0.1.0
visibilityHeight	number	是	200	触发显示按钮的滚动高度阈值，单位 px。	0.1.0
right	number	是	40	与视窗右侧的偏移（px）。	0.1.0
bottom	number	是	40	与视窗底部的偏移（px）。	0.1.0
zIndex	number	是	1000	组件样式的 z-index。	0.1.0
buttonProps	ButtonProps & EmitEvent<ButtonEvents> & RestAttrs	是		传递给内部 Button 的属性（没有使用 trigger 插槽时生效）。	0.1.0

BackTopSlots

插槽	参数	描述	版本
trigger		自定义整个回到顶部按钮的内容。	0.1.0
icon		自定义内部图标（没有使用 trigger 插槽时生效）。	0.1.0

RestAttrs

import type { StyleValue } from 'vue'

export type VueClassValue = string | Record<string, any> | VueClassValue[]
export type VueStyleValue = StyleValue

export type RestAttrs = {
	style?: VueStyleValue | null
	class?: VueClassValue | null
	[x: string]: any
}

EmitEvent

export type EmitEvent<T extends Record<string, any>> = {
	[K in keyof T as `on${Capitalize<K & string>}`]?: (...args: T[K]) => void
}