Tour 漫游式引导 ​

用于分步引导用户了解产品功能的气泡组件。

ts
import { createApp } from 'vue'
import { Tour as ElTour, TourStep as ElTourStep } from '@szhn/dh-design-pc'

const app = createApp()
app.use(ElTour)
app.use(ElTourStep)

基础用法 ​

最简单的用法，通过 steps 属性描述每一步的目标与内容。

<template>
  <div>
    <el-button @click="open = true">开始引导</el-button>
    <div style="margin-top: 12px; display: flex; gap: 8px;">
      <el-button ref="ref1">Upload</el-button>
      <el-button ref="ref2" type="primary">Save</el-button>
      <el-button ref="ref3">
        <el-icon><more-filled /></el-icon>
      </el-button>
    </div>

    <el-tour v-model="open">
      <el-tour-step
        :target="() => ref1?.$el"
        title="Upload File"
        description="Put you files here."
      />
      <el-tour-step
        :target="() => ref2?.$el"
        title="Save"
        description="Save your changes."
      />
      <el-tour-step
        :target="() => ref3?.$el"
        title="Other Actions"
        description="Click to see other actions."
      />
    </el-tour>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Tour as ElTour, TourStep as ElTourStep, Button as ElButton, Icon as ElIcon } from '@szhn/dh-design-pc'
import { MoreFilled } from '@szhn/dh-design-pc/icons'


const open = ref(false)
const ref1 = ref()
const ref2 = ref()
const ref3 = ref()
</script>

使用 TourStep 组件 ​

也可以使用 el-tour-step 以插槽方式声明步骤，便于自定义内容。

<template>
  <div>
    <el-button ref="ref1" @click="open = true">开始引导</el-button>
    <el-button ref="ref2" style="margin-left: 12px">操作按钮</el-button>

    <el-tour v-model="open">
      <el-tour-step :target="() => ref1?.$el" title="第一步" description="这是第一步的介绍。" />
      <el-tour-step :target="() => ref2?.$el" title="第二步" description="这是第二步的介绍。" />
    </el-tour>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Tour as ElTour, TourStep as ElTourStep, Button as ElButton } from '@szhn/dh-design-pc'


const open = ref(false)
const ref1 = ref<any>(null)
const ref2 = ref<any>(null)
</script>

非模态 ​

设置 :mask="false" 可以将引导变为非模态，建议与 type="primary" 组合使用以强调引导。

<template>
  <div>
    <el-button ref="btn" type="primary" @click="open = true">开始引导</el-button>
    <el-tour v-model="open" :mask="false" type="primary">
      <el-tour-step :target="() => btn?.$el" title="非模态引导" description="没有遮罩，用户仍可与页面交互。" />
    </el-tour>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Tour as ElTour, TourStep as ElTourStep, Button as ElButton } from '@szhn/dh-design-pc'


const open = ref(false)
const btn = ref<any>(null)
</script>

位置 ​

通过 placement 属性改变引导相对于目标的位置，共有 12 种位置可选。

<template>
  <div>
    <el-button ref="btn" @click="open = true">开始引导（右侧）</el-button>
    <el-tour v-model="open">
      <el-tour-step
        :target="() => btn?.$el"
        placement="right"
        title="右侧位置"
        description="通过 placement 调整引导卡片位置。"
      />
    </el-tour>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Tour as ElTour, TourStep as ElTourStep, Button as ElButton } from '@szhn/dh-design-pc'


const open = ref(false)
const btn = ref<any>(null)
</script>

主题类型 ​

通过 type="primary" 切换引导主题风格。

<template>
  <div>
    <el-button ref="btn" type="primary" @click="open = true">开始 Primary 引导</el-button>
    <el-tour v-model="open" type="primary">
      <el-tour-step
        :target="() => btn?.$el"
        title="Primary 主题"
        description="使用主色调突出引导内容。"
      />
    </el-tour>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Tour as ElTour, TourStep as ElTourStep, Button as ElButton } from '@szhn/dh-design-pc'


const open = ref(false)
const btn = ref<any>(null)
</script>

自定义遮罩样式 ​

通过 mask 传入对象，可自定义遮罩颜色、样式以及与目标元素之间的间距。

<template>
  <div>
    <el-button ref="ref1" @click="open = true">开始引导</el-button>

    <el-tour
      v-model="open"
      :mask="{ color: 'rgba(130, 90, 220, 0.6)' }"
    >
      <el-tour-step
        :target="() => ref1?.$el"
        title="自定义遮罩颜色"
        description="通过 mask.color 或 style 配置遮罩的视觉样式。"
      />
    </el-tour>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Tour as ElTour, TourStep as ElTourStep, Button as ElButton } from '@szhn/dh-design-pc'


