回到顶部 back-top

导航组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

滚过 200px 按钮才露面，点它滚回顶部

第 1 段内容，往下滚。

第 2 段内容，往下滚。

第 3 段内容，往下滚。

第 4 段内容，往下滚。

第 5 段内容，往下滚。

第 6 段内容，往下滚。

第 7 段内容，往下滚。

第 8 段内容，往下滚。

第 9 段内容，往下滚。

第 10 段内容，往下滚。

第 11 段内容，往下滚。

第 12 段内容，往下滚。

第 13 段内容，往下滚。

第 14 段内容，往下滚。

第 15 段内容，往下滚。

第 16 段内容，往下滚。

第 17 段内容，往下滚。

第 18 段内容，往下滚。

第 19 段内容，往下滚。

第 20 段内容，往下滚。

<script setup lang="ts">
import { ref } from "vue";
import { XhBackTopRoot, XhBackTopTrigger } from "@xihan-ui/vue";

const scrollEl = ref<HTMLElement | null>(null);
</script>

<template>
  <!-- 定位壳缺省钉在视口一角；这里把它改成钉在面板内，示例才不必占用整页 -->
  <div style="position: relative; inline-size: 100%">
    <div
      ref="scrollEl"
      style="
        block-size: 240px;
        overflow: auto;
        padding: 12px;
        border: 1px solid var(--xh-border-default);
        border-radius: 8px;
      "
    >
      <p v-for="i in 20" :key="i" style="margin: 0 0 12px">第 {{ i }} 段内容，往下滚。</p>
    </div>

    <XhBackTopRoot
      :target="scrollEl"
      style="position: absolute; --xh-back-top-inset-block: 12px; --xh-back-top-inset-inline: 12px"
    >
      <XhBackTopTrigger>↑</XhBackTopTrigger>
    </XhBackTopRoot>
  </div>
</template>

露面阈值

visibility-height 决定滚过多少像素按钮才出现

滚过 80px 才露面

第 1 段内容。

第 2 段内容。

第 3 段内容。

第 4 段内容。

第 5 段内容。

第 6 段内容。

第 7 段内容。

第 8 段内容。

第 9 段内容。

第 10 段内容。

第 11 段内容。

第 12 段内容。

第 13 段内容。

第 14 段内容。

第 15 段内容。

第 16 段内容。

第 17 段内容。

第 18 段内容。

第 19 段内容。

第 20 段内容。

<script setup lang="ts">
import { ref } from "vue";
import { XhBackTopRoot, XhBackTopTrigger } from "@xihan-ui/vue";

const scrollEl = ref<HTMLElement | null>(null);
const threshold = ref(80);
</script>

<template>
  <div style="display: grid; gap: 12px; inline-size: 100%">
    <label style="display: flex; align-items: center; gap: 8px">
      滚过
      <input v-model.number="threshold" type="range" min="0" max="600" step="20" />
      {{ threshold }}px 才露面
    </label>

    <div style="position: relative">
      <div
        ref="scrollEl"
        style="
          block-size: 240px;
          overflow: auto;
          padding: 12px;
          border: 1px solid var(--xh-border-default);
          border-radius: 8px;
        "
      >
        <p v-for="i in 20" :key="i" style="margin: 0 0 12px">第 {{ i }} 段内容。</p>
      </div>

      <XhBackTopRoot
        :target="scrollEl"
        :visibility-height="threshold"
        style="position: absolute; --xh-back-top-inset-block: 12px; --xh-back-top-inset-inline: 12px"
      >
        <XhBackTopTrigger>↑</XhBackTopTrigger>
      </XhBackTopRoot>
    </div>
  </div>
</template>

滚动方式

behavior=auto 一步跳回顶部，smooth 平滑滚过去

smooth · 第 1 段

smooth · 第 2 段

smooth · 第 3 段

smooth · 第 4 段

smooth · 第 5 段

smooth · 第 6 段

smooth · 第 7 段

smooth · 第 8 段

smooth · 第 9 段

smooth · 第 10 段

smooth · 第 11 段

smooth · 第 12 段

smooth · 第 13 段

smooth · 第 14 段

smooth · 第 15 段

smooth · 第 16 段

auto · 第 1 段

auto · 第 2 段

auto · 第 3 段

auto · 第 4 段

auto · 第 5 段

auto · 第 6 段

auto · 第 7 段

auto · 第 8 段

auto · 第 9 段

auto · 第 10 段

auto · 第 11 段

auto · 第 12 段

auto · 第 13 段

auto · 第 14 段

auto · 第 15 段

auto · 第 16 段

<script setup lang="ts">
import { ref } from "vue";
import { XhBackTopRoot, XhBackTopTrigger } from "@xihan-ui/vue";

const smoothEl = ref<HTMLElement | null>(null);
const autoEl = ref<HTMLElement | null>(null);
</script>

