更新记录

1.0.0（2025-08-14） 下载此版本

操作引导组件

平台兼容性

uni-app(4.51)

hz-novice-guidance 引导组件

一个操作引导组件，支持vue2和vue3，组件灵活，配置丰富。

功能概述

• ✅通过配置自定义步骤
• ✅支持配置到子组件、孙组件
• ✅支持自定义箭头
• ✅支持自定义功能按钮

配置项

组件参数

baseConfig 配置项

steps 配置项

组件事件

组件方法

插槽

使用示例

这里介绍了一些基本使用，更详细的使用可下载示例项目查看。

基本使用

<template>
  <view class="demo-step guide-step1" style="background: #000;"></view>
  <view class="demo-step guide-step2" style="background: #ff5500;"></view>
  <view class="demo-step guide-step3" style="background: #1a6840;"></view>
  <hz-novice-guidance ref="refNoviceGuidance" :steps="steps" @finished="finished" @next="handleNext" @skiped="skiped"></hz-novice-guidance>

</template>

// js
const refNoviceGuidance = ref()
const steps = [
  {
    el:'.guide-step1',
    tips:'新手引导组件，使用 vue3 + ts 开发，这里是组件说明',
  },
  {
    el:'.guide-step2',
    tips:`内容由 <span style='color:#ff5500;'>rich-text</span> 组件渲染，所以支持简单的HTML标签`,
  },
  {
    el:'.guide-step3',
    next:'朕知道了，下一个',
    nextStyle:{
      background:'#ff5500'
    },
    skip:'朕会了，跳过',
    skipStyle:{
      color:'#ff5500'
    },
    tips:'自定义按钮样式及文字',
  },
]

const finished = ()=>{
  console.log('引导结束')
}

const handleNext = (stepIndex)=>{
  console.log('点击下一步', stepIndex)
}

const skiped = ()=>{
  console.log('点击跳过')
}

onMounted(() => {
  // 小程序需添加 setTimeout 
  setTimeout(() => {
    refNoviceGuidance.value.start()
  }, 0)
})

// css
.demo-step {
  width: 100%; 
  height: 100px; 
  margin-bottom: 20px;
}

配置到子组件

// 页面组件（vue3开发的支付宝小程序，组件需加上额外参数 hz-ref-name，且值和 ref 值一致）
<father ref="refFather" hz-ref-name="refFather"></father>

// father组件
<template>
  <view class="father-container ">
    <view>我是父组件</view>
    <child ref="refChild" hz-ref-name="refChild">
    </child>
  </view>
</template>

// child组件
<template>
  <view class="child-container">
    <view>
      我是子组件
    </view>
    <grandson ref="refGrandson" hz-ref-name="refGrandson"></grandson>
  </view>
</template>

// grandson组件
<template>
  <view class="grandson-container">
    我是孙组件
  </view>
</template>

// js
const steps = [
  {
    // 孙组件中元素类名
    el: '.grandson-container',
    tips: '孙组件，el 值为孙组件中的类名',
    // 传数组，值为每层组件的 ref 名称
    context: ['refFather', 'refChild', 'refGrandson'],
  },
  {
    // 子组件中元素类名
    el: '.child-container',
    tips: '子组件',
    // 传函数，返回子组件实例
    context: ['refFather', 'refChild']
  },
]

支付宝小程序兼容性问题

如果是vue3开发的支付宝小程序，则需在相关子组件上加上额外参数hz-ref-name，值和 ref 的一致，否则支付宝小程序不生效。

自定义提示框内容、样式

<hz-novice-guidance ref="refNoviceGuidance1" :baseConfig="baseConfig" :steps="steps">
  <template #tips="{scope}">
    <view class="custom-tips">
      我是自定义的插槽内容。<br/>
      这是配置的原内容：<rich-text :nodes="scope.currentEle.tips"></rich-text><br/>
      <text style="color: red;">注意：通过 baseConfig 传给组件的 tipStyle 样式任然生效。</text>
    </view>
  </template>
</hz-novice-guidance>

// js
// 整体配置
const baseConfig = {
  highligthStyle:{
    // 配置高亮框背景颜色
    '--bgcolor': 'rgba(0, 0, 0, 0.8)',
  },
  // 提示内容样式
  tipStyle:{
    background: '#fecc11',
    color:'#1a6840',
  },
  // 箭头样式
  arrowStyle:{
    color: '#fecc11',
  }
}

const steps = [
  {
    el:'.guide-step6',
    tips:`步骤传入 tipStyle 参数将覆盖 baseConfig 中的值`,
    tipStyle:{
      background: '#1a6840',
      color:'#fff'
    },
    arrowStyle:{
      color: '#1a6840',
    },
  },
  {
    el:'.guide-step4',
    tips:`通过插槽 <span style='color:#ff5500;'>slot='tips'</span> 可完全自定义内容`,
  },
]

