vue-tour 新功能导航指引插件的使用及实现原理

指引效果.gif

大家好我是多肉攻城狮，大家一定见到过这样一种场景，当网站内容更新时，会通过一个指引操作引导用户熟悉更新的内容，如何实现这样的场景呢？这一篇文章我们来分享一个vue的新功能步骤指引插件vue-tour，并来看看其主要功能点的实现方式。

使用方法

安装及引用

# 安装
yarn add vue-tour
复制代码

// 在入口文件main.js中引用
import VueTour from "vue-tour";
require("vue-tour/dist/vue-tour.css");

Vue.use(VueTour);
复制代码

使用

页面中创建需要被指引的UI，例如下面demo中的这是DOM-1、这是DOM-2、这是DOM-3。
使用v-tour组件进行功能指引的显示，v-tour组件接收两个参数，steps和options，steps用于定义指引步骤项，options用于定义指引的相关配置。关于两个参数的配置说明见下方demo示例中的注释说明。
使用this.$tours["myTour"].start();语句进行指引的开始显示。

<template>
  <div class="wrap">
    <div class="item" id="v-step-0">
      这是DOM-1
    </div>
    <div class="item v-step-1">
      这是DOM-2
    </div>
    <div class="item" data-v-step="2">
      这是DOM-3
    </div>
    <v-tour name="myTour" :steps="steps" :options="myOptions"></v-tour>
  </div>
</template>
<script>
export default {
  name: "my-tour",
  data() {
    return {
      myOptions: {
        useKeyboardNavigation: false, // 是否通过键盘的←, → 和 ESC 控制指引
        labels: { // 指引项的按钮文案
          buttonSkip: "跳过指引", // 跳过文案
          buttonPrevious: "上一步", // 上一步文案
          buttonNext: "下一步", // 下一步文案
          buttonStop: "结束" // 结束文案
        },
        highlight: false // 是否高亮显示激活的的target项
      },
      steps: [
        {
          target: "#v-step-0", // 当前项的id或class或data-v-step属性
          content: "这是DOM-1", // 当前项指引内容
          params: {
            placement: "bottom", // 指引在target的位置，支持上、下、左、右
            highlight: false, // 当前项激活时是否高亮显示
            enableScrolling: false // 指引到当前项时是否滚动轴滚动到改项位置
          },
          // 在进行下一步时处理UI渲染或异步操作，例如打开弹窗，调用api等。当执行reject时，指引不会执行下一步
          before: type => new Promise((resolve, reject) => {
            // 耗时的UI渲染或异步操作
            resolve('foo')
          })
        },
        {
          target: ".v-step-1",
          content: "这是DOM-2",
          params: {
            placement: "bottom"
          }
        },
        {
          target: '[data-v-step="2"]',
          content: "这是DOM-3",
          params: {
            placement: "bottom"
          }
        }
      ]
    };
  },
  mounted: function() {
    this.$tours["myTour"].start();
  }
};
</script>
<style scoped>
.wrap {
  display: flex;
  padding: 20px;
}
.item {
  width: 400px;
  height: 200px;
  line-height: 200px;
  border: 2px solid #cecece;
}
</style>

复制代码

自定义激活样式

可以通过重定义.v-tour__target--highlightedclass的样式控制当前指引dom元素的样式。

.v-tour__target--highlighted {
  box-shadow: 0 0 0 99999px rgba(0,0,0,.4);
}
复制代码

自定义指引项样式

可通过在v-tour组件添加header, content and actions slot进行头部、内容和按钮操作区域的自定义。下面的代码以自定义按钮操作区域为例。

<v-tour name="myTour" :steps="steps">
  <template slot-scope="tour">
    <transition name="fade">
      <v-step
        v-if="tour.steps[tour.currentStep]"
        :key="tour.currentStep"
        :step="tour.steps[tour.currentStep]"
        :previous-step="tour.previousStep"
        :next-step="tour.nextStep"
        :stop="tour.stop"
        :skip="tour.skip"
        :is-first="tour.isFirst"
        :is-last="tour.isLast"
        :labels="tour.labels"
      >
        <template v-if="tour.currentStep === 2">
          <div slot="actions">
            <button @click="tour.previousStep" class="btn btn-primary">Previous step</button>
            <button @click="tour.nextStep" class="btn btn-primary">Next step</button>
          </div>
        </template>
      </v-step>
    </transition>
  </template>
</v-tour>
复制代码

回调函数