<template>
  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 16px; inline-size: 100%">
    <div style="position: relative">
      <div
        ref="smoothEl"
        style="
          block-size: 200px;
          overflow: auto;
          padding: 12px;
          border: 1px solid var(--xh-border-default);
          border-radius: 8px;
        "
      >
        <p v-for="i in 16" :key="i" style="margin: 0 0 12px">smooth · 第 {{ i }} 段</p>
      </div>
      <XhBackTopRoot
        :target="smoothEl"
        behavior="smooth"
        size="sm"
        style="position: absolute; --xh-back-top-inset-block: 12px; --xh-back-top-inset-inline: 12px"
      >
        <XhBackTopTrigger>↑</XhBackTopTrigger>
      </XhBackTopRoot>
    </div>

    <div style="position: relative">
      <div
        ref="autoEl"
        style="
          block-size: 200px;
          overflow: auto;
          padding: 12px;
          border: 1px solid var(--xh-border-default);
          border-radius: 8px;
        "
      >
        <p v-for="i in 16" :key="i" style="margin: 0 0 12px">auto · 第 {{ i }} 段</p>
      </div>
      <XhBackTopRoot
        :target="autoEl"
        behavior="auto"
        size="sm"
        style="position: absolute; --xh-back-top-inset-block: 12px; --xh-back-top-inset-inline: 12px"
      >
        <XhBackTopTrigger>↑</XhBackTopTrigger>
      </XhBackTopRoot>
    </div>
  </div>
</template>

语气与尺寸

tone 决定按钮用哪族颜色，size 换一档尺寸；translations 换掉读屏念出的名字

语气 brandneutralsuccesswarningdangerinfo 尺寸 smmdlg

第 1 段内容。

第 2 段内容。

第 3 段内容。

第 4 段内容。

第 5 段内容。

第 6 段内容。

第 7 段内容。

第 8 段内容。

第 9 段内容。

第 10 段内容。

第 11 段内容。

第 12 段内容。

第 13 段内容。

第 14 段内容。

第 15 段内容。

第 16 段内容。

第 17 段内容。

第 18 段内容。

第 19 段内容。

第 20 段内容。

<script setup lang="ts">
import { ref } from "vue";
import { XhBackTopRoot, XhBackTopTrigger } from "@xihan-ui/vue";

const scrollEl = ref<HTMLElement | null>(null);
const tone = ref("brand");
const size = ref("md");
</script>

<template>
  <div style="display: grid; gap: 12px; inline-size: 100%">
    <div style="display: flex; gap: 16px">
      <label style="display: flex; align-items: center; gap: 6px">
        语气
        <select v-model="tone">
          <option
            v-for="t in ['brand', 'neutral', 'success', 'warning', 'danger', 'info']"
            :key="t"
            :value="t"
          >
            {{ t }}
          </option>
        </select>
      </label>
      <label style="display: flex; align-items: center; gap: 6px">
        尺寸
        <select v-model="size">
          <option v-for="s in ['sm', 'md', 'lg']" :key="s" :value="s">{{ s }}</option>
        </select>
      </label>
    </div>

    <div style="position: relative">
      <div
        ref="scrollEl"
        style="
          block-size: 220px;
          overflow: auto;
          padding: 12px;
          border: 1px solid var(--xh-border-default);
          border-radius: 8px;
        "
      >
        <p v-for="i in 20" :key="i" style="margin: 0 0 12px">第 {{ i }} 段内容。</p>
      </div>

      <XhBackTopRoot
        :target="scrollEl"
        :tone="tone"
        :size="size"
        :visibility-height="40"
        :translations="{ trigger: '回到顶部' }"
        style="position: absolute; --xh-back-top-inset-block: 12px; --xh-back-top-inset-inline: 12px"
      >
        <XhBackTopTrigger>↑</XhBackTopTrigger>
      </XhBackTopRoot>
    </div>
  </div>
</template>

产物

层	值
自定义元素	<xh-back-top>
Vue 组件	XhBackTopRoot XhBackTopTrigger
组合式函数	useBackTop
状态机	backTopMachine
皮肤	@xihan-ui/styles/back-top.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="back-top"：root · trigger

Props

属性	类型	必填	说明
visibilityHeight	number		滚过这么多像素按钮才露面，默认 200。
behavior	BackTopBehavior		滚回顶部的方式，默认 smooth。
translations	Partial<BackTopTranslations>
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定按钮用哪族颜色。
size	Size		尺寸：sm / md / lg。
onVisibleChange	(details: BackTopVisibleChangeDetails) => void		露面与否变化时回调。

状态机

状态：hidden · visible

事件：SCROLL.RESOLVE · TRIGGER.CLICK

判据：shouldShow · shouldHide

connect API

useBackTop 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
visible	boolean	按钮此刻露不露面。
scrollToTop	() => void	程序化滚回顶部，与点按钮走同一条路。
getRootProps	() => T['element']
getTriggerProps	() => T['button']

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space	focus in trigger	滚回顶部；按 behavior 决定是一步到位还是平滑滚过去
Tab / Shift+Tab	trigger 露面时	走到按钮上；收起时整个 root 带 hidden，按钮不在 Tab 序列里