Driver.js中文网

# 简介及使用教程

Driver.js是一个功能强大且高度可定制的基于原生JavaScript开发的新用户引导库。它没有依赖项，支持所有主要浏览器。

# 安装

npm i driver.js
// 或者
yarn add driver.js

或者CDN引入方式

<script src="https://unpkg.com/driver.js/dist/driver.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/driver.js/dist/driver.min.css">
<!-- 或者 -->
<link rel="stylesheet" href="/dist/driver.min.css">
<script src="/dist/driver.min.js"></script>
<!-- 或者 -->
<link href="https://cdn.bootcdn.net/ajax/libs/driver.js/0.9.8/driver.min.css" rel="stylesheet">
<script src="https://cdn.bootcdn.net/ajax/libs/driver.js/0.9.8/driver.min.js"></script>

特点：

简单：简单易用，完全没有外部依赖

高度可定制：有一个强大的api，可以用于你希望突出显示任何内容

高亮显示：页面功能介绍上的任意元素(字面上的任意)

功能介绍：为你的web应用程序创建强大的功能介绍

焦点移位器：为用户友好添加焦点移位器

用户友好：通过键盘行为控制一切

一致行为：所有浏览器(包括著名的IE)都可以使用

MIT声明：免费用于个人和商业用途。

# 它是怎么实现的?

非常简单，它在整个页面顶部绘制了一个canvas蒙层，然后切掉要高亮显示的元素上方的部分实现高亮显示或不高亮显示，在显示高亮或关闭高亮显示时还提供了几个钩子，使其高度可定制。

# 能举一些例子吗?

下面是关于如何使用它的一些示例和示例用例。

# 高亮显示单个元素-不带弹出窗

如果您只想突出显示单个元素，您可以通过传入节点选择器非常简单地做到这一点。

const driver = new Driver();
driver.highlight('#create-post');

还有一个常见的使用场景，就是在用于与某个元素交互时高亮显示该元素。

const focusDriver = new Driver();

// Highlight the section on focus
document.getElementById('creation-input')
  .addEventListener('focus', (e) => {
    focusDriver.highlight('#creation-input');
  });

使聚焦元素高亮显示，可以查看下面例子，使用Tab键进行焦点切换可以查看它如何动画在两个元素之间切换高亮显示。你也可以关闭动画，或者设置高亮与元素之间的间距，下面会有详细介绍。

# 高亮显示单个元素 - 带弹出窗

如果你想在突出显示的元素旁边显示一些详细信息，可以通过设置指定标题与描述轻松实现。

const driver = new Driver();
driver.highlight({
  element: '#some-element',
  popover: {
      title: 'Popover标题',
      description: '这里是描述',
  }
});

还可以通过配置一些特定选项来定制弹出窗口的行为，下面将详细介绍。

弹出窗的位置设置

您还可以将弹出窗口的位置更改为左、左中、左下、上、上中、右上、右、右中、右下或下、下中、右下方、中间。

const driver = new Driver();
driver.highlight({
  element: '#some-element',
  popover: {
    title: 'Title for the Popover',
    description: 'Description for it',
    // 位置可以设置为 
    //  左：left, 左中：left-center, 左下：left-bottom,
    //  上：top,上中：top-center, 上右：top-right, 
    //  右：right, 右中：right-center, 右下right-bottom,
    //  下：bottom, 下中：bottom-center, 下右：bottom-right, 中：mid-center
    position: 'left',
  }
});

如果您没有设置置顶位置或将position设置为auto,它将自动为弹出窗口找到合适的显示位置。

# 弹窗中使用HTML

您可以在弹窗的标题与内容部分使用HTML代码。

例如：

const driver = new Driver();
driver.highlight({
  element: '#some-element',
  popover: {
    title: '<em>An italicized title</em>',
    description: 'Description may also contain <strong>HTML</strong>'
  }
});

禁止点击阴影关闭

driver.js 默认是点击阴影会关闭高亮，您可以禁用这个行为。

例如：

const driver = new Driver({
    allowClose: false,
});

driver.highlight({
  element: '#some-element',
  popover: {
    title: '<em>An italicized title</em>',
    description: 'Description may also contain <strong>HTML</strong>'
  }
});

如果你在多个步骤使用了这个禁用选项，它将在步骤完成或者关闭它的时候进行关闭。如果是对单个节点弹窗，您需要使用下面方法进行关闭。

driver.reset()

const driver = new Driver();
// Define the steps for introduction
driver.defineSteps([
  {
    element: '#first-element-introduction',
    popover: {
      className: 'first-step-popover-class',
      title: 'Title on Popover',
      description: 'Body of the popover',
      position: 'left'
    }
  },
  {
    element: '#second-element-introduction',
    popover: {
      title: 'Title on Popover',
      description: 'Body of the popover',
      position: 'top'
    }
  },
  {
    element: '#third-element-introduction',
    popover: {
      title: 'Title on Popover',
      description: 'Body of the popover',
      position: 'right'
    }
  },
]);
// Start the introduction
driver.start();

这只是多步骤功能介绍的一个简单示例。要了解更多信息，请查看 “快速游览”

您还可以关闭弹出窗口中的页脚按钮，在这种情况下，用户可以使用键盘上的箭头键控制弹出窗口。或者您可以使用驱动程序提供的方法来控制它。

# 无遮罩

您可以创建在没有阴影覆盖的情况下实现上面所有操作，只要将不透明度设置为 ‘0’即可。

