使用 Vue Tour 封装一个统一的页面引导组件

项目开发过程中需要实现用户引导功能，经过调研发现一个好用的 Vue 插件 vue-tour，今天就来分享一下我是如何基于 vue-tour 封装一个统一的引导组件，方便后续在多个页面复用的。

---

第一步：安装 vue-tour 插件

首先安装：

npm install vue-tour

然后在项目的 main.js 中进行全局注册：

import Vue from 'vue'
import VueTour from 'vue-tour'
import 'vue-tour/dist/vue-tour.css'

Vue.use(VueTour)

---

第二步：封装统一引导组件

我们希望做到的效果是：不管哪个页面需要引导，只需要引入这个组件，传入 name 和 steps，然后调用 start() 方法即可开启引导。

于是我们封装了一个组件 v-tour-comp.vue，完整代码如下：

<template>
  <div>
    <div v-if="showMask" class="mask">div>
    <v-tour :name="name" :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 #content>
              <slot :tour="tour">slot>
            template>
            <template #actions>
              <slot name="action" :tour="tour">slot>
            template>
          v-step>
        transition>
      template>
    v-tour>
  div>
template>

<script>
export default {
  name: 'v-tour-comp',
  props: {
    name: String,
    steps: Array
  },
  data() {
    return {
      showMask: false
    }
  },
  created() {
    this.setStepsBefore()
  },
  methods: {
    setStepsBefore() {
      // 引导前判断每一步的目标元素是否存在，保证渲染的位置是正确的
      this.steps.forEach((item) => {
        item.before = () =>
          new Promise((resolve, reject) => {
            const el = document.querySelector(item.target)
            if (!el) {
              reject(new Error('找不到元素'))
              return
            }
            resolve()
          })
      })
    },
    start() {
      this.showMask = true
      this.$tours[this.name]?.start()
    },
    stop() {
      this.showMask = false
      this.$tours[this.name]?.stop()
    },
    previousStep() {
      this.$tours[this.name]?.previousStep()
    },
    nextStep() {
      this.$tours[this.name]?.nextStep()
    }
  }
}
script>

<style scoped lang="scss">
.mask {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: 9999;
  background-color: transparent;
}
style>

✅ 核心逻辑说明：

• 我们通过 setStepsBefore 方法，确保每一步引导的目标 DOM 元素在页面上是存在的；
• 对外暴露 start()、stop() 等方法，方便外部调用控制；
• 使用插槽 提供自定义内容和操作按钮的能力；
• 加一个 mask 遮罩层可以让用户更聚焦当前引导区域（当然你可以自定义背景色等样式）。

---

第三步：在页面中使用

在你需要引导的页面中，只需要这样用：

结语

通过封装这个组件，我们可以在项目中非常方便地添加用户引导，只需要：

1. 传入 steps；
2. 引用组件；
3. 调用 start()。

对于提升用户上手效率、降低学习成本、增强产品友好性来说，这样的小工具非常值得一试。如果你也有类似的需求，欢迎试试这个方案～

GitHub 项目地址：vue-tour

---

如果你觉得这篇文章对你有帮助，欢迎点赞收藏，也欢迎留言交流更多引导类功能的实现方式

---