Tour 新手引导

用于引导用户了解产品功能的导览组件。支持高亮目标元素、遮罩镂空、多步骤导航、键盘操作等功能。

基础用法

通过 v-model 控制引导的显示和隐藏，steps 配置引导步骤。每个步骤通过 target 指定高亮元素（支持 CSS 选择器、HTMLElement 或函数）。

<script setup>
import { ref } from 'vue'

const open = ref(false)

const steps = [
  {
    title: '开始引导',
    description: '欢迎使用 ZC UI！点击「下一步」继续。',
    target: '#tour-demo-btn-1',
  },
  {
    title: '功能介绍',
    description: '这是一个按钮组件，支持多种类型和尺寸。',
    target: '#tour-demo-btn-2',
  },
  {
    title: '更多功能',
    description: '探索更多组件和功能吧！',
    target: '#tour-demo-btn-3',
  },
]
</script>

<template>
  <ZcSpace>
    <ZcButton id="tour-demo-btn-1" type="primary" @click="open = true">
      开始引导
    </ZcButton>
    <ZcButton id="tour-demo-btn-2">功能按钮</ZcButton>
    <ZcButton id="tour-demo-btn-3" type="success">更多功能</ZcButton>
    <ZcTour v-model="open" :steps="steps" />
  </ZcSpace>
</template>

弹出位置

支持 12 个方向的弹出位置：top / top-start / top-end / bottom / bottom-start / bottom-end / left / left-start / left-end / right / right-start / right-end。

可以在组件级别统一设置 placement，也可以在每个 step 中单独覆盖。

<script setup>
import { ref } from 'vue'

const open = ref(false)

const steps = [
  {
    title: '右侧弹出',
    description: '引导面板从目标的右侧弹出。',
    target: '#tour-placement-demo',
    placement: 'right',
  },
]
</script>

<template>
  <div>
    <ZcButton id="tour-placement-demo" type="primary" @click="open = true">
      右侧弹出
    </ZcButton>
    <ZcTour v-model="open" :steps="steps" />
  </div>
</template>

自定义指示器

通过 indicator 属性选择内置指示器类型，或通过 indicator 插槽完全自定义。

• default：页码（如 1/3）
• dot：圆点指示器
• none：不显示指示器

<script setup>
import { ref } from 'vue'

const open = ref(false)

const steps = [
  { title: '步骤一', description: '使用圆点指示器。', target: '#tour-dot-demo' },
  { title: '步骤二', description: '当前进度一目了然。', target: '#tour-dot-demo' },
  { title: '步骤三', description: '完成引导！', target: '#tour-dot-demo' },
]
</script>

<template>
  <div>
    <ZcButton id="tour-dot-demo" type="primary" @click="open = true">
      圆点指示器
    </ZcButton>
    <ZcTour v-model="open" :steps="steps" indicator="dot" />
  </div>
</template>

键盘导航

开启 keyboard 属性后支持键盘操作：

• ESC：关闭引导
• → / ↓：下一步
• ← / ↑：上一步

<script setup>
import { ref } from 'vue'

const open = ref(false)

const steps = [
  { title: '键盘操作', description: '尝试使用方向键切换步骤，ESC 关闭引导。', target: '#tour-keyboard-demo' },
]
</script>

<template>
  <div>
    <ZcButton id="tour-keyboard-demo" type="primary" @click="open = true">
      开启键盘导航
    </ZcButton>
    <ZcTour v-model="open" :steps="steps" :keyboard="true" />
  </div>
</template>

自定义按钮文案

通过属性或插槽自定义按钮文案。

<script setup>
import { ref } from 'vue'

const open = ref(false)

const steps = [
  { title: '自定义文案', description: '每个按钮的文案都可以自定义。', target: '#tour-text-demo' },
  { title: '第二步', description: '继续探索。', target: '#tour-text-demo' },
]
</script>