自定义箭头样式

<hz-novice-guidance ref="refNoviceGuidance" :baseConfig="baseConfig" :steps="steps" >
  <template #arrow>
    <view class="custom-arrow">
      <view class="arrow"></view>
      <view class="arrow-line"></view>
      <view class="arrow-head"></view>
    </view>
  </template>
</hz-novice-guidance>

// js
// 整体配置
const baseConfig = {
  // 箭头样式
  arrowStyle:{
    color: '#fecc11',
    width:36,
    height:24,
  }
}

const steps = [
  {
    el:'.guide-step13',
    tips:`步骤参数中的 arrowStyle 会覆盖组件的 baseConfig 中的值`,
    arrowStyle:{
      color: '#ff5500',
      width:12,
      height:8,
    }
  },
  {
    el:'.guide-step5',
    tips:`使用箭头插槽`,
    customArrow:true
  },
  {
    el:'.guide-step6',
    tips:`不自动旋转箭头`,
    autoRotateArrow:false,
    customArrow:true
  },
]

自定义按钮样式

1. 修改文字、样式

   
   <hz-novice-guidance ref="refNoviceGuidance" :baseConfig="baseConfig" :steps="steps" ></hz-novice-guidance>

// js // 整体配置 const baseConfig = { next:'next', nextStyle:{ background: '#ff5500', }, skip:'skip', skipStyle:{ color: '#ff5500', }, } const steps = [ { el:'.guide-step1', tips:'通过参数或插槽控制按钮样式', showSkip:false, }, { el:'.guide-step3', tips:可通过参数，控制按钮的文字、样式, next:'done' }, ]

2. 按钮展示在外部
```js
<hz-novice-guidance ref="refNoviceGuidance" :baseConfig="baseConfig" :steps="steps" ></hz-novice-guidance>

// js
// 整体配置
const baseConfig = {
  outerBtn: true,
}
const steps = [
  {
    el:'.guide-step4',
    tips:`按钮可显示在提示框外部`,
  },
]

3. 使用插槽自定义按钮

   
   <hz-novice-guidance ref="refNoviceGuidance" :baseConfig="baseConfig" :steps="steps" >
   <template #btns="{scope}">
   <view class="custom-btns-outertips">
     <view class="skip-btn" @click="customSkip" v-if="scope.currentStep < steps3.length - 1">跳过</view>
     <view class="next-btn" @click="customNext">{{scope.currentStep < steps3.length - 1 ? '下一步' : '完成'}}</view>
   </view>
   </template>
   </hz-novice-guidance>

// js // 整体配置 const baseConfig = { outerBtn: true, } const steps = [ { el:'.guide-step5', tips:通过插槽 <span style='color:#ff5500;'>slot='btns'</span> 可完全自定义按钮, }, { el:'.guide-step15', tips:通过调用组件的 next、skip、finished 方法控制引导流程, }, ]

const customNext = () => { refNoviceGuidance.value.next() } const customSkip = () => { refNoviceGuidance.value.skip() }

## 常见问题
1. 目前只测试过h5、微信小程序、支付宝小程序，其他平台大家可自行测试。
2. el 值应是唯一的，最好使用class选择器（如 `.guide-step1`）。
3. 该组件暂不适用于高度过大的元素，可能会导致提示框显示不全。

## 兼容性问题
1. 如果是`vue3`开发的`支付宝小程序`，且需配置到子组件时，则需在相关所有子组件上加上额外参数`hz-ref-name`，值和 ref 的一致，否则支付宝小程序不生效。
```js
// 页面组件（vue3开发的支付宝小程序，组件需加上额外参数 hz-ref-name，且值和 ref 值一致）
<father ref="refFather" hz-ref-name="refFather"></father>
// father组件
<template>
  <view class="father-container ">
    <view>我是父组件</view>
    <child ref="refChild" hz-ref-name="refChild">
    </child>
  </view>
</template>

const steps = [
  {
    el: '.child-container',
    tips: '子组件',
    context: ['refFather', 'refChild']
  },
]

2. 使用vue3开发并编译到支付宝小程序时，如果使用插槽且使用了插槽传值，会导致其他插槽的默认内容无法显示。该问题官方暂未修复。

   
   // 这种写法在 vue3 并编译到支付宝小程序，会导致提示内容不展示
   <hz-novice-guidance>
   <template #btns="{scope}"></template>
   </hz-novice-guidance>

// 这种写法正常显示