Driver.js 实现用户引导功能

Glory_wzh

已于 2023-11-02 16:28:49 修改

阅读量1.1k

点赞数 3

于 2023-11-02 09:37:38 首次发布

本文链接：https://blog.csdn.net/Glory_wzh/article/details/134154872

版权

本文详细介绍了如何在Vue3项目中使用Driver.js库来创建引导功能，包括安装步骤、引入组件、配置示例和全局配置选项。读者将学习如何设置高亮区域、自定义弹出窗口和导航行为。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

前言

记录使用Driver.js基于Vue3 + TS 实现引导功能。
本文中 Driver.js 使用的版本为 1.3.0，下面附带简单示例及配置项。
当然，也可以自行访问官网 Driver.js 查看示例及配置项。

安装

运行以下命令之一来安装软件包：

# npm
npm install driver.js

# pmpm
pnpm install driver.js

# yarn
yarn insatll driver.js

开始使用

安装后，您可以将包导入到项目中。简单示例如下：

<template>
  <div>
    <div class="block highlight1">高亮区域1</div>
    <div class="block highlight2">高亮区域2</div>
    <br />
    <br />
    <el-button type="primary" @click="handleOpen">打开引导</el-button>
  </div>
</template>

<script setup lang="ts">
import { driver, type DriveStep } from "driver.js";
import "driver.js/dist/driver.css";

const steps: DriveStep[] = [
  {
    element: ".highlight1", // 需要被高亮的元素选择器
    // 弹框内容，如果为空将不会显示弹窗
    popover: {
      title: "提示", // 弹窗的标题
      description: "这是高亮区域1", // 弹窗的主体内容
      side: "bottom", // 弹窗位置
    },
  },
  {
    element: ".highlight2",
    popover: {
      title: "提示",
      description: "这是高亮区域2",
      side: "bottom",
    },
  },
];

const driverObj = driver({
  steps: steps, // 高亮显示的步骤数组
  nextBtnText: "下一步", // 下一步按钮显示文字
  prevBtnText: "上一步", // 上一步按钮显示文字
  doneBtnText: "关闭", // 关闭按钮显示文字
});

const handleOpen = () => {
  driverObj.drive();
};
</script>

<style scoped lang="scss">
.block {
  display: inline-block;
  width: 100px;
  height: 100px;
  background-color: aqua;
  text-align: center;
  line-height: 100px;
  margin-right: 30px;
}
</style>

效果如下：
简单使用

全局配置

可以通过将配置对象传递给 driver 调用或使用 setConfig 方法来全局配置驱动程序。

const driverObj = driver({
  // ... 参考下方配置项
})

或者

const driverObj = driver()
driverObj.setConfig({
  // ... 参考下方配置项
})

可用的配置选项：