<template>
  <div>
    <ZcButton id="tour-text-demo" type="primary" @click="open = true">
      自定义文案
    </ZcButton>
    <ZcTour
      v-model="open"
      :steps="steps"
      prev-text="后退"
      next-text="前进"
      finish-text="结束"
      skip-text="退出"
    />
  </div>
</template>

自定义内容

通过插槽自定义标题、描述和操作区域的渲染。

<script setup>
import { ref } from 'vue'

const open = ref(false)

const steps = [
  { title: '自定义内容', description: '通过插槽完全自定义面板内容。', target: '#tour-slot-demo' },
]
</script>

<template>
  <div>
    <ZcButton id="tour-slot-demo" type="primary" @click="open = true">
      自定义内容
    </ZcButton>
    <ZcTour v-model="open" :steps="steps">
      <template #title="{ current }">
        <span style="color: var(--color-zc-primary-500)">✦ 自定义标题 #{{ current + 1 }}</span>
      </template>
      <template #actions="{ next, prev, isFirst, isLast }">
        <ZcButton size="small" :disabled="isFirst" @click="prev()">Prev</ZcButton>
        <ZcButton size="small" type="primary" @click="next()">
          {{ isLast ? 'Done' : 'Next' }}
        </ZcButton>
      </template>
    </ZcTour>
  </div>
</template>

Tour API

Tour Props

参数	说明	类型	默认值
modelValue / v-model	是否显示引导	boolean	false
open / v-model:open	是否显示引导（别名）	boolean	false
steps	引导步骤配置	TourStep[]	[]
current / v-model:current	当前步骤索引	number	0
placement	默认弹出位置	TourPlacement	'bottom'
arrow	是否显示箭头	boolean	true
showMask	是否显示遮罩	boolean	true
closeOnOverlayClick	点击遮罩是否关闭	boolean	true
keyboard	是否启用键盘导航	boolean	true
gap	高亮区域内边距 (px)	number	6
offset	面板与目标的间距 (px)	number	12
maskColor	遮罩颜色	string	'rgba(0,0,0,0.5)'
zIndex	层级	number	—
indicator	指示器类型	'default' | 'dot' | 'none'	'default'
scrollIntoViewOptions	滚动到目标的选项	ScrollIntoViewOptions	{ behavior: 'smooth', block: 'center' }
showPrevButton	是否显示上一步按钮	boolean	true
showSkipButton	是否显示跳过按钮	boolean	true
prevButtonText	上一步按钮文案	string	'上一步'
nextButtonText	下一步按钮文案	string	'下一步'
finishButtonText	完成按钮文案	string	'完成'
skipButtonText	跳过按钮文案	string	'跳过'

TourStep

参数	说明	类型	默认值
title	步骤标题	string	—
description	步骤描述	string	—
target	目标元素	string | HTMLElement | (() => HTMLElement)	—
placement	覆盖弹出位置	TourPlacement	—
showArrow	覆盖箭头显示	boolean	—
gap	覆盖高亮内边距	number	—
offset	覆盖面板间距	number	—

TourPlacement

'top' | 'top-start' | 'top-end'
'bottom' | 'bottom-start' | 'bottom-end'
'left' | 'left-start' | 'left-end'
'right' | 'right-start' | 'right-end'

Tour Events

事件名	说明	回调参数
update:modelValue	显隐状态变化	(value: boolean)
update:open	显隐状态变化	(value: boolean)
update:current	当前步骤变化	(current: number)
change	步骤切换	(currentStep: number)
close	引导关闭	(currentStep: number)
finish	引导完成（最后一步点击下一步）	()

Tour Slots

插槽名	说明
indicator	自定义步骤指示器
title	自定义标题
description	自定义描述内容
actions	自定义操作按钮
prev-text	上一步按钮文案
next-text	下一步按钮文案
finish-text	完成按钮文案

Tour Methods (exposed)

方法名	说明	参数
open	打开引导	()
close	关闭引导	()
next	下一步	()
prev	上一步	()
goTo	跳转到指定步骤	(index: number)