新手引导 intro.js 的使用

1 依赖引入

npm install --save intro.js

2 intro.js的使用

以 vue3 为例

<template>
  <div id="step1">...</div>
  <div id="step2">...</div>
  <div id="step3">...</div>
</template>

<script setup>
import { onBeforeUnmount, onMounted } from 'vue'
// 引入intro.js相关依赖
import introJs from 'intro.js'
import 'intro.js/introjs.css'

const intro = introJs() // 申明引导

onMounted(() => {
  // 注册引导
  intro.setOptions({
    nextLabel: '下一步',
    prevLabel: '上一步',
    doneLabel: '完成',
    steps: [
      {
        element: document.querySelector('#step1'),
        intro: "这是第一步的描述",
        position: 'bottom'
      },
      {
        element: document.querySelector('#step2'),
        intro: "这是第二步的描述",
        position: 'bottom'
      },
      {
        element: document.querySelector('#step3'),
        intro: "这是第二步的描述",
        position: 'left'
      }
    ]
  })
  intro.start() // 开启引导
})

onBeforeUnmount(() => {
  intro?.exit() // 销毁监听
})
</script>

3 再次唤起引导

引导关闭后发现无法通过 intro.start() 方法再次唤起，因此需要销毁重建。

function openIntro() { // 打开引导方法，可绑定在 "新手引导" 按钮上重复触发
  intro.onExit(() => { // 引导关闭钩子，每次关闭都重新创建引导
    setTimeout(() => { // 手动异步
      intro?.exit() // 销毁
      intro = introJs() // 重构
    }, 10)
  })
  // 注册引导
  intro.setOptions({
    nextLabel: '下一步',
    prevLabel: '上一步',
    doneLabel: '完成',
    steps: [
      {
        element: document.querySelector('#step1'),
        intro: "这是第一步的描述",
        position: 'bottom'
      },
      {
        element: document.querySelector('#step2'),
        intro: "这是第二步的描述",
        position: 'bottom'
      },
      {
        element: document.querySelector('#step3'),
        intro: "这是第二步的描述",
        position: 'left'
      }
    ]
  })
  intro.start() // 开启引导
}

4 集成为公共组件使用

4.1 在 Vue3 作为 hook 使用

import { ref, onBeforeUnmount } from 'vue'
import introJs from 'intro.js'
import 'intro.js/introjs.css'

export function useIntro() {
  const intro = ref(introJs())

  function openIntroWithOptions(options = { steps: [] }) {
      intro.value.onExit(() => { // 每次关闭都重新创建引导器
        setTimeout(() => {
          intro.value?.exit() // 销毁
          intro.value = introJs() // 重构
        }, 10)
      })
      // 注册引导器
      intro.value.setOptions({
        nextLabel: '下一步',
        prevLabel: '上一步',
        doneLabel: '完成',
        ...options
      })
      intro.value.start()
  }

  onBeforeUnmount(() => {
    intro.value?.exit()
  })

  return {
    intro,
    openIntroWithOptions
  }
}

/** 
 * 在页面中使用示例：
 * 1. 引入 useIntro
 * 2. 声明方法
 * 3. 编写引导打开方法
 * 3.1 其中至少配置 steps，由于element要实时获取，所以必须在页面中的方法里实时配置
 * 3.2 如果是页面加载完立即启动引导，可直接在 onMounted 中执行 openIntro 方法内容 */
// import { useIntro } from '@/hooks/intro' // 1.引入
// const { openIntroWithOptions } = useIntro() // 2.声明 
// function openIntro() { // 3.引导打开方法
//   openIntroWithOptions({ // 配置引导options
//     steps: [
//       {
//         element: document.querySelector('#step1'),
//         intro: "这里是待办事项总览",
//         position: 'bottom'
//       },
//       {
//         element: document.querySelector('#step2'),
//         intro: "点击可查看此类目待办事项",
//         position: 'bottom'
//       },
//       {
//         element: document.querySelector('#step3'),
//         intro: "这是待办事项列表",
//         position: 'top'
//       },
//       {
//         element: document.querySelector('#step4'),
//         intro: "点击可前往处理",
//         position: 'left'
//       }
//     ]
//   })
// }

4.2 在 Vue2 作为 mixin 使用

// 引导器mixins
import introJs from 'intro.js'
import 'intro.js/introjs.css'

let intro = introJs()

export default {
  beforeDestroy() {
    intro?.exit() // 销毁监听
  },
  methods: {
    openIntroWithOptions(options = { steps: [] }) { // 打开引导
      intro.onExit(() => { // 每次关闭都重新创建引导器
        setTimeout(() => {
          intro?.exit() // 销毁
          intro = introJs() // 重构
        }, 10)
      })
      // 注册引导器
      intro.setOptions({
        nextLabel: '下一步',
        prevLabel: '上一步',
        doneLabel: '完成',
        ...options
      })
      intro.start()
    }
  }
}

/** 
 * 在页面中使用示例：
 * 1. 引入
 * 2. 申明mixins
 * 3. 在 methods 中写入以下方法
 * 3.1 其中至少配置 steps，由于element要实时获取，所以必须在页面中的方法里实时配置
 * 3.2 如果是页面加载完立即启动引导，可直接在 mounted 中执行 openIntro 方法内容 */
// import intro from '@/mixins/intro' // 1. 引入
// mixins: [intro] // 2. 申明
// openIntro() { // 3. 调用方法
//   this.openIntroWithOptions({ // 配置引导options
//     steps: [
//       {
//         element: document.querySelector('#step1'),
//         intro: "这里是待办事项总览",
//         position: 'bottom'
//       },
//       {
//         element: document.querySelector('#step2'),
//         intro: "点击可查看此类目待办事项",
//         position: 'bottom'
//       },
//       {
//         element: document.querySelector('#step3'),
//         intro: "这是待办事项列表",
//         position: 'top'
//       },
//       {
//         element: document.querySelector('#step4'),
//         intro: "点击可前往处理",
//         position: 'left'
//       }
//     ]
//   })
// }

笔记主要为自用，欢迎友好交流！