BackTop 回到頂部 - Vant 4
BackTop 回到頂部
⬆️ 介紹
回到頂部元件為使用者提供了便捷的頁面導航體驗！當頁面內容較長時，一鍵返回頂部，讓瀏覽更加輕鬆愉快。
📦 引入
透過以下方式來全域註冊元件，更多註冊方式請參考元件註冊。
js
import { createApp } from'vue';
const app = createApp();
app.use(BackTop);🎯 程式碼演示
基礎用法
請滾動右側的範例頁面，當頁面滾動 200px 時，右下角會出現返回頂部按鈕。智慧顯示，貼心體驗！
html
js
exportdefault { setup() { const list = [...Array(50).keys()]; return { list }; }, };自訂位置
透過 right 和 bottom 屬性來設定元件距離右側和底部的位置。靈活定位，適應不同佈局需求！
html
js
exportdefault { setup() { const list = [...Array(50).keys()]; return { list }; }, };自訂內容
使用預設插槽來自訂元件展示的內容。
html
js
exportdefault { setup() { const list = [...Array(50).keys()]; return { list }; }, };設定滾動目標
可以透過 target 屬性來設定觸發滾動的目標物件，支援傳入選擇器或 HTMLElement。
html
js
exportdefault { setup() { const list = [...Array(50).keys()]; return { list }; }, };瞬間滾動
當設定 immediate 屬性後，頁面滾動的過程不再有過渡效果，而是瞬間滾動到頂部。
html
API
Props
| 參數 | 說明 | 類型 | 預設值 |
|---|---|---|---|
| target | 觸發滾動的目標物件，支援傳入選擇器或 DOM 元素，預設最近的父級滾動容器 | *string | HTMLElement* |
| right | 距離頁面右側的距離，預設單位為 px | *number | string* |
| bottom | 距離頁面底部的距離，預設單位為 px | *number | string* |
| offset | 滾動高度達到此參數值時才顯示元件 | number | 200 |
| teleport | 指定掛載的節點，等同於 Teleport 元件的 to 屬性 | *string | Element* |
| immediate v4.0.9 | 是否瞬間滾動到頂部 | boolean | false | | z-index | 設定元件的 z-index 層級 | number | string | 100 |
Events
| 事件名 | 說明 | 回調參數 |
|---|---|---|
| click | 點擊元件時觸發 | event: MouseEvent |
Slots
| 名稱 | 說明 |
|---|---|
| default | 自訂按鈕顯示內容 |
類型定義
元件匯出以下類型定義：
ts
importtype { BackTopProps, BackTopThemeVars } from'vant';主題定製
樣式變數
元件提供了下列 CSS 變數，可用於自訂樣式，使用方法請參考 ConfigProvider 元件。
| 名稱 | 預設值 | 描述 |
|---|---|---|
| --van-back-top-size | 40px | - |
| --van-back-top-icon-size | 20px | - |
| --van-back-top-right | 30px | - |
| --van-back-top-bottom | 40px | - |
| --van-back-top-z-index | 100 | - |
| --van-back-top-text-color | #fff | - |
| --van-back-top-background | var(--van-blue) | - |
📝 總結
BackTop 回到頂部元件是提升使用者體驗的貼心小助手！⬆️ 當使用者在長頁面中瀏覽時，它能提供快速返回頂部的便捷方式，讓頁面導航變得更加友好。透過智慧的顯示邏輯和流暢的滾動動畫，為使用者帶來愉悅的瀏覽體驗。
🎯 核心特性：
- 🎯 智慧顯示：根據滾動距離自動顯示/隱藏
- 📍 靈活定位：支援自訂位置和滾動目標
- 🎨 個性定製：支援自訂內容和樣式
- ⚡ 流暢動畫：平滑的滾動過渡效果
- 🚀 瞬間滾動：支援無過渡的快速返回
無論是長清單、文章頁面還是複雜的表單，BackTop 都能為你的應用增添貼心的導航體驗！