FloatingPanel 浮动面板 - Vant 4
📱 FloatingPanel 浮动面板
🎯 介绍
想象一下，有一个神奇的抽屉从屏幕底部悄悄探出头来，就像一个害羞的小精灵等待着被发现！🧚♀️ FloatingPanel 浮动面板就是这样一个充满魅力的组件。
它静静地停靠在页面底部，用户只需轻轻一拖，就能唤醒这个沉睡的面板，让它优雅地展开，露出隐藏的宝藏内容！无论是展示详细信息、提供快捷操作，还是创建多层级的内容展示，FloatingPanel 都能带来如丝般顺滑的交互体验。✨
就像手机上的控制中心一样，用户可以随心所欲地拖拽面板到不同的高度，每一次滑动都充满了探索的乐趣！
💡 温馨提示：请确保你的
vant版本 >= 4.5.0 才能使用这个优雅的组件哦！
📦 引入
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from'vue'; import { FloatingPanel } from'vant'; const app = createApp(); app.use(FloatingPanel);🎯 代码演示
🔧 基础用法
让我们从最简单的开始！🚀 FloatingPanel 就像一个乖巧的小宠物，默认时只露出 100px 的小脑袋在屏幕底部。但当用户轻轻一拖，它就会兴奋地跳起来，展开到屏幕高度的 60%，就像一只被唤醒的小猫咪伸懒腰一样可爱！
⚓ 自定义锚点
想要让面板更加智能吗？🎯 通过 anchors 属性，你可以为面板设置多个"停车位"！就像电梯有不同的楼层一样，面板会在这些预设的高度位置智能停靠。
配合 v-model:height 双向绑定，你还能精确控制面板当前的"楼层"位置。比如，让面板在三个黄金位置停靠：100px（一楼大厅）、40% 屏幕高度（二楼展厅）和 70% 屏幕高度（三楼全景）：
import { ref } from'vue'; exportdefault { setup() { const anchors = [ 100, Math.round(0.4 * window.innerHeight), Math.round(0.7 * window.innerHeight), ]; const height = ref(anchors[0]); return { anchors, height }; }, };🎮 仅头部拖拽
有时候你可能希望面板内容区域专心做自己的事情，不被"打扰"！🎭 默认情况下，FloatingPanel 的头部和内容区域都是"热情好客"的，用户在任何地方都能拖拽面板。
但如果你想让内容区域专注于滚动或其他交互，可以通过设置 content-draggable="false" 来让它"专心工作"，只允许用户通过头部区域来控制面板的升降。就像给面板戴上了一顶"指挥帽"！👑
API
Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:height | 当前面板的显示高度 | *number | string* |
| anchors | 设置自定义锚点，就像给面板安装电梯楼层按钮 🏢 | number[] | [100, window.innerHeight * 0.6] |
| duration | 动画时长，控制面板升降的优雅程度 ⏱️ | *number | string* |
| content-draggable | 允许拖拽内容容器，让内容区域也能"参与"拖拽 🎮 | boolean | true |
lock-scroll v4.6.4 | 当不拖拽时，是否锁定背景滚动，防止"一心二用" 🔒 | boolean | false |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| height-change | 面板显示高度改变且结束拖动后触发 | { height: number } |
Slots
| Name | Description |
|---|---|
| default | 自定义面板内容 |
| header | 自定义面板标头 |
类型定义
组件导出以下类型定义：
importtype { FloatingPanelProps } from'vant';主题定制
样式变量
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| Name | Default Value | Description |
|---|---|---|
| --van-floating-panel-border-radius | 16px | - |
| --van-floating-panel-header-height | 30px | - |
| --van-floating-panel-z-index | 999 | - |
| --van-floating-panel-background | var(--van-background-2) | - |
| --van-floating-panel-bar-width | 20px | - |
| --van-floating-panel-bar-height | 3px | - |
| --van-floating-panel-bar-color | var(--van-gray-5) | - |
📚 相关文档
FloatingPanel 浮动面板与这些组件搭配使用，能创造出更丰富的交互体验：
- Popup 弹出层 - 另一种内容展示方式，更适合模态交互 🎪
- ActionSheet 动作面板 - 从底部弹出的操作选择面板 📋
- Overlay 遮罩层 - 为面板添加背景遮罩效果 🎭
- PullRefresh 下拉刷新 - 面板内容的刷新交互 🔄
- FloatingBubble 浮动气泡 - 触发面板的悬浮按钮 🫧
- BackTop 回到顶部 - 面板内容的快速导航 🚀
- Sticky 粘性定位 - 面板内的固定元素 📌
- List 列表 - 面板内容的常见展示形式 📝
- Tab 标签页 - 面板内的多标签内容切换 🏷️