v-tour组件支持指引过程中操作后触发回调函数，需在v-tour中添加callbacks，参数值为对象，对象中可设置5中类型的方法，如下代码所示。

<v-tour :callbacks="myCallbacks">
复制代码

data: () => ({
  myCallbacks: {
    onStart: this.onStart, // 开始时触发
    onPreviousStep: this.onPreviousStep, // 上一步时触发
    onNextStep: this.onNextStep, // 下一步时触发
    onSkip: this.onSkip, // 跳过时触发
    onFinish: this.onFinish // 结束时触发
  }
})
复制代码

实现方式

下面，我们来看一下v-tour插件是如何实现新功能指引的。在新功能步骤指引的过程中，主要需要实现两个功能点。

在指引时，tooltip需定位到目标dom进行展示。
当目标dom在滚动轴隐藏区域时，需将目标dom滚动到可视区域。

vue-tour的实现比较轻量，以上两个功能都是通过插件来实现的。

`@popperjs/core`（目标dom定位显示tooltip）

vue-tour使用了@popperjs/core用于当指引到某目标dom时，在该dom元素的某个位置显示tooltip，我们来看一下使用方式。

安装

yarn add @popperjs/core
复制代码

使用

直接上demo。

<template>
  <div>
    <div id="target"></div>
    <div id="tooltip">
      这里是指引信息
    </div>
  </div>
</template>
<script>
import { createPopper } from "@popperjs/core";
export default {
  mounted() {
    const target = document.querySelector("#target");
    const tooltip = document.querySelector("#tooltip");
    createPopper(target, tooltip, {
      placement: "right",
      modifiers: [
        {
          name: "offset",
          options: {
            offset: [0, 8]
          }
        }
      ]
    });
  }
};
</script>
<style>
#target {
  width: 400px;
  height: 200px;
  background: #eee;
}
#tooltip {
  background: #333;
  color: white;
  font-weight: bold;
  padding: 4px 8px;
  font-size: 13px;
  border-radius: 4px;
}
</style>
复制代码

在上面的示例代码中，我们引用了@popperjs/core插件的createPopper方法，该方法接收三个参数，其说明如下：

/**
   * @param {dom} target 目标dom元素
   * @param {dom} popper 指引UI dom元素
   * @param {object} 配置信息对象
   */
createPopper(target, popper, {
  placement: "bottom", // 指引UI位置信息（'auto','auto-start','auto-end','top','top-start','top-end','bottom','bottom-start','bottom-end','right','right-start','right-end','left','left-start','left-end'）
  strategy: "absolute", // 指引UIpositon，支持absolute和fixed
  modifiers: [] // 自定义修饰符，详情参考官网
});
复制代码

`jump.js`（目标dom滚动到可视区域）

vue-tour使用了jump.js用于当目标dom在滚动轴隐藏区域时，需将目标dom滚动到可视区域，我们来看一下使用方式。github.com/callmecavs/…

安装

yarn add jump.js
复制代码

使用

直接上demo。

  <div>
    <div class="item item1">1</div>
    <div class="item item2">2</div>
    <div class="item item3">3</div>
    <div class="item item4">4</div>
    <div class="item item5">5</div>
    <div class="item item6">6</div>
  </div>
</template>
<script>
import jump from "jump.js";
export default {
  mounted() {
    jump(".item4");
  }
};
</script>
<style>
.item {
  width: 400px;
  height: 200px;
  line-height: 200px;
  font-size: 20px;
  font-weight: 600;
  text-align: center;
}
.item1,
.item3,
.item5 {
  background: #d4fd86;
}
.item2,
.item4,
.item6 {
  background: #fa9c71;
}
</style>
复制代码

在上面的实例中，我们定义了一个列表，并在mounted声明周期中，执行了jump方法。并在jump方法中传递了我们希望滚动到的目标dom元素的class，可以看到，当刷新页面时，页面滚动到了.item4所在的div区域。当然jump函数还支持传入其它配置参数，如下所示。

jump('.target', {
  duration: 1000, // 滚动时间
  offset: 0, // 滚动位置的偏移量，默认为0，即滚动到目标元素的最顶部
  callback: undefined, // 滚动完成后的回调函数
  easing: easeInOutQuad, // 重定义缓动函数
  a11y: false
})
复制代码

好啦，vue-tour就先介绍到这里了。欢迎小伙伴关注多肉攻城狮，持续分享前端技术~

往期精彩回顾