垦荒学园

简体中文

English

简体中文

English

切换主题

Bootstrap 提示框 ​

🎯 概述 ​

Bootstrap 提示框（Tooltips）是一个小型的弹出提示组件，当用户将鼠标悬停在元素上时显示。常用于提供额外的说明信息或帮助文本。

📦 基本用法 ​

html
<button type="button" class="btn btn-secondary" 
        data-bs-toggle="tooltip" 
        data-bs-placement="top"
        data-bs-title="这是一个提示框">
    悬停查看提示
</button>

<script>
// 必须手动初始化提示框
const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]');
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl));
</script>

📍 提示框位置 ​

html
<!-- 顶部 -->
<button type="button" class="btn btn-secondary" 
        data-bs-toggle="tooltip" 
        data-bs-placement="top"
        data-bs-title="顶部提示">
    顶部
</button>

<!-- 右侧 -->
<button type="button" class="btn btn-secondary" 
        data-bs-toggle="tooltip" 
        data-bs-placement="right"
        data-bs-title="右侧提示">
    右侧
</button>

<!-- 底部 -->
<button type="button" class="btn btn-secondary" 
        data-bs-toggle="tooltip" 
        data-bs-placement="bottom"
        data-bs-title="底部提示">
    底部
</button>

<!-- 左侧 -->
<button type="button" class="btn btn-secondary" 
        data-bs-toggle="tooltip" 
        data-bs-placement="left"
        data-bs-title="左侧提示">
    左侧
</button>

🎨 HTML 内容 ​

html
<button type="button" class="btn btn-secondary" 
        data-bs-toggle="tooltip" 
        data-bs-html="true"
        data-bs-title="<em>斜体</em> 和 <strong>粗体</strong>">
    HTML 提示
</button>

💻 JavaScript API ​

初始化 ​

javascript
// 初始化单个提示框
const tooltip = new bootstrap.Tooltip('#myTooltip', {
    placement: 'top',
    trigger: 'hover',
    delay: { show: 500, hide: 100 }
});

// 初始化所有提示框
const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]');
[...tooltipTriggerList].map(el => new bootstrap.Tooltip(el));

方法 ​

javascript
const myTooltip = document.getElementById('myTooltip');
const tooltip = bootstrap.Tooltip.getInstance(myTooltip);

// 显示提示框
tooltip.show();

// 隐藏提示框
tooltip.hide();

// 切换提示框
tooltip.toggle();

// 销毁提示框
tooltip.dispose();

// 启用提示框
tooltip.enable();

// 禁用提示框
tooltip.disable();

// 更新提示框位置
tooltip.update();

配置选项 ​

javascript
const options = {
    animation: true,           // 是否使用动画
    container: false,          // 容器元素
    delay: 0,                  // 延迟显示/隐藏（毫秒）
    html: false,               // 是否允许 HTML
    placement: 'top',          // 位置
    title: '',                 // 提示文本
    trigger: 'hover focus',    // 触发方式
    offset: [0, 0],           // 偏移量
    customClass: ''           // 自定义类名
};

🎭 事件监听 ​

javascript
const myTooltip = document.getElementById('myTooltip');

// 即将显示时触发
myTooltip.addEventListener('show.bs.tooltip', event => {
    console.log('即将显示提示框');
});

// 显示完成后触发
myTooltip.addEventListener('shown.bs.tooltip', event => {
    console.log('提示框已显示');
});

// 即将隐藏时触发
myTooltip.addEventListener('hide.bs.tooltip', event => {
    console.log('即将隐藏提示框');
});

// 隐藏完成后触发
myTooltip.addEventListener('hidden.bs.tooltip', event => {
    console.log('提示框已隐藏');
});

🌟 实际示例 ​

