# Hints 功能提示

URL: https://caijiao.org/driver-js/03-advanced/03-hints
Source: docs/driver-js/03-advanced/03-hints.md
Description: 讲解 Driver.js hints 入口的使用方式，适合给页面元素添加轻量提示点、功能标记和非阻塞说明。

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

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

## 引入 hints

Hints 使用独立入口：

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

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

## 基本用法

```js
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)` 控制具体提示。

```js
productHints.open("keyboard-shortcuts");
```

## 代码演示

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

[在线代码演示](/driver-js/demos/4-hints.html)

## Hints 与 Tour 的区别

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

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

## 动态显示 Hints

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

```js
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

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

```js
productHints.hide();
```

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

## 使用建议

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