菜鸟教程
教程 driver-js tutorial

安装与样式引入

Driver.js 可以通过包管理器安装，也可以直接用 CDN。现代前端项目建议使用 npm 包，因为这样更方便参与构建、类型提示和版本管理。

使用包管理器安装

根据项目使用的包管理器选择一个命令即可：

bash 
npm install driver.js
bash 
pnpm add driver.js
bash 
yarn add driver.js

安装后，在入口文件或具体页面模块中导入：

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

driver 是创建实例的函数，driver.css 是默认样式。没有引入 CSS 时，遮罩、弹层和按钮可能无法正确显示。

在 HTML 中使用 CDN

如果只是做静态页面示例，可以直接引入 CDN 文件：

html 
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/driver.js@latest/dist/driver.css">
<script src="https://cdn.jsdelivr.net/npm/driver.js@latest/dist/driver.js.iife.js"></script>

<button id="start-tour">开始引导</button>
<button id="create-project">创建项目</button>

<script>
  const driverObj = window.driver.js.driver();

  document.querySelector("#start-tour").addEventListener("click", () => {
    driverObj.highlight({
      element: "#create-project",
      popover: {
        title: "创建项目",
        description: "点击这里创建你的第一个项目。",
      },
    });
  });
</script>

生产项目中不建议长期使用 @latest，因为它会跟随最新版本变化。上线项目应固定版本号，便于排查和回滚。

检查是否安装成功

可以先写一个最小按钮验证：

html 
<button id="help-button">帮助</button>
js 
import { driver } from "driver.js";
import "driver.js/dist/driver.css";

const driverObj = driver();

document.querySelector("#help-button").addEventListener("click", () => {
  driverObj.highlight({
    element: "#help-button",
    popover: {
      title: "帮助按钮",
      description: "这个按钮用于打开当前页面的帮助信息。",
    },
  });
});

如果点击后出现遮罩、高亮框和说明弹层，说明安装和样式引入都正常。

常见安装问题

问题 原因 处理方式
弹层没有样式 忘记引入 driver.css 在入口或组件中导入 CSS
构建时报找不到包 依赖没有安装到当前项目 确认 package.json 和锁文件，重新安装依赖
CDN 示例无法运行 脚本加载失败或全局对象写错 检查网络请求，使用 window.driver.js.driver()
页面没有高亮目标 选择器没有匹配元素 确认元素已经渲染，并检查选择器拼写

版本确认

本教程以 Driver.js 1.x API 为主。需要确认当前安装版本时，可以运行：

bash 
npm view driver.js version

项目中已安装的版本可以查看：

bash 
npm list driver.js

相关内容