FloatingBubble 浮动气泡 - Vant 4

🫧 FloatingBubble 浮动气泡

🎯 介绍

想象一下，有一个可爱的小气泡静静地漂浮在你的页面角落，就像一个贴心的小助手，随时等待着为用户提供帮助！🎈 FloatingBubble 浮动气泡组件就是这样一个神奇的存在。

它不仅可以优雅地悬浮在页面边缘，还拥有超能力 —— 支持自由拖拽和智能磁吸！用户可以随心所欲地把它拖到任何位置，而它会聪明地吸附到最合适的边缘。无论是客服入口、快捷操作，还是返回顶部，FloatingBubble 都能让常用功能触手可及！✨

💡 温馨提示：请确保你的 vant 版本 >= 4.6.0 才能使用这个可爱的组件哦！

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from'vue'; import { FloatingBubble } from'vant'; const app = createApp(); app.use(FloatingBubble);

🎯 代码演示

🔧 基础用法

让我们从最简单的开始！🚀 浮动气泡就像一个乖巧的小宠物，默认会安静地待在右下角。你可以上下拖拽它（只能在 y 轴方向移动哦），就像在逗一只可爱的小猫咪！通过 icon 属性，你可以给它换上不同的"表情"，让它更符合你的应用风格。

import { showToast } from'vant'; exportdefault { setup() { constonClick = () => { showToast('点击气泡'); }; return { onClick }; }, };

🎮 自由拖拽和磁吸

现在让我们释放气泡的全部潜能！🌟 设置 axis="xy" 后，小气泡就获得了完全的自由 —— 它可以在屏幕上任意飞翔！更神奇的是，当你松手时，它会像有磁力一样自动吸附到最近的边缘，就像找到了最舒适的"停车位"。这种智能磁吸效果让用户体验更加流畅自然！

import { showToast } from'vant'; exportdefault { setup() { constonOffsetChange = (offset) => { showToast(`x: ${offset.x.toFixed(0)}, y: ${offset.y.toFixed(0)}`); }; return { onOffsetChange }; }, };

🔄 双向绑定

想要精确控制气泡的位置？没问题！🎯 使用 v-model:offset 就像给气泡装上了GPS定位系统，你可以通过代码精确地告诉它应该出现在哪里。无论是响应用户操作还是根据业务逻辑动态调整位置，双向绑定让一切都变得简单而优雅！

import { ref } from'vue'; exportdefault { setup() { const offset = ref({ x: 200, y: 400 }); return { offset }; }, };

API

Props

参数	说明	类型	默认值
v-model:offset	控制气泡位置	OffsetType	默认右下角坐标
axis	拖拽的方向，xy 代表自由拖拽，lock 代表禁止拖拽 🔒	*'x'	'y'
magnetic	自动磁吸的方向，让气泡像磁铁一样聪明吸附 🧲	*'x'	'y'*
icon	气泡图标名称或图片链接，给气泡换个可爱的表情 😊	string	-

| gap | 气泡与窗口的最小间距，就像给气泡设置安全距离 📏 | number | { x: number, y: number } | 24 | | teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | body |

Events

事件名	说明	回调参数
click	点击组件时触发	MouseEvent
offset-change	由用户拖拽导致位置改变后触发	{x: string, y: string}

Slots

名称	说明
default	自定义气泡显示内容

类型定义

组件导出以下类型定义：

exporttype { FloatingBubbleProps, FloatingBubbleAxis, FloatingBubbleMagnetic, FloatingBubbleOffset, } from'vant';

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-floating-bubble-size	48px	-
--van-floating-bubble-initial-gap	24px	-
--van-floating-bubble-icon-size	28px	-
--van-floating-bubble-background	var(--van-primary-color)	-
--van-floating-bubble-color	var(--van-background-2)	-
--van-floating-bubble-z-index	999	-
--van-floating-bubble-border-radius	--van-floating-bubble-border-radius	-

📚 相关文档

FloatingBubble 浮动气泡与这些组件搭配使用，能创造出更丰富的交互体验：

• BackTop 回到顶部 - 另一个悬浮助手，专门负责快速返回页面顶部 🚀
• Icon 图标 - 为气泡提供各种生动表情的图标库 🎭
• Button 按钮 - 可以作为气泡的触发器或内容展示 🔘
• Overlay 遮罩层 - 配合气泡创建模态交互效果 🎪
• Popup 弹出层 - 气泡点击后的内容展示容器 📦
• ActionSheet 动作面板 - 气泡触发的操作选择面板 📋
• Toast 轻提示 - 气泡操作后的反馈提示 💬
• Dialog 弹出框 - 气泡触发的确认或信息对话框 💭