Floating-Vue 指令式工具提示使用指南

Floating-Vue 指令式工具提示使用指南

floating-vue 💬 Easy tooltips, popovers, dropdown, menus... for Vue 项目地址: https://gitcode.com/gh_mirrors/fl/floating-vue

指令式工具提示基础用法

Floating-Vue 提供了 v-tooltip 指令来快速创建工具提示效果。这是最直接的实现方式，适合大多数简单场景。

基本语法格式如下：

<button v-tooltip="'提示内容'">悬停我</button>

指令值可以是字符串或响应式属性：

<button v-tooltip="dynamicContent">悬停我</button>

工具提示位置控制

通过添加修饰符可以轻松控制工具提示的显示位置：

<button v-tooltip.top-start="'顶部起始位置提示'">
<button v-tooltip.bottom-end="'底部结束位置提示'">

支持的位置修饰符包括：

• top, top-start, top-end
• bottom, bottom-start, bottom-end
• left, left-start, left-end
• right, right-start, right-end

对象形式的高级配置

当需要更复杂的控制时，可以使用对象形式的配置：

<button v-tooltip="{
  content: '详细提示内容',
  placement: 'bottom',
  delay: 200
}">悬停我</button>

对象中可以配置所有组件支持的属性，实现更精细的控制。

安全地显示HTML内容

默认情况下，内容会被转义为纯文本以防止XSS攻击。如需显示HTML内容，必须显式启用：

<button v-tooltip="{
  content: '<b>加粗文本</b> <i>斜体文本</i>',
  html: true
}">HTML提示</button>

启用HTML功能时，请确保内容来源可信，避免XSS安全风险。

异步内容加载

工具提示支持异步加载内容，适合需要从API获取数据的场景：

<button v-tooltip="{
  content: fetchData,
  loadingContent: '加载中...'
}">获取数据</button>

可以自定义加载状态的样式：

.v-popper--tooltip-loading .v-popper__inner {
  color: #77aaff;
  font-style: italic;
}

如需传递参数给异步方法，可使用箭头函数：

<button v-tooltip="{
  content: () => fetchUserData(userId)
}">用户信息</button>

手动触发控制

通过组合 triggers 和 shown 属性，可以实现手动控制工具提示：

<button
  v-tooltip="{
    content: '手动控制提示',
    shown: isTooltipVisible,
    triggers: []
  }"
>点击显示提示</button>

这种模式下，工具提示的显示/隐藏完全由 shown 属性控制。

移动端适配策略

在移动设备上，工具提示可能不是最佳交互方式。可以全局禁用：

FloatingVue.options.themes.tooltip.disabled = window.innerWidth <= 768

也可以在特定元素上覆盖全局设置：

<button v-tooltip="{
  content: '移动端也显示的提示',
  disabled: false
}">重要按钮</button>

最佳实践建议

1. 对于简单提示，优先使用指令式语法，代码更简洁
2. 复杂场景使用对象形式配置，提高可读性和可维护性
3. 异步内容提供加载状态反馈，提升用户体验
4. 移动端考虑禁用或替换为点击触发方式
5. HTML内容务必验证来源，防止XSS攻击

通过合理运用这些指令特性，可以创建出既美观又实用的工具提示效果。

floating-vue 💬 Easy tooltips, popovers, dropdown, menus... for Vue 项目地址: https://gitcode.com/gh_mirrors/fl/floating-vue