SwBackTop

SwBackTop 是长页回到顶部按钮：滚动超过阈值（默认约一屏）后右下角淡入圆形按钮，点击平滑滚回顶部；prefers-reduced-motion: reduce 用户自动降级为瞬时跳转（不做长距离平滑动画）。scroll 监听走 rAF 节流 + passive，仅客户端注册、SSR 零副作用。

按钮视觉 2.75rem、触摸热区自带 sw-hit-area（44×44）；aria-label 走 framework 内置三语词典（回到顶部 / 回到頂部 / Back to top），随站点语言切换。

全站接入只要一行：在 layouts/default.vue 挂 <SwBackTop /> 即可（监听 window 滚动）。下面的 Demo 因为要在文档页内演示，都用 target 指到局部滚动容器——按钮出现在视口右下角（position: fixed）。

基础用法（target 局部容器）

滚动容器超过阈值 → 按钮淡入 → 点击滚回容器顶部

加载中...
<!-- 全站默认用法：layouts/default.vue 挂一次，监听 window -->
<SwBackTop />

<!-- 局部滚动布局：target 指到滚动容器（CSS 选择器） -->
<SwBackTop target=".scroll-pane" />

自定义阈值

threshold（px）控制「滚过多少才出现」；不传默认约一屏（window.innerHeight / 容器 clientHeight）：

<SwBackTop :threshold="200" />

插槽自渲染

#default slot 替换默认箭头图标（文字 / 业务图标库均可）：

slot 自渲染「TOP」文字钮

加载中...
<SwBackTop><PhRocket :size="20" /></SwBackTop>

Token 移位换肤

定位 / 尺寸 / 配色全走 --sw-back-top-* token，applier 在 overrides.css 覆盖即可，无需 :deep：

品牌色 + 大尺寸 + 自定位置

加载中...
/* overrides.css：移动端给底部 TabBar 让位 + 品牌色 */
:root {
  --sw-back-top-bottom: 5.5rem;
  --sw-back-top-bg: var(--primary);
  --sw-back-top-color: var(--primary-foreground);
}

Props

名称类型必填默认值说明
thresholdnumberundefined出现阈值（px）。不传 = 约一屏（window.innerHeight / 容器 clientHeight，resize 不重算）
targetstringundefined滚动容器 CSS 选择器；不传监听 window。选择器落空时 dev warn + 组件整体 no-op

Slots

名称作用域说明
default—按钮内容，默认内联向上箭头 SVG

样式定制 Token

Token默认值作用点
--sw-back-top-right1.5rem距视口右缘
--sw-back-top-bottom2rem距视口底缘
--sw-back-top-size2.75rem按钮直径
--sw-back-top-bgvar(--card)底色
--sw-back-top-colorvar(--foreground-soft)图标 / 文字色
--sw-back-top-z90层级（常见导航 100 之下）

注意事项

  • 无自定义事件：点击行为即滚顶；需要埋点在外层包点击或用 useTracker 自埋（③ 档纯工具组件，不加 :track）。
  • prefers-reduced-motion: reduce 下：滚顶改瞬时跳转、出现/消失过渡关闭（UX-004）。
  • 移动端有底部 TabBar 的站：覆盖 --sw-back-top-bottom 让位（如 5.5rem），framework 不内置断点偏移（TabBar 高度是业务知识）。

相关