Driver.js，Web应用的老司机，一个强大的产品导览插件

随着Web应用的复杂性和功能性的不断提升，如何有效地引导用户了解并熟悉应用的功能和界面变得至关重要。Driver.js是一个轻量级的、无依赖的库，专为在Web应用中添加用户引导和提示而设计。本文将详细介绍Driver.js的功能、优势以及如何使用它来提升用户体验。

一、介绍

Driver.js是一个轻量级的Javascript类库，可用于产品导览、亮点、上下文帮助等，从而一步一步地导览用户快速熟悉产品功能。强大的、高度可定制的原生JavaScript引擎，用于导览用户关注页面重点内容。无外部依赖，轻量级，支持所有主流浏览器，并且高度可定制。

特点：

支持所有主流浏览器：包括Chrome，IE9+、Safari、Firefox、Opera等。
可运行于移动手机端：除了电脑、平板，还适配手机端。

高度可定制：拥有强大的API，可以根据您的需求进行任意使用。

轻量级：压缩后仅5KB，相较于其他库（通常超过12KB压缩后）更小巧。

无依赖：使用简单，完全没有外部依赖。

功能丰富：为您的网络应用程序创建强大的特效介绍。

MIT许可：个人和商业用途均免费。
使用便捷：所有操作都可以通过键盘控制。

高亮任何内容：可以在页面上高亮任何元素。

得益于其可扩展的API，Driver.js可以用于更广泛的用户场景。

导览用户：通过解释如何使用您的产品并回答常见问题来导览您的用户。
移除干扰：通过高亮功能，您可以移除干扰，让用户的注意力集中在重要的事情上。
上下文帮助：为您的用户提供上下文帮助，解释如何使用您的产品并回答常见问题。
功能推荐：高亮新功能，解释如何使用它们，并确保您的用户不会错过它们。

二、安装及使用

# Using npm
npm install driver.js

# Using pnpm
pnpm install driver.js

# Using yarn
yarn add driver.js

或者，您可以使用CDN并在HTML文件中包含脚本：

<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"/>

安装完成后，您可以在项目中导入该包。以下示例展示了如何高亮一个元素：

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

const driverObj = driver();
driverObj.highlight({
  element: "#some-element",
  popover: {
    title: "Title",
    description: "Description"
  }
});

如果您正在使用CDN，您将需要从window对象中使用该包：

const driver = window.driver.js.driver;

const driverObj = driver();

driverObj.highlight({
  element: "#some-element",
  popover: {
    title: "Title",
    description: "Description"
  }
});

以下是一个创建具有多个步骤的导览的简单示例。

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

const driverObj = driver({
  showProgress: true,
  steps: [
    { element: '#tour-example', popover: { title: 'Animated Tour Example', description: 'Here is the code example showing animated tour. Let\'s walk you through it.', side: "left", align: 'start' }},
    { element: 'code .line:nth-child(1)', popover: { title: 'Import the Library', description: 'It works the same in vanilla JavaScript as well as frameworks.', side: "bottom", align: 'start' }},
    { element: 'code .line:nth-child(2)', popover: { title: 'Importing CSS', description: 'Import the CSS which gives you the default styling for popover and overlay.', side: "bottom", align: 'start' }},
    { element: 'code .line:nth-child(4) span:nth-child(7)', popover: { title: 'Create Driver', description: 'Simply call the driver function to create a driver.js instance', side: "left", align: 'start' }},
    { element: 'code .line:nth-child(18)', popover: { title: 'Start Tour', description: 'Call the drive method to start the tour and your tour will be started.', side: "top", align: 'start' }},
    { element: 'a[href="/docs/configuration"]', popover: { title: 'More Configuration', description: 'Look at this page for all the configuration options you can pass.', side: "right", align: 'start' }},
    { popover: { title: 'Happy Coding', description: 'And that is all, go ahead and start adding tours to your applications.' } }
  ]
});

driverObj.drive();

三、配置

1、实例属性Driver配置
Driver.js旨在具有高度可配置性。您可以全局配置driver，也可以按步骤配置。您还可以在driver运行时实时配置它。