html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Bootstrap 提示框示例</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
    <div class="container my-5">
        <h1>Bootstrap 提示框示例</h1>
        
        <!-- 四个方向的提示框 -->
        <h2>提示框位置</h2>
        <div class="mb-4">
            <button type="button" class="btn btn-secondary me-2" 
                    data-bs-toggle="tooltip" 
                    data-bs-placement="top"
                    data-bs-title="顶部提示框">
                顶部
            </button>
            <button type="button" class="btn btn-secondary me-2" 
                    data-bs-toggle="tooltip" 
                    data-bs-placement="right"
                    data-bs-title="右侧提示框">
                右侧
            </button>
            <button type="button" class="btn btn-secondary me-2" 
                    data-bs-toggle="tooltip" 
                    data-bs-placement="bottom"
                    data-bs-title="底部提示框">
                底部
            </button>
            <button type="button" class="btn btn-secondary" 
                    data-bs-toggle="tooltip" 
                    data-bs-placement="left"
                    data-bs-title="左侧提示框">
                左侧
            </button>
        </div>
        
        <!-- HTML 内容提示框 -->
        <h2>HTML 内容</h2>
        <div class="mb-4">
            <button type="button" class="btn btn-primary" 
                    data-bs-toggle="tooltip" 
                    data-bs-html="true"
                    data-bs-title="<strong>粗体文本</strong><br><em>斜体文本</em>">
                HTML 提示框
            </button>
        </div>
        
        <!-- 不同颜色的按钮 -->
        <h2>不同按钮样式</h2>
        <div class="mb-4">
            <button type="button" class="btn btn-primary me-2" 
                    data-bs-toggle="tooltip" 
                    data-bs-title="主要按钮提示">
                Primary
            </button>
            <button type="button" class="btn btn-success me-2" 
                    data-bs-toggle="tooltip" 
                    data-bs-title="成功按钮提示">
                Success
            </button>
            <button type="button" class="btn btn-danger me-2" 
                    data-bs-toggle="tooltip" 
                    data-bs-title="危险按钮提示">
                Danger
            </button>
            <button type="button" class="btn btn-warning me-2" 
                    data-bs-toggle="tooltip" 
                    data-bs-title="警告按钮提示">
                Warning
            </button>
            <button type="button" class="btn btn-info" 
                    data-bs-toggle="tooltip" 
                    data-bs-title="信息按钮提示">
                Info
            </button>
        </div>
        
        <!-- 链接上的提示框 -->
        <h2>链接提示框</h2>
        <div class="mb-4">
            <p>
                这是一段文本，包含一个
                <a href="#" data-bs-toggle="tooltip" data-bs-title="这是链接的提示信息">带提示的链接</a>
                和更多内容。
            </p>
        </div>
        
        <!-- 图标按钮 -->
        <h2>图标按钮提示</h2>
        <div class="mb-4">
            <button type="button" class="btn btn-outline-primary me-2" 
                    data-bs-toggle="tooltip" 
                    data-bs-title="编辑">
                <svg width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
                    <path d="M12.146.146a.5.5 0 0 1 .708 0l3 3a.5.5 0 0 1 0 .708l-10 10a.5.5 0 0 1-.168.11l-5 2a.5.5 0 0 1-.65-.65l2-5a.5.5 0 0 1 .11-.168l10-10zM11.207 2.5 13.5 4.793 14.793 3.5 12.5 1.207 11.207 2.5zm1.586 3L10.5 3.207 4 9.707V10h.5a.5.5 0 0 1 .5.5v.5h.5a.5.5 0 0 1 .5.5v.5h.293l6.5-6.5zm-9.761 5.175-.106.106-1.528 3.821 3.821-1.528.106-.106A.5.5 0 0 1 5 12.5V12h-.5a.5.5 0 0 1-.5-.5V11h-.5a.5.5 0 0 1-.468-.325z"/>
                </svg>
            </button>
            <button type="button" class="btn btn-outline-danger me-2" 
                    data-bs-toggle="tooltip" 
                    data-bs-title="删除">
                <svg width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
                    <path d="M5.5 5.5A.5.5 0 0 1 6 6v6a.5.5 0 0 1-1 0V6a.5.5 0 0 1 .5-.5zm2.5 0a.5.5 0 0 1 .5.5v6a.5.5 0 0 1-1 0V6a.5.5 0 0 1 .5-.5zm3 .5a.5.5 0 0 0-1 0v6a.5.5 0 0 0 1 0V6z"/>
                    <path fill-rule="evenodd" d="M14.5 3a1 1 0 0 1-1 1H13v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V4h-.5a1 1 0 0 1-1-1V2a1 1 0 0 1 1-1H6a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1h3.5a1 1 0 0 1 1 1v1zM4.118 4 4 4.059V13a1 1 0 0 0 1 1h6a1 1 0 0 0 1-1V4.059L11.882 4H4.118zM2.5 3V2h11v1h-11z"/>
                </svg>
            </button>
            <button type="button" class="btn btn-outline-success" 
                    data-bs-toggle="tooltip" 
                    data-bs-title="保存">
                <svg width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
                    <path d="M2 1a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1V2a1 1 0 0 0-1-1H9.5a1 1 0 0 0-1 1v7.293l2.646-2.647a.5.5 0 0 1 .708.708l-3.5 3.5a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L7.5 9.293V2a2 2 0 0 1 2-2H14a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V2a2 2 0 0 1 2-2h2.5a.5.5 0 0 1 0 1H2z"/>
                </svg>
            </button>
        </div>
        
        <!-- 表单字段提示 -->
        <h2>表单字段提示</h2>
        <form class="mb-4">
            <div class="mb-3">
                <label for="username" class="form-label">
                    用户名
                    <span data-bs-toggle="tooltip" data-bs-title="用户名必须是 3-20 个字符">ℹ️</span>
                </label>
                <input type="text" class="form-control" id="username">
            </div>
            <div class="mb-3">
                <label for="email" class="form-label">
                    邮箱
                    <span data-bs-toggle="tooltip" data-bs-title="请输入有效的邮箱地址">ℹ️</span>
                </label>
                <input type="email" class="form-control" id="email">
            </div>
        </form>
        
        <!-- JavaScript 控制 -->
        <h2>JavaScript 控制</h2>
        <div class="mb-4">
            <button type="button" class="btn btn-primary me-2" id="jsTooltip">
                可控制的提示框
            </button>
            <button type="button" class="btn btn-success me-2" id="showBtn">显示</button>
            <button type="button" class="btn btn-warning me-2" id="hideBtn">隐藏</button>
            <button type="button" class="btn btn-danger" id="toggleBtn">切换</button>
        </div>
    </div>
    
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
    <script>
        // 初始化所有提示框
        const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]');
        const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl));
        
        // JavaScript 控制示例
        const jsTooltipEl = document.getElementById('jsTooltip');
        const jsTooltip = new bootstrap.Tooltip(jsTooltipEl, {
            title: '这是通过 JavaScript 控制的提示框',
            trigger: 'manual'
        });
        
        document.getElementById('showBtn').addEventListener('click', () => {
            jsTooltip.show();
        });
        
        document.getElementById('hideBtn').addEventListener('click', () => {
            jsTooltip.hide();
        });
        
        document.getElementById('toggleBtn').addEventListener('click', () => {
            jsTooltip.toggle();
        });
        
        // 监听提示框事件
        jsTooltipEl.addEventListener('shown.bs.tooltip', () => {
            console.log('提示框已显示');
        });
    </script>
