Backtop 回到顶部

快速回到滚动视口顶部的辅助按钮，拥有粗野主义的厚重斜角硬投影和高亮黄配色。支持监听全局 window 滚动或指定的局部 DOM 节点滚动，提供 useThrottle 节流防护，防止由于短时间频繁派发 scroll 事件产生的 CPU 开销。

预览

Preview

基础用法

向下滚动下方容器，当滚动距离超过 100px 时，容器右下角会出现回到顶部按钮。 指定 target 后，Backtop 使用 absolute 定位，按钮会相对目标容器定位，不会逃出预览框。

滚动内容

向下滚动以触发回到顶部按钮

安装

pnpm dlx brutx-vue@latest add backtop

用法

基础全局用法

在页面中直接引入 <Backtop>。当全局视口向下滚动高度超过 200 像素时，按钮会自动以过渡动效浮现。

<script setup>
import { Backtop } from 'brutx-ui-vue'
</script>

<template>
    <!-- 默认监听全局 window 视口，在右下角展示 -->
    <Backtop :visibility-height="200" />
</template>

监听局部滚动容器

在具有 overflow-y: auto 的局部大内容容器内挂载回到顶部，通过 target 属性传入容器的选择器 ID 或者是 HTMLElement 引用。

<template>
    <div id="my-scroll-box" class="h-60 overflow-y-auto relative">
        <!-- 页面长文本内容 -->
        <div class="h-[800px]">...</div>
        
        <!-- target 绑定容器 selector -->
        <Backtop target="#my-scroll-box" :visibility-height="100" />
    </div>
</template>

改变偏置位置与色彩变体

通过 right 和 bottom 定位偏移量，并通过 variant 修改配色主题。

<template>
    <Backtop 
        :right="80" 
        :bottom="80" 
        variant="accent" 
        :visibility-height="150" 
    />
</template>

API 参考

Backtop — 属性

名称	类型	默认值	说明
visibilityHeight	number | undefined	200	滚动容器的垂直滚动距离达到此像素值时显示按钮。
详情 声明类型 number | undefined 默认值详情 声明 200 来源: packages/ui/src/components/backtop/Backtop.vue 解析值 200 来源 Backtop.vue:14 packages/ui/src/components/backtop/Backtop.vue
target	string | HTMLElement | undefined	undefined 运行时回退:未设置或为空字符串时监听 window，按钮相对视口固定定位。	监听并滚动到顶部的容器，可传入 CSS 选择器或元素。设置后按钮使用 absolute 定位，需放在已定位的祖先容器内。
详情 声明类型 string | HTMLElement | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/backtop/Backtop.vue 解析值 undefined 运行时回退 未设置或为空字符串时监听 window，按钮相对视口固定定位。 组件在说明的运行条件下采用此回退值。 来源 Backtop.vue:15 packages/ui/src/components/backtop/Backtop.vue
right	number | undefined	40	按钮到定位参照区域右侧的距离，单位为像素。
详情 声明类型 number | undefined 默认值详情 声明 40 来源: packages/ui/src/components/backtop/Backtop.vue 解析值 40 来源 Backtop.vue:16 packages/ui/src/components/backtop/Backtop.vue
bottom	number | undefined	40	按钮到定位参照区域底部的距离，单位为像素。
详情 声明类型 number | undefined 默认值详情 声明 40 来源: packages/ui/src/components/backtop/Backtop.vue 解析值 40 来源 Backtop.vue:17 packages/ui/src/components/backtop/Backtop.vue
variant	"default" | "ghost" | "primary" | "secondary" | "success" | "danger" | "accent" | "outline" | "link" | undefined	"primary"	传给内部 Button 的视觉变体；primary 额外应用黄色背景和黑色文字。
详情 声明类型 "default" | "ghost" | "primary" | "secondary" | "success" | "danger" | "accent" | "outline" | "link" | undefined 字面量 "accent" "danger" "default" "ghost" "link" "outline" "primary" "secondary" "success" 默认值详情 声明 'primary' 来源: packages/ui/src/components/backtop/Backtop.vue 解析值 "primary" 来源 Backtop.vue:18 packages/ui/src/components/backtop/Backtop.vue
class	string | undefined	undefined	追加到回到顶部按钮的自定义 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/backtop/Backtop.vue 解析值 undefined 来源 Backtop.vue:19 packages/ui/src/components/backtop/Backtop.vue

Backtop — 事件

名称	签名或类型	说明
@click	[event: MouseEvent]	按钮被点击时发出原始鼠标事件，随后对目标容器调用平滑滚动到顶部。
详情 声明类型 [event: MouseEvent] 来源 Backtop.vue packages/ui/src/components/backtop/Backtop.vue

Backtop — 插槽

名称	签名或类型	说明
#default	{}	替换按钮内的向上箭头图标。
详情 声明类型 {} 来源 Backtop.vue packages/ui/src/components/backtop/Backtop.vue

可访问性

• 键盘操作：按钮支持 Tab 聚焦及 Enter、Space 激活。
• ARIA 属性：按钮使用 backtop.backToTop 本地化文案作为无障碍名称。
• 滚动行为：激活后调用原生滚动 { top: 0, behavior: 'smooth' }，实际滚动表现由浏览器处理。