# 单点高亮

URL: https://caijiao.org/driver-js/02-basics/02-highlight
Source: docs/driver-js/02-basics/02-highlight.md
Description: 讲解 Driver.js highlight 方法的使用方式，适合新功能提示、按钮说明、表单字段提示和一次性页面说明。

如果不需要完整的分步导览，只想解释页面上的一个元素，可以使用 `highlight()`。

`highlight()` 适合新功能提示、按钮说明、表单字段解释、空状态引导等场景。

## 基本用法

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

const driverObj = driver();

driverObj.highlight({
  element: "#export-button",
  popover: {
    title: "导出数据",
    description: "点击这里可以把当前筛选结果导出为 CSV 文件。",
    side: "bottom",
    align: "end",
  },
});
```

`highlight()` 接收的对象和 `steps` 中的单个 step 很像，都可以设置 `element` 和 `popover`。

## 点击按钮后显示提示

更常见的做法是给帮助按钮绑定事件：

```js
const driverObj = driver();

document.querySelector("#show-export-help").addEventListener("click", () => {
  driverObj.highlight({
    element: "#export-button",
    popover: {
      title: "导出数据",
      description: "导出内容会包含当前筛选条件下的所有记录。",
    },
  });
});
```

## 代码演示

点击演示中的“说明导出”按钮，可以看到只针对一个按钮的单点高亮。

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

## 首次展示新功能

新功能上线后，可以只对未看过的用户展示一次：

```js
const FEATURE_KEY = "feature-export-2026-09";
const driverObj = driver();

if (!localStorage.getItem(FEATURE_KEY)) {
  driverObj.highlight({
    element: "#export-button",
    popover: {
      title: "新增导出功能",
      description: "现在可以直接导出当前列表数据。",
    },
  });

  localStorage.setItem(FEATURE_KEY, "1");
}
```

如果你的应用有用户系统，可以把“是否展示过”记录到服务端，而不是只放在当前浏览器。

## 高亮 DOM 元素

`element` 不只能写字符串，也可以传入真实 DOM 元素：

```js
const button = document.querySelector("#save-button");

if (button) {
  driverObj.highlight({
    element: button,
    popover: {
      title: "保存",
      description: "保存后，修改会立即对团队成员可见。",
    },
  });
}
```

在组件化框架中，这种写法常和 ref 一起使用。

## 关闭当前高亮

用户可以通过内置按钮关闭高亮。代码中也可以调用实例方法销毁当前引导：

```js
driverObj.destroy();
```

例如路由切换、弹窗关闭、用户权限变化时，应主动清理当前高亮，避免遮罩停留在错误页面。

## 单点提示的写作建议

| 建议 | 示例 |
| --- | --- |
| 说明用途 | “点击这里可以导出当前列表” |
| 说明条件 | “只有管理员可以看到这个入口” |
| 说明后果 | “删除后不可恢复，请谨慎操作” |
| 避免空话 | 不要只写“这是一个按钮” |

单点提示要短。用户点开之后，应该立刻知道下一步做什么。