</body>
</html>

✅ 最佳实践 ​

1. 可访问性 ​

html
<!-- 为禁用元素添加提示框 -->
<span class="d-inline-block" data-bs-toggle="tooltip" data-bs-title="禁用按钮的提示">
    <button class="btn btn-primary" type="button" disabled>禁用按钮</button>
</span>

2. 性能优化 ​

javascript
// 使用事件委托初始化提示框
document.body.addEventListener('mouseenter', event => {
    if (event.target.hasAttribute('data-bs-toggle') && 
        event.target.getAttribute('data-bs-toggle') === 'tooltip') {
        const tooltip = bootstrap.Tooltip.getOrCreateInstance(event.target);
        tooltip.show();
    }
}, true);

3. 响应式设计 ​

javascript
// 在小屏幕上禁用提示框
if (window.innerWidth < 768) {
    const tooltips = document.querySelectorAll('[data-bs-toggle="tooltip"]');
    tooltips.forEach(el => {
        const tooltip = bootstrap.Tooltip.getInstance(el);
        if (tooltip) {
            tooltip.disable();
        }
    });
}

🎯 常见应用场景 ​

  1. 图标按钮 - 说明按钮功能
  2. 表单字段 - 提供输入提示
  3. 链接说明 - 解释链接目标
  4. 功能说明 - 简短的功能介绍
  5. 帮助信息 - 提供额外帮助

下一步 ​

现在你已经掌握了 Bootstrap 提示框的使用方法，接下来我们将学习弹出框组件。

下一章：Bootstrap 弹出框 →