vue-js-driver

基于driver.js封装的vue2版轻量级新手引导库

✨ 特性

• 🚀 简单轻量
• 💪 高度可定制
• ✋ 阻止用户交互
• ⌨️ 支持键盘控制
• 👏 突出显示任何内容
• 🆓 开源版本支持免费商用
• 🌀 所有主流浏览器表现一致

🎬 在线体验

Live Demo

📦 安装

npm install vue-js-driver
yarn add vue-js-driver
pnpm add vue-js-driver

👉 快速上手

引入

// main.js全局引入 或 HelloWorld.vue组件内引入
import Vue from 'vue';

import vueJsDriver from 'vue-js-driver';
import driverConfig from '@/config/driverConfig.js';

Vue.use(vueJsDriver, driverConfig);

配置Driver

// driverConfig.js
export default {
  className: '', // 包裹Driver弹窗的类名，避免css作用域污染
  allowClose: false, // 是否允许点击遮罩时关闭
  opacity: 0, // 背景透明度，`0` 表示只弹窗无遮罩
  padding: 0, // 元素与边缘的距离
  stageBackground: 'transparent', // 高亮元素的背景颜色
  prevBtnText: '上一步->', // 当前步骤上一步按钮的文本
  nextBtnText: '下一步->', // 当前步骤下一步按钮的文本
  closeBtnText: '关闭x', // 当前步骤关闭按钮的文本
  doneBtnText: '完成√', // 最后一个按钮的文本
  showButtons: false // 是否显示底部的控制按钮
  ...
}

配置步骤

// steps.js
export default {
  homeSteps: [ // 首页步骤
    {
      element: '#welcome', // 高亮的元素，内部通过querySelector获取元素，还可通过DOM的方法获取，例如document.getElementById('welcome')
      popover: {
          title: '这是标题', // 弹窗的标题，为空则不显示，注：支持HTML
          description: '这是描述', // 弹窗的主体内容，注：支持HTML
          position: 'right', // 弹窗显示的位置
      },
      padding: 25 // 弹窗与高亮元素的内边距，会扩大高亮元素的宽/高
      ...
      // 更多配置：https://github.com/kamranahmedse/driver.js/blob/master/src/index.js
    }
  ],
  otherSteps: [], // 其他页面步骤
  ...
}

使用

<!-- HelloWorld.vue -->
<template>
  <div class="hello">
    <h1 id="welcome">{{ msg }}</h1>
    <p class="description">
      For a guide and recipes on how to configure / customize this project,<br>
      check out the
      <a href="https://cli.vuejs.org" target="_blank" rel="noopener">vue-cli documentation</a>.
    </p>
    <h3 @click="showDriver">显示引导Show Demo</h3>
    <h3 @click="highSingleElement">突出单个元素</h3>
    <h3 @click="highSingleElement2">突出单个元素（含配置）</h3>
  </div>
</template>

<script>
import steps from '../steps.js';

export default {
  props: {
    msg: String
  },
  methods: {
    showDriver () {

      // 通过$vueJsDriver来调用，1代表跳转到第二步，不传默认跳转至第一步
      this.$vueJsDriver.showDriver(steps.homeSteps, 1);
    },
    highSingleElement () {
      this.$sfDriverJs.highlight('#welcome');
    },
    highSingleElement2 () {
      this.$sfDriverJs.highlight({
        element: '#welcome',
        popover: {
          title: 'Title for the Popover',
          description: 'Description for it',
          position: 'bottom',
          offset: 20
        }
      });
    }
  },
  ...
}

API

Driver选项