const open = ref(false)
const ref1 = ref<InstanceType<typeof ElButton>>()
</script>

自定义指示器 ​

使用 indicators 插槽可以完全自定义底部的步骤指示器。

<template>
  <div>
    <el-button ref="ref1" @click="open = true">开始引导（自定义指示器）</el-button>

    <el-tour v-model="open">
      <template #indicators="{ current, total }">
        <span class="dh-tour-indicator">{{ current + 1 }} / {{ total }}</span>
      </template>
      <el-tour-step
        :target="() => ref1?.$el"
        title="第一步"
        description="右下角指示器展示 X/Y 步数。"
      />
      <el-tour-step
        :target="() => ref1?.$el"
        title="第二步"
        description="你可以完全自定义指示器 UI。"
      />
    </el-tour>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Tour as ElTour, TourStep as ElTourStep, Button as ElButton } from '@szhn/dh-design-pc'


const open = ref(false)
const ref1 = ref<InstanceType<typeof ElButton>>()
</script>

<style scoped>
.dh-tour-indicator {
  font-size: 12px;
  color: var(--el-text-color-regular);
  padding: 2px 8px;
  border-radius: 10px;
  background: var(--el-fill-color-light);
}
</style>

目标 ​

target 支持 string（选择器）、HTMLElement、() => HTMLElement 以及空值（居中展示）。

<template>
  <div>
    <el-button id="tour-target-demo" class="mr-2" @click="open = true">
      字符串 target
    </el-button>
    <el-button ref="fnRef" @click="open2 = true">函数 target</el-button>
    <el-button class="ml-2" @click="open3 = true">空 target（居中）</el-button>

    <el-tour v-model="open">
      <el-tour-step
        target="#tour-target-demo"
        title="字符串选择器"
        description="target 传入字符串时，按 document.querySelector 解析。"
      />
    </el-tour>

    <el-tour v-model="open2">
      <el-tour-step
        :target="() => fnRef?.$el"
        title="函数 target"
        description="target 支持函数，返回 HTMLElement。"
      />
    </el-tour>

    <el-tour v-model="open3">
      <el-tour-step
        title="空 target"
        description="未指定 target 时，引导卡片居中显示。"
      />
    </el-tour>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Tour as ElTour, TourStep as ElTourStep, Button as ElButton } from '@szhn/dh-design-pc'


const open = ref(false)
const open2 = ref(false)
const open3 = ref(false)
const fnRef = ref<InstanceType<typeof ElButton>>()
</script>

API ​

Tour Attributes ​

属性说明类型默认值
model-value / v-model是否打开引导booleanfalse
current / v-model:current当前步骤number0
mask是否启用遮罩，也可传入 { color, style } 自定义boolean | objecttrue
type主题类型'default' | 'primary'default
placement卡片相对于目标的位置enum（12 种）bottom
content-stylecontent 自定义样式CSSProperties—
show-arrow是否显示箭头booleantrue
show-close是否显示关闭按钮booleantrue
close-icon自定义关闭图标string | Component—
close-on-press-escape是否可以通过 ESC 关闭booleantrue
target-area-clickable启用蒙层时 target 区域是否可点击booleantrue
gap遮罩与目标之间的透明间距TourGap{ offset: 6, radius: 2 }
append-to挂载到的 DOM 元素CSSSelector | HTMLElementbody
scroll-into-view-options滚动到视窗的参数boolean | ScrollIntoViewOptions{}
z-indexTour 的层级number2001

Tour Events ​

事件名说明参数
close关闭引导时的回调(current: number) => void
finish完成引导时的回调() => void
change步骤切换时的回调(current: number) => void

Tour Slots ​

插槽名说明作用域
defaultTourStep 组件列表—
indicators自定义指示器{ current, total }

TourStep Attributes ​

属性说明类型默认值
target目标元素string | HTMLElement | () => HTMLElement—
title步骤标题string—
description步骤描述string—
placement卡片位置enumbottom
content-stylecontent 自定义样式CSSProperties—
mask是否启用蒙层（可覆盖 Tour 的 mask）boolean | object—
type主题类型'default' | 'primary'—
show-arrow是否显示箭头boolean—
show-close是否显示关闭按钮boolean—
close-icon自定义关闭图标string | Component—
next-button-props"下一步" 按钮属性object—
prev-button-props"上一步" 按钮属性object—
scroll-into-view-options滚动参数（跟随 Tour）boolean | ScrollIntoViewOptions—

TourStep Slots ​

插槽名说明
default自定义描述内容
header自定义 header 内容

TourStep Events ​

事件名说明参数
close关闭引导时的回调() => void

更多内容见 Element Plus Tour 文档。