Driver.js 学习笔记

Driver.js 是什么？

Driver.js 是一个轻量级（约 4kb gzip）、无依赖的原生 JavaScript 库，用于在网页中创建用户引导流程。它通过高亮特定元素、锁定用户交互并展示引导弹窗，帮助用户快速理解页面功能。其核心优势包括：

• 无依赖：纯 JavaScript 实现，兼容所有主流浏览器。
• 高度可定制：支持修改按钮文本、背景色、弹窗位置等。
• 轻量灵活：适合集成到 Vue、React 等框架中，也可直接通过 CDN 引入。

安装

CDN 引入

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

NPM 安装

$ npm install driver.js

driver.js 使用是不区分框架的，在Vue和React中都可以以相同的方式引入

import Driver from 'driver.js';
import 'driver.js/dist/driver.min.css';

const driverObj = driver({
  // ...
})

driverObj.drive()

使用

driver.js 最核心的使用方法都来自于Driver实例，driver(options: Config): Driver

最常见的用法是通过Driver实例的highlight和drive方法来突出元素。

类型

driver.js 的核心接口类型如下，这些类型用于创建Driver实例。

interface Config {
  steps?: DriveStep[]; // 引导步骤
  animate?: boolean; // 过渡动画
  overlayColor?: string; // 遮罩颜色
  overlayOpacity?: number; // 遮罩透明度
  smoothScroll?: boolean; // 平滑滚动
  allowClose?: boolean; // 允许关闭
  overlayClickBehavior?: "close" | "nextStep"; // 遮罩点击动作
  stagePadding?: number; // 突出元素切口之间的距离
  stageRadius?: number; // 突出元素切口半径
  disableActiveInteraction?: boolean; // 禁用突出元素的交互
  allowKeyboardControl?: boolean; // 允许键盘控制

  // 弹窗配置
  popoverClass?: string; // 弹窗自定义类名
  popoverOffset?: number; // 弹窗偏移
  showButtons?: AllowedButtons[]; // 显示按钮
  disableButtons?: AllowedButtons[]; // 禁用按钮
  showProgress?: boolean; // 显示进度

  // 按钮文案
  progressText?: string; // 进度文案
  nextBtnText?: string; // 下一步按钮文案
  prevBtnText?: string; // 上一步按钮文案
  doneBtnText?: string; // 完成按钮文案

  // 弹窗渲染回调
  onPopoverRender?: (popover: PopoverDOM, opts: { config: Config; state: State, driver: Driver }) => void;

  // 状态变更回调
  onHighlightStarted?: DriverHook; // 突出元素开始显示
  onHighlighted?: DriverHook; // 突出元素显示完成
  onDeselected?: DriverHook; // 取消选择
  onDestroyStarted?: DriverHook; // 突出元素开始取消
  onDestroyed?: DriverHook; // 突出元素取消完成

  // 按钮事件
  onNextClick?: DriverHook; // 下一步点击
  onPrevClick?: DriverHook; // 上一步点击
  onCloseClick?: DriverHook; // 关闭点击
}

上面是driver对象的全局配置，我们还可以通过steps对每一个引导步骤进行配置

interface DriveStep {
  element: ELement | string; // 要突出显示的元素或者css选择器
  popover?: { // 弹窗配置
    title?: string;
    description?: string;
    side?: "top" | "right" | "bottom" | "left";
    align?: "start" | "center" | "end";
    showButtons?: AllowedButtons[]; // 显示按钮
    disableButtons?: AllowedButtons[]; // 禁用按钮
    nextBtnText?: string; // 下一步按钮文案
    prevBtnText?: string; // 上一步按钮文案
    doneBtnText?: string; // 完成按钮文案
    showProgress?: boolean; // 显示进度
    popoverClass?: string; // 弹窗自定义类名
    onPopoverRender?: (popover: PopoverDOM, opts: { config: Config; state: State,}) => void;
    onNextClick?: (popover: PopoverDOM, opts: { config: Config; state: State,}) => void;
    onPrevClick?: (popover: PopoverDOM, opts: { config: Config; state: State,}) => void;
    onCloseClick?: (popover: PopoverDOM, opts: { config: Config; state: State,}) => void;
  };
  onDeselected?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
  onHighlightStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
  onHighlighted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;
}

上面列举了一些生命周期的hook，各个hook的触发时机如下

API

下面的表格里面列出了driver实例上的一些方法，我们可以利用这些方法操作引导交互。

自定义样式

driver.js 支持自定义引导的样式，只需要覆写下面的样式即可

/* popover包装器 */
.driver-popover {}

/* 指向突出显示的元素的箭头 */
.driver-popover-arrow {}

/* 标题和描述 */
.driver-popover-title {}
.driver-popover-description {}

/* 关闭按钮 */
.driver-popover-close-btn {}

/* 底部进度条和操作按钮 */
.driver-popover-footer {}
.driver-popover-progress-text {}
.driver-popover-prev-btn {}
.driver-popover-next-btn {}

demo

我预制了一段demo代码，可以点击下面的按钮来看一下driver引导效果

const driverObject = driver({
  showProgress: true,
  doneBtnText: '我会了',
  prevBtnText: '上一步',
  nextBtnText: '下一步',
  overlayColor: 'red',
  popoverClass: "custom-popover-class",
  onDestroyStarted: () => {
    if(!driverObject.hasNextStep() || confirm('确定要离开吗？')) {
        driverObject.destroy();
    }
  },
  steps: [
    {
      element: '#type',
      popover: {
        title: '配置类型',
        description: '这里列举了driver函数支持的配置类型',
        side: "right",
        align:'start'
      }
    },
    {
      element: '#methodDrive',
      popover: {
        title: 'drive',
        description: '我们可以通过这个方法来开启引导',
        side: "bottom",
        align: 'start'
      }
    }
  ]
})