参数	说明	类型/回调参数	可选值	默认值
className	包裹Driver弹窗的类名	string	—	vue-js-driver
animate	是否开启过渡动画	boolean	—	true
opacity	背景透明度，0 表示只弹窗无遮罩	number	0-1	0.75
padding	元素与边缘的距离	number	—	10
allowClose	是否允许点击遮罩时关闭	boolean	—	true
overlayClickNext	是否允许点击遮罩时移动到下一步	boolean	—	false
stageBackground	高亮元素的背景颜色	string	—	#ffffff
doneBtnText	最后一个按钮的文本	string	—	完成
closeBtnText	当前步骤关闭按钮的文本	string	—	关闭
nextBtnText	当前步骤下一步按钮的文本	string	—	下一步
prevBtnText	当前步骤上一步按钮的文本	string	—	上一步
showButtons	是否显示底部的控制按钮	boolean	—	true
keyboardControl	是否允许键盘控制，Esc关闭、操作键（←上一步、→下一步）用于移动	boolean	—	true
scrollIntoViewOptions	scrollIntoView() 方法的选项	object	—	null
onHighlightStarted	元素即将高亮时调用	function(element){}	—	—
onHighlighted	元素完全高亮时调用	function(element){}	—	—
onDeselected	取消选择时调用	function(element){}	—	—
onReset	遮罩将要关闭时调用	function(element){}	—	—
onNext	任何步骤中移动到下一步时调用	function(element){}	—	—
onPrevious	任何步骤中移动到上一步时调用	function(element){}	—	—

Step步骤选项

参数	说明	类型/回调参数	可选值	默认值
element	需高亮的选择器字符或Node，内部通过querySelector获取元素，还可通过DOM的方法获取	string/Node	—	—
stageBackground	高亮元素的背景颜色	string	—	#ffffff
padding	弹窗与高亮元素的内边距，会扩大高亮元素的宽/高	number	—	—
onNext	从当前步骤移动到下一步时调用	function(element){}	—	—
onPrevious	从当前步骤移动到上一步时调用	function(element){}	—	—
popover	弹窗的配置项，具体参考以下选项，注：为空不会显示弹窗	object	—	—
className	除了Driver选项中的通用类名称之外，还可以指定包裹当前指定步骤弹窗的类名	string	—	''
title	弹窗的标题，为空则不显示，注：支持HTML	string	—	—
description	弹窗的主体内容，注：支持HTML	string	—	—
position	弹窗的位置	string	left, left-center, left-bottom, top, top-center, top-right, right, right-center, right-bottom,bottom, bottom-center, bottom-right, mid-center	bottom
offset	弹窗的平移距离，如弹窗在高亮元素下方，offet控制左右位移，margin控制上下	number	可负数	—
margin	弹窗与高亮元素的外边距	number	可负数	—
padding	弹窗与高亮元素的内边距	number	可负数	—
showButtons	是否显示底部的控制按钮	boolean	—	true
doneBtnText	最后一个按钮的文本	string	—	Done
closeBtnText	当前步骤关闭按钮的文本	string	—	Close
nextBtnText	当前步骤下一步按钮的文本	string	—	Next
prevBtnText	当前步骤上一步按钮的文本	string	—	Previous

方法

事件名称	说明	参数
showDriver	启用Driver	(steps, index)steps所有步骤的参数，index开始高亮的索引
isActivated	检查Driver是否激活，注：非事件，为Driver的属性	true激活，false未激活
defineSteps	设置要高亮显示的步骤数据	(steps)高亮步骤的数组
start	启用引导	(stepNumber)开始高亮的位置，默认为0
moveNext	移动到步骤列表中的下一步	—
movePrevious	移动到步骤列表中的上一步	—
hasNextStep	检查是否有可移动到的下一步的元素	—
hasPreviousStep	检查是否有可移动到的上一步的元素	—
preventMove	阻止当前移动，如果要执行某些异步任务并手动移动到下一步，则在onNext或onPrevious中很有用	—
highlight	使用查询选择器或步骤定义高亮显示的元素	(string|stepDefinition)查询选择器或步骤数据
refresh	重新定位弹出窗口和突出显示的元素	—
reset	重置遮罩并且清屏	(immediate)立即重置，不要动画，默认为false
hasHighlightedElement	检查是否有高亮元素	—
const activeElement = $vueJsDriver.getHighlightedElement()	获取当前高亮元素	—
activeElement.getCalculatedPosition	获取当前高亮元素的坐标	—
activeElement.hidePopover	隐藏弹窗	—
activeElement.showPopover	显示弹窗	—
activeElement.getNode	获取当前高亮元素后面的DOM元素	—
const lastActiveElement = $vueJsDriver.getLastHighlightedElement()	获取最后一个高亮元素	—

您可以使用各种选项来实现您可能想要的任何选择

🔑 License

MIT