bootstrap tooltip 必须同时设置 data-bs-toggle="tooltip" 和 data-bs-trigger 才生效;data 属性优先级高于 js 配置;focus 触发需元素可聚焦;manual 模式需手动调用 enable()、show()、hide()。
bootstrap tooltip 默认是 hover focus 触发,不显式声明就一定会在悬停或获得焦点时弹出——哪怕你只想点一下才显示,也得手动覆盖。
data-bs-trigger="click" 必须同时配 data-bs-toggle="tooltip"
只写 data-bs-trigger="click" 没用,Bootstrap 5 会忽略它,继续按默认的 hover focus 行事。必须成对出现:
-
data-bs-toggle="tooltip"是启用 Tooltip 的开关,缺了它整个组件不初始化 -
data-bs-trigger="click"是告诉它“别 hover,等我点” - 顺序无关,但两个属性都要写在同一个元素上
错误写法:<button data-bs-trigger="click">点我</button> → 完全没反应
正确写法:<button data-bs-toggle="tooltip" data-bs-trigger="click" data-bs-title="确认删除?">删除</button>
JS 初始化时 trigger 配置优先级低于 data 属性
如果你既写了 data-bs-trigger="hover",又用 JS 调用 new bootstrap.Tooltip(el, { trigger: 'click' }),最终生效的还是 HTML 里的 data-bs-trigger 值。
- Bootstrap 5 明确规定:data 属性配置 > JS 选项配置
- 想用 JS 控制,先清空元素上的
data-bs-trigger、data-bs-title等所有相关属性 - 否则控制台可能不报错,但 tooltip 内容为空或触发逻辑错乱
推荐做法:静态内容全用 data 属性;动态内容(比如从 API 拿标题)才用 JS 初始化,并确保 DOM 上无残留 data 配置。
focus 触发必须让元素可聚焦
data-bs-trigger="focus" 不是写上就灵——<div>、<code><span></span> 这类默认不可聚焦的元素,加了也白加。
- 要么换成
<button></button>或<a href="#"></a>这类原生可聚焦元素 - 要么手动加
tabindex="0",例如:<div tabindex="0" data-bs-toggle="tooltip" data-bs-trigger="focus" data-bs-title="输入说明">姓名</div> - 移动端慎用 focus:Safari 对非表单元素的 focus 支持不稳定,容易失焦即收,不如改用
manual+touchstart
manual 模式要自己管 show/hide 生命周期
设 data-bs-trigger="manual" 后,Tooltip 不再响应任何自动事件,完全交由你调用 show() / hide() 方法控制。
- 常见漏掉的一步:没在
show()前调用enable()—— 尤其是元素刚动态插入 DOM 时,show()会静默失败 - 隐藏时建议用
hide()而不是直接移除 DOM,否则 Popper 定位逻辑可能残留副作用 - 如果要支持点击外部关闭,得自己监听
document.addEventListener('click', ...)并判断点击是否在 tooltip 或触发元素之外
最易被忽略的是:manual 模式下,data-bs-delay 和 data-bs-animation 依然生效,但 show/hide 的时机完全由你决定,别以为设了 delay 就能自动延迟——它只作用于你调用 show() 后的内部计时器。











