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

news2025/5/18 18:21:41

项目开发过程中需要实现用户引导功能，经过调研发现一个好用的 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() 等方法，方便外部调用控制；
使用插槽 <slot> 提供自定义内容和操作按钮的能力；
加一个 mask 遮罩层可以让用户更聚焦当前引导区域（当然你可以自定义背景色等样式）。

📌 第三步：在页面中使用

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

<template>
  <div>
    <div class="step-1">我是第一步</div>
    <div class="step-2">我是第二步</div>

    <v-tour-comp ref="tour" :name="'guide-demo'" :steps="tourSteps">
      <template #content="{ tour }">
        <div>{{ tour.steps[tour.currentStep].content }}</div>
      </template>
      <template #action="{ tour }">
        <button @click="tour.previousStep" v-if="!tour.isFirst">上一步</button>
        <button @click="tour.nextStep" v-if="!tour.isLast">下一步</button>
        <button @click="tour.stop">结束</button>
      </template>
    </v-tour-comp>
  </div>
</template>

<script>
import VTourComp from '@/components/v-tour-comp.vue'

export default {
  components: { VTourComp },
  data() {
    return {
      tourSteps: [
        {
          target: '.step-1',
          content: '这是第一步，介绍页面某个功能'
        },
        {
          target: '.step-2',
          content: '这是第二步，继续讲解另一个部分'
        }
      ]
    }
  },
  mounted() {
    // 页面加载后自动触发引导
    this.$nextTick(() => {
      this.$refs.tour.start()
    })
  }
}
</script>