const driver = new Driver({
    opacity: 0,
});

driver.highlight({
  element: '#run-element-without-popover',
  popover: {
    title: 'Title for the Popover',
    description: 'Description for it',
    position: 'top', // can be `top`, `left`, `right`, `bottom`
  }
});

..并且您可以对功能介绍进行同样的操作

# ..还有更多

驱动程序提供了许多选项，您可以操纵这些选项以使驱动程序的行为符合您的意愿

# 驱动程序定义

以下是driver需要了解的选项

const driver = new Driver({
  className: 'scoped-class', // className to wrap driver.js popover 弹窗的额外样式名
  animate: true,  // Animate while changing highlighted element 是否在切换时使用动画
  opacity: 0.75,  // Background opacity (0 means only popovers and without overlay) 覆盖阴影透明度
  padding: 10,    // Distance of element from around the edges 高亮与高亮节点的间距大小
  allowClose: true, // Whether clicking on overlay should close or not 是否允许点击覆盖阴影关闭 默认允许
  overlayClickNext: false, // Should it move to next step on overlay click 是否点击覆盖阴影时下一步
  doneBtnText: 'Done', // Text on the final button 完成按钮的文字
  closeBtnText: 'Close', // Text on the close button for this step 关闭按钮的文字
  nextBtnText: 'Next', // Next button text for this step 下一步按钮的文字
  prevBtnText: 'Previous', // Previous button text for this step 上一步按钮文字
  showButtons: false, // Do not show control buttons in footer 是否在底部显示按钮
  keyboardControl: true, // Allow controlling through keyboard (escape to close, arrow keys to move) 是否允许键盘控制 （ESC 关闭， 方向键 控制进度）
  scrollIntoViewOptions: {}, // We use `scrollIntoView()` when possible, pass here the options for it if you want any
  onHighlightStarted: (Element) {}, // Called when element is about to be highlighted 当节点高亮开始时触发回调
  onHighlighted: (Element) {}, // Called when element is fully highlighted 当节点已经高亮时触发回调
  onDeselected: (Element) {}, // Called when element has been deselected 当节点关闭高亮触发回调
  onReset: (Element) {},        // Called when overlay is about to be cleared 当点击因应关闭时触发回调
  onNext: (Element) => {},      // Called when moving to next step on any step 下一步时触发回调
  onPrevious: (Element) => {},  // Called when moving to next step on any step 上一步触发回调
});

注意：所有的按钮选项文字配置都可以在步骤数组配置中进行覆盖。

# 步骤定义

以下是您可以在每个步骤中传递的一组选项，即步骤数组中的项目或传递给高亮显示方法的对象

const stepDefinition = {
  element: '#some-item',        // Query selector string or Node to be highlighted 高亮节点选择器
  popover: {                    // There will be no popover if empty or not given 弹窗选项
    className: 'popover-class', // className to wrap this specific step popover in addition to the general className in Driver options 弹窗额外class名
    title: 'Title',             // Title on the popover 标题
    description: 'Description', // Body of the popover 内容
    showButtons: false,         // Do not show control buttons in footer 是否显示按钮
    closeBtnText: 'Close',      // Text on the close button for this step 关闭按钮文字
    nextBtnText: 'Next',        // Next button text for this step 下一步按钮文字
    prevBtnText: 'Previous',    // Previous button text for this step 上一步按钮文字
  }
};

# API 方法

以下是您可以使用的API方法

const driver = new Driver(driverOptions);

const isActivated = driver.isActivated; // Checks if the driver is active or not 检测高亮状态
driver.moveNext();     // Moves to next step in the steps list 下一步
driver.movePrevious(); // Moves to previous step in the steps list 上一步
driver.start(stepNumber = 0);  // Starts driving through the defined steps 开始步骤
driver.highlight(string|stepDefinition); // highlights the element using query selector or the step definition 使用节点选择器进行高亮
driver.reset(); // Resets the overlay and clears the screen 关闭
driver.hasHighlightedElement(); // Checks if there is any highlighted element 检测是否已经高亮过
driver.hasNextStep(); // Checks if there is next step to move to 检测是否有下一步
driver.hasPreviousStep(); // Checks if there is previous step to move to 检测而是否有上一步

// Prevents the current move. Useful in `onNext` or `onPrevious` if you want to
// 可以在‘OnNext’或者‘onPrevious’中阻止步骤移动
// perform some asynchronous task and manually move to next step
// 可以在方法中执行一些异步方法然后手动转到下一步
driver.preventMove();

// Gets the currently highlighted element on screen
// 获取当前屏幕上高亮的节点
const activeElement = driver.getHighlightedElement();
const lastActiveElement = driver.getLastHighlightedElement();
activeElement.getCalculatedPosition(); // Gets screen co-ordinates of the active element 获取高亮节点的屏幕坐标
activeElement.hidePopover();  // Hide the popover 隐藏弹窗
activeElement.showPopover();  // Show the popover 显示弹窗

activeElement.getNode();  // Gets the DOM Element behind this element 获取高亮元素后面的元素节点

您可以使用各种选项来实现您可能想要的任何目标。我有一些进一步改进的计划，可以关注GitHub项目

# 贡献

您可以在GitHub页面上找到投稿说明。随时提交问题、创建拉取请求或传播消息

Kamran的一款产品是在他放弃寻找完美的解决方案来整合旅程介绍和叠加后，出于厌倦和沮丧而制作的。