const driver = new Driver({
  // 要高亮显示的步骤
  steps?: DriveStep[];
  // 是否开启动画，default: true
  animate?: boolean;
  // 遮罩层背景颜色
  overlayColor?: string;
  // 是否平滑滚动到高亮显示的元素，default: false
  smoothScroll?: boolean;
  // 点击遮罩层是否关闭，default: true
  allowClose?: boolean;
  // 遮罩层不透明度（0表示仅弹出且不覆盖），default: 0.5
  overlayOpacity?: number;
  // 边距，default: 10
  stagePadding?: number;
  // 高亮显示的元素圆角，default: 5
  stageRadius?: number;
  // 是否允许键盘导航，default: true
  allowKeyboardControl?: boolean;
  // 是否禁用与高亮显示的元素的交互，default: false
  disableActiveInteraction?: boolean;
  // 如果您想将自定义类添加到popover
  popoverClass?: string;
  // popover和高亮显示的元素之间的距离，default: 10
  popoverOffset?: number;
  // 在弹出窗口中显示的按钮。对于导览，默认为["next", "previous", "close"]，对于单元素高亮显示，默认为[]。
  showButtons?: AllowedButtons[];
  // 是否禁用按钮
  disableButtons?: AllowedButtons[];

  // 是否显示弹窗进度，default: false
  showProgress?: boolean;
  // 弹窗进度文字
  // {{current}}: 当前步骤数
  //  - {{total}}: 步骤总数
  progressText?: string;
  // 此步骤的下一个按钮文本
  nextBtnText?: string;
  // 此步骤的上一个按钮文本
  prevBtnText?: string;
  // 最后一个按钮上的文本
  doneBtnText?: string;

  // 在呈现popover之后调用。PopoverDOM是一个引用PopoverDOM元素的对象，如按钮标题、描述、正文、容器等。
  onPopoverRender?: (popover: PopoverDOM, 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;;
  onDeselected?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;;

  //导览元素driver前后的钩子被摧毁。每个钩子接收以下参数：
  //-element：当前活动的元素
  //-step：为当前活动的配置的步骤对象
  //-options.config：当前配置选项
  //-options.state：驱动程序的当前状态
  onDestroyStarted?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;;
  onDestroyed?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;;
   // 当点击下一步时调用
  onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;;
  // 当点击上一步时调用
  onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;;
  // 当点击关闭时调用
  onCloseClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void;;
});

注意：通过覆盖onNextClick和onPrevClick钩子，您可以控制driver的导航。这意味着用户将无法使用按钮进行导航，您将不得不调用driverObj.moveNext()或driverObj.movePrevious()来导航到下一个/上一个步骤。

您可以使用此功能来实现自定义逻辑以在步骤之间导航。当您处理动态内容并希望根据某些逻辑高亮显示下一个/上一个元素时，这也很有用。

onNextClick和onPrevClick钩子也可以在步骤级别进行配置。在driver级别进行配置时，您控制所有步骤的导航。在步骤级别进行配置时，您只控制特定步骤的导航。

2、弹出框popver配置

弹出框是Driver.js的主要UI元素。它是突出显示目标元素并显示步骤内容的元素。您可以全局配置弹出框，也可以按步骤配置。以下是一些可用的配置选项。

type Popover = {
//弹出窗口中显示的标题和说明。您可以在其中使用HTML。此外，您可以。省略其中一个，只显示另一个。
  title?: string;
  description?: string;

  // popover相对于目标元素的位置和对齐方式。
  side?: "top" | "right" | "bottom" | "left";
  align?: "start" | "center" | "end";

  // 在popver不显示控制按钮
  showButtons?: ("next" | "previous" | "close")[];
  // 禁用popver的按钮
  disableButtons?: ("next" | "previous" | "close")[];
  // 此步骤的下一个按钮文本
  nextBtnText?: string;
  // 此步骤的上一个按钮文本
  prevBtnText?: string;
  // 此步骤的关闭按钮的文本
  doneBtnText?: string;

  // 同Driver配置
  progressText?: string;
  popoverClass?: string;
  onPopoverRender?: (popover: PopoverDOM, options: { config: Config; state: State }) => void;

  onNextClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
  onPrevClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
  onCloseClick?: (element?: Element, step: DriveStep, options: { config: Config; state: State }) => void
}

3、steps步骤配置
步骤配置是传递给highlight方法或drive方法的steps数组的配置对象。您可以为每个步骤配置弹出框和目标元素。以下是一些可用的配置选项。

type DriveStep = {
  // 要高亮显示的目标元素。
  //这可以是DOM元素，也可以是CSS选择器。
  //如果这是一个选择器，则第一个匹配元素将高亮显示。
  element: Element | string;

  // 此步骤的popover配置。
  popover?: Popover;

  // 当取消选择当前步骤时回调，
  //即将被高亮显示或高亮显示。
  //每个回调都会接收以下参数：
  //-element：步骤的当前DOM元素
  //-step：为步骤配置的步骤对象
  //-options.config：当前配置选项
  //-options.state：驱动程序的当前状态
  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;
}

四、Driver API

以下是初始化driver后，driver提供的方法列表。

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

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

// --------------------------------------------------
// driverObj is an object with the following methods
// --------------------------------------------------

// 从第几步开始导览
driverObj.drive();  
driverObj.drive(4); 
// 移动到步骤列表中的下一步
driverObj.moveNext(); 
// 移动到步骤列表中的上一步
driverObj.movePrevious(); 
// 跳到到步骤列表中的第几步
driverObj.moveTo(4); 
// 检查是否有下一步要进行
driverObj.hasNextStep(); 
// 检查是否有上一步要移动
driverObj.hasPreviousStep()
// 当前步骤是不是第一步
driverObj.isFirstStep(); 
// 当前步骤是不是最后一步
driverObj.isLastStep();
// 获取当前激活的步骤的index
driverObj.getActiveIndex(); 
// 获取当前激活的步骤
driverObj.getActiveStep(); 
// 获取当前步骤的前一步
driverObj.getPreviousStep(); 
// 获取当前激活的HTML元素
driverObj.getActiveElement(); 
// 获取当前激活步骤的上一步HTML元素
driverObj.getPreviousElement(); 

// 导览或高亮是否处于激活状态
driverObj.isActive();

// 刷新
driverObj.refresh();

// 查看配置部分获取配置选项
driverObj.getConfig();
// 设置配置选项
driverObj.setConfig({ /* ... */ });
// 设置步骤内容
driverObj.setSteps([ /* ... */ ]); // Set the steps

// 通过调用`getState`方法来访问driver的当前状态
driverObj.getState();

// 有关步骤的格式，请参阅配置的DriveStep部分
driverObj.highlight({ /* ... */ }); // Highlight an element
// 销毁导览
driverObj.destroy(); 

五、总结

文档地址：https://driverjs.cn。

当然，除了以上介绍的driver.js的安装、基本使用、配置和API外，driver.js还有主题定制、动态导览、静态导览、弹出框定制等实例，可以参考文档学习。

Driver.js是一个功能强大、易于使用的库，可以帮助开发者在Web应用中添加用户引导和提示。通过动态引导层、自定义样式和动画效果等功能，Driver.js能够提升用户体验并帮助用户更好地了解和使用应用。如果你正在开发一个复杂的Web应用并需要添加用户引导和提示功能，那么Driver.js将是一个不错的选择。