BackTop 回到顶部 - Vant 4
BackTop 回到顶部
⬆️ 介绍
回到顶部组件为用户提供了便捷的页面导航体验！当页面内容较长时，一键返回顶部，让浏览更加轻松愉快。
📦 引入
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
js
import { createApp } from'vue'; import { BackTop } from'vant'; 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 都能为你的应用增添贴心的导航体验！