type Config  = {
  // 高亮显示的步骤数组。
  steps?: DriveStep[];
  // 是否为产品演示制作动画。(默认值:true)
  animate?: boolean;
  // 引导弹窗背景颜色，支持"#000"、"rgb(0, 0, 0)" 。(默认值:black)
  overlayColor?: string;
  // 是否平滑滚动到高亮显示的元素。(默认值:false)
  smoothScroll?: boolean;
  // 是否允许通过点击背景来关闭弹出窗口。(默认值:true)
  allowClose?: boolean;
  // 背景的透明度。(默认值:0.5)
  overlayOpacity?: number;
  // 突出显示的元素与切口之间的距离。(默认值:10)
  stagePadding?: number;
  // 突出显示的元素周围的切口半径。(默认值:5)
  stageRadius?: number;
  // 是否允许键盘导航。(默认值:true)
  allowKeyboardControl?: boolean;
  // 是否禁用与突出显示的元素的交互。(默认值:false)
  disableActiveInteraction?: boolean;
  // 自定义class类名
  popoverClass?: string;
  // 弹出窗口和突出显示的元素之间的距离。(默认值:10)
  popoverOffset?: number;
  // 要显示在弹出窗口中的按钮数组。默认为["next"， "previous"， "close"]
  showButtons?: AllowedButtons[];
  // 要禁用的按钮数组
  disableButtons?: AllowedButtons[];
  // 是否在弹出窗口中显示进度文本。(默认值:false)
  showProgress?: boolean;
  // 进度文本的模板。{{current}}:当前步长，{{total}}:总步数
  // 如："{{current}} of {{total}}"
  progressText?: string;
  // 下一步按钮显示文字
  nextBtnText?: string;
  // 上一步按钮显示文字
  prevBtnText?: string;
  // 关闭按钮显示文字
  doneBtnText?: string;
  
  // 弹出窗口渲染后调用
  //   - PopoverDOM: 弹出窗口DOM元素
  //   - option.config: 当前配置选项
  //   - option.state: 驱动器的当前状态
  onPopoverRender?: (popover: PopoverDOM, options: { config: Config; state: State }) => void;
  
  // 在突出显示每个步骤之前和之后运行
  //   - element: 该步骤的目标DOM元素
  //   - step: 为step配置的step对象
  //   - options.config: 当前配置选项
  //   - options.state: 驱动器的当前状态
  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;;

  // 驱动程序被销毁前后运行
  //   - element: 当前活动的元素
  //   - step: 为当前活动对象配置的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;;

  // 按钮点击时运行
  //   - element: 当前步骤的DOM元素
  //   - step: 为step配置的step对象
  //   - options.config: 当前配置选项
  //   - options.state: 驱动器的当前状态
  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 钩子，可以控制驱动程序的导航。这意味着将无法使用按钮进行导航，必须调用 driverObj.moveNext() 或 driverObj.movePrevious() 来导航到下一个/上一个步骤。

onNextClick 和 onPrevClick 钩子也可以在步骤级别配置。当在驱动程序级别进行配置时，可以控制所有步骤的导航。在步骤级别进行配置时，只能控制该特定步骤的导航。

弹出框配置

弹出框是 Driver.js 的主要UI元素，它是突出显示目标元素并显示步骤内容的元素。

可用的配置选项：

type Popover = {
  // 弹出框标题
  title?: string;
  // 弹出框描述
  description?: string;
  // 弹出窗口的位置
  side?: "top" | "right" | "bottom" | "left";
  // 弹出窗口的对齐方式
  align?: "start" | "center" | "end";
  // 显示在弹出窗口中的按钮数组
  showButtons?: ("next" | "previous" | "close")[];
  // 要禁用的按钮数组
  disableButtons?: ("next" | "previous" | "close")[];
  // 下一步按钮文本
  nextBtnText?: string;
  // 上一步按钮文本
  prevBtnText?: string;
  // 最后一步按钮文本
  doneBtnText?: string;
  // 是否在弹出窗口中显示进度文本。
  showProgress?: boolean;
  // 进度文本的模板，具体参考全局配置
  progressText?: string;
  // 自定义class类名
  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
}

步骤配置

步骤是传递给 highlight 方法或 drive 方法的 steps 数组的配置对象，可以为每个步骤配置弹出框和目标元素。

可用的配置选项：

type DriveStep = {
  // 需要被高亮的元素选择器
  element: Element | string;
  // 弹窗配置
  popover?: Popover;

  // 取消选择当前步骤时回调
  //   - element: 该步骤的目标DOM元素
  //   - step: 为step配置的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;
}

状态

可以通过调用 getState 方法来获取当前状态。它也被传递给钩子和回调函数。

状态参数：

type State = {
  // 当前是否活动
  isInitialized?: boolean;
  // 当前步骤的索引
  activeIndex?: number;
  // 当前步骤的DOM元素
  activeElement?: Element;
  // 当前步骤的step对象
  activeStep?: DriveStep;
  // 上一步骤的DOM元素
  previousElement?: Element;
  // 上一步骤的step对象
  previousStep?: DriveStep;
  // 弹出窗口的DOM元素
  popover?: PopoverDOM;
}

API参考

Driver 首先要初始化，初始化完成后具有以下方法：

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

// 初始化
const driverObj = driver({
  // ... 配置项
});

driverObj.drive();  // 从头开始
driverObj.drive(4); // 从第 5 步开始，此处传入的为 step 数组的索引

driverObj.moveNext(); // 进入下一步
driverObj.movePrevious(); // 进入上一步
driverObj.moveTo(4); // 进入第 5 步
driverObj.hasNextStep(); // 判断是否有下一步
driverObj.hasPreviousStep() // 判断是否有上一步

driverObj.isFirstStep(); // 判断当前步骤是否是第一步
driverObj.isLastStep(); // 判断当前步骤是否是最后一步

driverObj.getActiveIndex(); // 获取当前步骤索引

driverObj.getActiveStep(); // 获取当前步骤配置
driverObj.getPreviousStep(); // 获取上一步配置
driverObj.getActiveElement(); // 获取当前步骤dom元素
driverObj.getPreviousElement(); // 获取上一步dom元素

// 当前是否高亮
driverObj.isActive();

// 刷新
driverObj.refresh();

// 获取配置项
driverObj.getConfig();
// 初始化配置项
driverObj.setConfig({ /* ... */ });

driverObj.setSteps([ /* ... */ ]); // 设置步骤

// 获取状态
driverObj.getState();

driverObj.highlight({ /* ... */ }); // 高亮元素

自定义样式

可以全局设置 popoverClass 选项定义自定义 class ，或在步骤中设置 popoverClass 自定义 class 。如下面的示例，自定义类名 my-custom-popover-class ，通过给此类名添加样式进行自定义样式。

const driverObj = driver({
  popoverClass: 'my-custom-popover-class'
});

或者

const driverObj = driver({
  steps: [
    {
      element: '#some-element',
      popover: {
        title: 'Title',
        description: 'Description',
        popoverClass: 'my-custom-popover-class'
      }
    }
  ],
})