当前位置：首页 > article >正文

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

article 2025/9/17 17:03:44

项目开发过程中需要实现用户引导功能，经过调研发现一个好用的 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-stepv-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 = truethis.$tours[this.name]?.start()},stop() {this.showMask = falsethis.$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>