Hints 功能提示

除了遮罩式导览，Driver.js 还提供 Hints 功能，用于在页面元素旁边放置轻量提示点。用户点击或悬停提示点时，再看到具体说明。

Hints 更适合非阻塞提示：它不会像完整导览那样接管用户注意力。

引入 hints

Hints 使用独立入口：

import { hints } from "driver.js/hints";
import "driver.js/dist/hints.css";

不同构建环境对 CSS 路径处理方式可能不同，实际项目中以安装包内的文件和官方文档为准。

基本用法

const productHints = hints({
  hints: [
    {
      id: "keyboard-shortcuts",
      element: "#keyboard-shortcuts",
      popover: {
        title: "快捷键",
        description: "点击这里查看当前页面支持的键盘快捷键。",
      },
    },
    {
      id: "notification-settings",
      element: "#notification-settings",
      popover: {
        title: "通知设置",
        description: "可以在这里调整邮件、短信和站内通知。",
      },
    },
  ],
});

productHints.show();

如果只需要打开某一个 hint，可以用 open(id) 控制具体提示。

productHints.open("keyboard-shortcuts");

代码演示

点击演示中的“显示提示点”按钮，可以看到 Hints 在多个功能卡片旁生成轻量提示点。

在线代码演示

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Driver.js Hints 演示</title>
  <link rel="stylesheet" href="/driver-js/vendor/hints.css">
  <style>
    body {
      margin: 0;
      background: #f8fafc;
      color: #172033;
      font-family: Arial, "Microsoft YaHei", sans-serif;
    }
.board {
  max-width: 820px;
  margin: 0 auto;
  padding: 28px 22px;
}

.toolbar {
  display: flex;
  justify-content: space-between;
  gap: 12px;
  margin-bottom: 16px;
}

.toolbar,
.card {
  border: 1px solid #dbe3ef;
  border-radius: 8px;
  background: #fff;
  padding: 16px;
  box-shadow: 0 12px 32px rgba(15, 23, 42, 0.06);
}

.actions {
  display: flex;
  gap: 10px;
}

button {
  cursor: pointer;
  border-radius: 6px;
  padding: 9px 13px;
  font-weight: 700;
}

.primary {
  border: 1px solid #2563eb;
  background: #2563eb;
  color: #fff;
}

.secondary {
  border: 1px solid #cbd5e1;
  background: #fff;
  color: #334155;
}

.grid {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 14px;
}

.card h3 {
  margin: 0 0 8px;
  font-size: 16px;
}

.card p {
  margin: 0;
  color: #64748b;
  line-height: 1.6;
}

</style>
</head>
<body>
<main class="board">
<section class="toolbar">
<strong>功能面板</strong>
<div class="actions">
<button id="show-hints" class="primary" type="button">显示提示点</button>
<button id="hide-hints" class="secondary" type="button">隐藏提示点</button>
</div>
</section>
&lt;section class=&quot;grid&quot;&gt;
  &lt;article id=&quot;shortcuts&quot; class=&quot;card&quot;&gt;
    &lt;h3&gt;快捷键&lt;/h3&gt;
    &lt;p&gt;查看当前页面支持的键盘快捷键。&lt;/p&gt;
  &lt;/article&gt;
  &lt;article id=&quot;automation&quot; class=&quot;card&quot;&gt;
    &lt;h3&gt;自动化&lt;/h3&gt;
    &lt;p&gt;配置定时任务和规则触发器。&lt;/p&gt;
  &lt;/article&gt;
  &lt;article id=&quot;notifications&quot; class=&quot;card&quot;&gt;
    &lt;h3&gt;通知&lt;/h3&gt;
    &lt;p&gt;设置邮件、短信和站内通知。&lt;/p&gt;
  &lt;/article&gt;
&lt;/section&gt;

</main>
<script type="module">
import { hints } from "/driver-js/vendor/hints.mjs";
const productHints = hints({
  hints: [
    {
      id: &quot;shortcuts&quot;,
      element: &quot;#shortcuts&quot;,
      popover: {
        title: &quot;快捷键入口&quot;,
        description: &quot;适合给老用户提供更快的操作方式，但不打断当前流程。&quot;,
      },
    },
    {
      id: &quot;automation&quot;,
      element: &quot;#automation&quot;,
      popover: {
        title: &quot;新增自动化&quot;,
        description: &quot;用提示点标记新功能，比打开完整 Tour 更轻量。&quot;,
      },
    },
  ],
});

document.querySelector(&quot;#show-hints&quot;).addEventListener(&quot;click&quot;, () =&gt; {
  productHints.show();
});

document.querySelector(&quot;#hide-hints&quot;).addEventListener(&quot;click&quot;, () =&gt; {
  productHints.hide();
});

</script>
</body>
</html>

Hints 与 Tour 的区别

对比项	Tour	Hints
用户注意力	强，遮罩并聚焦某个元素	弱，只放置提示点
适合场景	首次导览、关键流程说明	新功能标记、补充说明
是否分步	通常是多步骤	通常相互独立
打扰程度	较高	较低

如果用户必须理解某个流程才能继续使用，选择 Tour。只是告诉用户“这里有新东西”，选择 Hints。

动态显示 Hints

可以根据用户权限、功能开关或页面状态显示不同提示：

const pageHints = [];

if (user.canExport) {
  pageHints.push({
    id: "export",
    element: "#export-button",
    popover: {
      title: "导出数据",
      description: "你现在拥有导出权限，可以导出当前结果。",
    },
  });
}

if (featureFlags.newDashboard) {
  pageHints.push({
    id: "dashboard-switcher",
    element: "#dashboard-switcher",
    popover: {
      title: "新版看板",
      description: "这里可以切换到新版数据看板。",
    },
  });
}

const productHints = hints({ hints: pageHints });
productHints.show();

关闭 Hints

当页面切换或组件卸载时，应该隐藏提示点：

productHints.hide();

在单页应用中，如果没有清理，提示点可能残留在旧页面上。

使用建议

Hints 不要太多，同一屏幕 1 到 3 个更容易被理解。
提示点应该放在稳定元素上，避免跟随动画元素抖动。
已读状态可以记录到 localStorage 或用户配置中。
Hints 的文案要解释“为什么值得注意”，不要只重复按钮名称。