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 高度是業務知識）。

相關