wot-design-uni/docs/component/tour.md

Guide 漫游组件

用于引导用户逐步了解应用功能的组件，可以高亮显示页面中的特定元素并提供说明。

基本使用

通过 steps 属性设置引导步骤，通过 v-model 控制显示隐藏。

<template>
  <view>
    <view class="tour-item" id="step1">
      <text class="tour-title">第一步</text>
      <text class="tour-content">这是引导的第一步，介绍基本功能</text>
    </view>
    
    <view class="tour-item" id="step2">
      <text class="tour-title">第二步</text>
      <text class="tour-content">这是引导的第二步，展示更多功能</text>
    </view>
    
    <wd-tour 
      :model-value="showTour" 
      :steps="steps" 
      v-model:current="current"
      @finish="onFinish"
    />
  </view>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const showTour = ref(true)
const current = ref(0)

const steps = [
  {
    element: '#step1',
    content: '这是第一步的说明'
  },
  {
    element: '#step2',
    content: '这是第二步的说明'
  }
]

function onFinish() {
  console.log('引导完成')
}
</script>

自定义引导内容

通过 content 插槽可以自定义引导内容。

<wd-tour :model-value="showTour" :steps="steps">
  <template #content>
    <view class="custom-content">
      <wd-icon name="help-circle-filled" size="22px"></wd-icon>
      <text class="custom-text">自定义引导内容区域</text>
    </view>
  </template>
</wd-tour>

自定义高亮区域

通过 highlight 插槽可以自定义高亮区域样式。

<wd-tour :model-value="showTour" :steps="steps">
  <template #highlight="{ elementInfo }">
    <view class="custom-highlight" :style="getCustomHighlightStyle(elementInfo)"></view>
  </template>
</wd-tour>

自定义按钮

通过 prev、next、skip、finish 插槽可以自定义按钮。

<wd-tour :model-value="showTour" :steps="steps" next-text="继续" finish-text="知道了">
  <template #next>
    <view class="custom-button custom-next">下一步</view>
  </template>
  <template #finish>
    <view class="custom-button custom-finish">完成</view>
  </template>
</wd-tour>

点击蒙版继续

通过 click-mask-next 属性可以设置点击蒙版是否可以下一步。

<wd-tour 
  :model-value="showTour" 
  :steps="steps" 
  :click-mask-next="true"
/>

自定义蒙版样式

通过 mask-color、offset、border-radius、padding 属性可以自定义蒙版样式。

<wd-tour 
  :model-value="showTour" 
  :steps="steps" 
  mask-color="rgba(255, 0, 0, 0.6)"
  :offset="40"
  :border-radius="15"
  :padding="20"
/>

关闭蒙版

通过 mask 属性可以控制是否显示蒙版。

<wd-tour 
  :model-value="showTour" 
  :steps="steps" 
  :mask="false"
/>

控制当前步骤

通过 v-model:current 可以控制当前步骤。

<view>
  <wd-button @click="current = 2">跳转到第三步</wd-button>
  <wd-tour 
    :model-value="showTour" 
    :steps="steps" 
    v-model:current="current"
  />
</view>

Attributes

参数	说明	类型	可选值	默认值
v-model	是否显示引导组件	boolean	-	false
steps	引导步骤列表	array	-	[]
current	当前步骤索引，支持 v-model:current 双向绑定	number	-	0
mask	蒙版是否显示	boolean	-	true
mask-color	蒙版颜色（支持 rgba 格式）	string	-	rgba(0, 0, 0, 0.5)
offset	引导提示框与高亮框的间距	number	-	20
duration	动画持续时间（毫秒）	number	-	300
border-radius	高亮区域的圆角大小	number	-	8
padding	高亮区域的内边距	number	-	10
prev-text	上一步按钮文字	string	-	上一步
next-text	下一步按钮文字	string	-	下一步
skip-text	跳过按钮文字	string	-	跳过
finish-text	完成按钮文字	string	-	完成
bottom-safety-offset	底部安全偏移量，用于滚动计算时确保元素周围有足够的空间	number	-	100
top-safety-offset	顶部安全偏移量，用于滚动计算时确保元素周围有足够的空间	number	-	0
custom-nav	是否自定义顶部导航栏	boolean	-	false
click-mask-next	点击蒙版是否可以下一步	boolean	-	false
z-index	引导组件的层级	number	-	999998
show-tour-buttons	是否显示引导按钮	boolean	-	true

Steps 数据结构

属性	说明	类型
element	需要高亮的元素选择器	string
content	引导文字内容（支持富文本）	string

Events

事件名	说明	参数
change	步骤改变时触发	{currentIndex: number }
prev	点击上一步按钮时触发	{ oldCurrent: number, current: number, total: number, isUp: number }
next	点击下一步按钮时触发	{ oldCurrent: number, current: number, total: number, isUp: number }
finish	点击完成按钮时触发	{ current: number, total: number }
skip	点击跳过按钮时触发	{ current: number, total: number }
error	查找引导元素出错时触发	{ message: string, element: string }

Slots

插槽名	说明	参数
highlight	自定义高亮区域	elementInfo: 元素位置信息
content	自定义引导内容	-
prev	自定义上一步按钮	-
next	自定义下一步按钮	-
skip	自定义跳过按钮	-
finish	自定义完成按钮	-

Methods

通过 ref 可以获取到组件实例，调用组件提供的方法：

方法名	说明	参数
handlePrev	切换到上一步	-
handleNext	切换到下一步	-
handleSkip	跳过引导	-
handleFinish	完成引导	-

注意事项

1. 确保要高亮的元素在页面中存在且可选择
2. 在自定义导航栏的情况下，需要设置 custom-nav 和适当的 top-safety-offset 值
3. 引导组件会自动处理滚动，确保高亮元素在可视区域内
4. 可以通过 mask 属性控制是否显示遮罩层
5. 使用自定义高亮区域时，注意避免遮挡引导操作按钮
6. 在不同平台（H5、微信小程序等）中，插槽的使用方式可能略有差异
7. 建议在使用时添加 v-if 或 v-show 条件渲染，以确保组件正确初始化

主题定制

组件支持通过 CSS 变量定制主题，可以修改以下变量：

// 蒙版颜色
--wd-tour-mask-color: rgba(0, 0, 0, 0.5);

// 引导框背景色
--wd-tour-popover-bg-color: #ffffff;

// 按钮背景色
--wd-tour-button-primary-bg-color: #007aff;

// 按钮文字颜色
--wd-tour-button-color: #ffffff;

常见问题

为什么在微信小程序中自定义插槽不显示？

在微信小程序中使用条件渲染与插槽结合时可能会出现问题，建议使用 v-show 替代 v-if 或将条件判断移到插槽内部。

为什么高亮区域会闪烁？

这通常是因为组件初始化时元素信息尚未获取完成导致的。组件已优化初始状态，避免闪烁问题。

如何解决点击问题？

如果自定义高亮区域遮挡了操作按钮，可以调整 z-index 或修改自定义高亮区域的样式，确保按钮可点击。