Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Tour 漫游引导
新功能上线时,一步步高亮页面上的元素并给出说明,带用户熟悉界面。遮罩盖住页面,目标元素处留出高亮区域,旁边的卡片显示标题、说明和上一步、下一步按钮。
引入
import { NsTour } from '@ns/ui'
基础用法
steps 描述每一步:target 是要高亮的元素,title、description 是卡片上的标题和说明。v-model:open 控制显示,v-model:current 是当前第几步(从 0 开始)。
target 可以是 CSS 选择器、元素、组件实例(取它的根元素)、ref,或者返回它们的函数。推荐写成函数 () => buttonRef.value:切到这一步时才去取元素,这时页面早就渲染好了。目标不在可视区域时会先滚过去。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourStep } from '@ns/ui'
const open = ref(false)
const current = ref(0)
const uploadRef = ref()
const saveRef = ref()
const moreRef = ref()
const steps: TourStep[] = [
{
target: () => uploadRef.value,
title: '上传文件',
description: '点这里选择本地文件上传,一次可以选多个。'
},
{
target: () => saveRef.value,
title: '保存',
description: '改完记得保存,保存后其他成员就能看到。'
},
{
target: () => moreRef.value,
title: '更多操作',
description: '导出、分享、删除等不常用的操作都收在这里。'
}
]
const start = () => {
current.value = 0
open.value = true
}
</script>
<template>
<div>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap>
<NsButton type="primary" @click="start">开始引导</NsButton>
<span>open:{{ open }},current:{{ current }}</span>
</NsSpace>
<NsSpace>
<NsButton ref="uploadRef" icon="upload">上传</NsButton>
<NsButton ref="saveRef" icon="save">保存</NsButton>
<NsButton ref="moreRef" icon="more-horizontal" aria-label="更多" />
</NsSpace>
</NsSpace>
<NsTour v-model:open="open" v-model:current="current" :steps="steps" />
</div>
</template>
没有目标
不写 target 的步骤,卡片显示在屏幕中间,遮罩盖住整个页面、不留高亮区域。适合放开场的欢迎语和最后的结束语。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourStep } from '@ns/ui'
const open = ref(false)
const publishRef = ref()
const steps: TourStep[] = [
{
title: '欢迎使用新版编辑器',
description: '花一分钟看看有哪些变化。这一步没写 target,卡片在屏幕中间。'
},
{
target: () => publishRef.value,
title: '发布',
description: '写完点这里发布,发布前会先自动保存。'
},
{
title: '就这些',
description: '以后可以在“帮助”菜单里重新打开这个引导。'
}
]
</script>
<template>
<div>
<NsSpace wrap>
<NsButton @click="open = true">开始引导</NsButton>
<NsButton ref="publishRef" type="primary" icon="upload">发布</NsButton>
</NsSpace>
<NsTour v-model:open="open" :steps="steps" />
</div>
</template>
位置
placement 是卡片相对目标的位置,默认 bottom,共 12 个方向;放不下时自动翻到另一侧。arrow 控制要不要显示指向目标的箭头,默认显示,没有目标时不显示。
这个示例关掉了遮罩,打开后可以直接在选择框里换方向、勾选箭头:
<script setup lang="ts">
import { computed, ref } from 'vue'
import { NsButton, NsCheckbox, NsSelect, NsSpace, NsTour } from '@ns/ui'
import type { PopperPlacement, SelectOption, TourStep } from '@ns/ui'
const placements: PopperPlacement[] = [
'top',
'top-start',
'top-end',
'bottom',
'bottom-start',
'bottom-end',
'left',
'left-start',
'left-end',
'right',
'right-start',
'right-end'
]
const options: SelectOption[] = placements.map((value) => ({ label: value, value }))
const open = ref(false)
const placement = ref<PopperPlacement>('bottom')
const arrow = ref(true)
const targetRef = ref<HTMLElement>()
const steps = computed<TourStep[]>(() => [
{
target: () => targetRef.value,
title: `placement:${placement.value}`,
description: '在上面的选择框里换个方向看看。'
}
])
</script>
<template>
<div>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap>
<NsSelect v-model="placement" :options="options" style="width: 160px" />
<NsCheckbox v-model="arrow">显示箭头(arrow)</NsCheckbox>
<NsButton type="primary" @click="open = true">打开</NsButton>
</NsSpace>
<div class="stage">
<div ref="targetRef" class="target">目标元素</div>
</div>
</NsSpace>
<NsTour
v-model:open="open"
:steps="steps"
:placement="placement"
:arrow="arrow"
:mask="false"
/>
</div>
</template>
<style scoped>
.stage {
display: flex;
justify-content: center;
padding: 160px 0;
}
.target {
padding: var(--ns-spacing-4) var(--ns-spacing-8);
color: var(--ns-text-color-secondary);
border: 1px dashed var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
</style>
遮罩
mask 默认 true,用主题的 --ns-mask-color;false 不显示遮罩;传 { color } 改颜色。
有遮罩时整个页面(包括高亮的目标)都不能点击,焦点限制在卡片里;没有遮罩时页面照常可以操作,目标也不再有高亮区域,只靠卡片的箭头指着。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourMask, TourStep } from '@ns/ui'
const open = ref(false)
const mask = ref<TourMask>(true)
const searchRef = ref()
const filterRef = ref()
const steps: TourStep[] = [
{ target: () => searchRef.value, title: '搜索', description: '按名称、编号搜索。' },
{ target: () => filterRef.value, title: '筛选', description: '按状态、时间等条件筛选。' }
]
const show = (value: TourMask) => {
mask.value = value
open.value = true
}
</script>
<template>
<div>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap>
<NsButton @click="show(true)">默认遮罩(true)</NsButton>
<NsButton @click="show(false)">不显示遮罩(false)</NsButton>
<NsButton @click="show({ color: 'rgba(22, 119, 255, 0.25)' })">蓝色遮罩</NsButton>
<NsButton @click="show({ color: 'rgba(0, 0, 0, 0.75)' })">更深的遮罩</NsButton>
</NsSpace>
<NsSpace>
<NsButton ref="searchRef" icon="search">搜索</NsButton>
<NsButton ref="filterRef" icon="filter">筛选</NsButton>
</NsSpace>
</NsSpace>
<NsTour v-model:open="open" :steps="steps" :mask="mask" />
</div>
</template>
高亮区域
gap 设置高亮区域比目标每边向外扩出的距离 offset 和圆角 radius,单位 px,默认都是 6。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourGap, TourStep } from '@ns/ui'
const open = ref(false)
const gap = ref<TourGap>({})
const cardRef = ref<HTMLElement>()
const steps: TourStep[] = [
{
target: () => cardRef.value,
title: '数据概览',
description: '这里汇总了今天的访问量和订单数。'
}
]
const show = (value: TourGap) => {
gap.value = value
open.value = true
}
</script>
<template>
<div>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap>
<NsButton @click="show({})">默认(offset 6、radius 6)</NsButton>
<NsButton @click="show({ offset: 0, radius: 0 })">贴边直角(offset 0、radius 0)</NsButton>
<NsButton @click="show({ offset: 12, radius: 20 })"
>宽松圆角(offset 12、radius 20)</NsButton
>
</NsSpace>
<div ref="cardRef" class="overview">
<div>
<div class="overview__label">访问量</div>
<div class="overview__value">12,846</div>
</div>
<div>
<div class="overview__label">订单数</div>
<div class="overview__value">326</div>
</div>
</div>
</NsSpace>
<NsTour v-model:open="open" :steps="steps" :gap="gap" />
</div>
</template>
<style scoped>
.overview {
display: flex;
gap: var(--ns-spacing-8);
padding: var(--ns-spacing-4) var(--ns-spacing-6);
background: var(--ns-bg-color-secondary);
border-radius: var(--ns-border-radius);
}
.overview__label {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.overview__value {
font-size: var(--ns-font-size-xl);
font-weight: var(--ns-font-weight-semibold);
}
</style>
类型
type 是卡片外观:default(默认,普通卡片)、primary(主色卡片,白字,按钮换成白色)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourStep, TourType } from '@ns/ui'
const open = ref(false)
const type = ref<TourType>('default')
const shareRef = ref()
const starRef = ref()
const steps: TourStep[] = [
{ target: () => shareRef.value, title: '分享', description: '生成链接发给同事。' },
{ target: () => starRef.value, title: '收藏', description: '收藏后可以在首页快速找到。' }
]
const show = (value: TourType) => {
type.value = value
open.value = true
}
</script>
<template>
<div>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap>
<NsButton @click="show('default')">普通卡片(default)</NsButton>
<NsButton type="primary" @click="show('primary')">主色卡片(primary)</NsButton>
</NsSpace>
<NsSpace>
<NsButton ref="shareRef" icon="share">分享</NsButton>
<NsButton ref="starRef" icon="star">收藏</NsButton>
</NsSpace>
</NsSpace>
<NsTour v-model:open="open" :steps="steps" :type="type" />
</div>
</template>
步骤指示
indicator 是卡片左下角的步骤指示:text(默认,显示“2 / 4”)、dots(圆点,当前步骤高亮)、none(不显示)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourIndicator, TourStep } from '@ns/ui'
const open = ref(false)
const indicator = ref<TourIndicator>('text')
const aRef = ref()
const bRef = ref()
const cRef = ref()
const dRef = ref()
const steps: TourStep[] = [
{ target: () => aRef.value, title: '新建', description: '新建一份文档。' },
{ target: () => bRef.value, title: '编辑', description: '修改文档内容。' },
{ target: () => cRef.value, title: '复制', description: '复制一份副本。' },
{ target: () => dRef.value, title: '删除', description: '删除后可以在回收站找回。' }
]
const show = (value: TourIndicator) => {
indicator.value = value
open.value = true
}
</script>
<template>
<div>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap>
<NsButton @click="show('text')">文字(text)</NsButton>
<NsButton @click="show('dots')">圆点(dots)</NsButton>
<NsButton @click="show('none')">不显示(none)</NsButton>
</NsSpace>
<NsSpace>
<NsButton ref="aRef" icon="plus">新建</NsButton>
<NsButton ref="bRef" icon="edit">编辑</NsButton>
<NsButton ref="cRef" icon="copy">复制</NsButton>
<NsButton ref="dRef" icon="trash" type="danger" plain>删除</NsButton>
</NsSpace>
</NsSpace>
<NsTour v-model:open="open" :steps="steps" :indicator="indicator" />
</div>
</template>
按钮文字
prev-button-text、next-button-text、finish-button-text 分别是“上一步”“下一步”和最后一步“完成”按钮的文字,英文界面用:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourStep } from '@ns/ui'
const open = ref(false)
const inboxRef = ref()
const settingRef = ref()
const steps: TourStep[] = [
{ title: 'Welcome', description: 'Take a quick look at what is new.' },
{ target: () => inboxRef.value, title: 'Inbox', description: 'All your messages are here.' },
{ target: () => settingRef.value, title: 'Settings', description: 'Change your preferences.' }
]
</script>
<template>
<div>
<NsSpace wrap>
<NsButton type="primary" @click="open = true">Start tour</NsButton>
<NsButton ref="inboxRef" icon="mail">Inbox</NsButton>
<NsButton ref="settingRef" icon="setting">Settings</NsButton>
</NsSpace>
<NsTour
v-model:open="open"
:steps="steps"
prev-button-text="Previous"
next-button-text="Next"
finish-button-text="Finish"
/>
</div>
</template>
关闭方式
默认可以点右上角的关闭按钮或按 Esc 关闭。show-close 为 false 时不显示关闭按钮;keyboard 为 false 时不响应键盘(Esc 不关闭,方向键不切换)。两个都关掉时只能走完全部步骤。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourStep } from '@ns/ui'
const open = ref(false)
const showClose = ref(true)
const keyboard = ref(true)
const helpRef = ref()
const steps: TourStep[] = [
{ target: () => helpRef.value, title: '帮助', description: '遇到问题点这里。' },
{ title: '完成', description: '点“完成”结束引导。' }
]
const show = (close: boolean, key: boolean) => {
showClose.value = close
keyboard.value = key
open.value = true
}
</script>
<template>
<div>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace wrap>
<NsButton @click="show(true, true)">默认</NsButton>
<NsButton @click="show(false, true)">不显示关闭按钮(show-close=false)</NsButton>
<NsButton @click="show(true, false)">不响应键盘(keyboard=false)</NsButton>
<NsButton @click="show(false, false)">两个都关掉</NsButton>
</NsSpace>
<NsButton ref="helpRef" icon="info">帮助</NsButton>
</NsSpace>
<NsTour v-model:open="open" :steps="steps" :show-close="showClose" :keyboard="keyboard" />
</div>
</template>
单步设置
每一步可以单独设置 placement、mask、type,优先于组件上的同名属性。下面第 1 步卡片在右边,第 2 步换成主色卡片,第 3 步没有遮罩:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourStep } from '@ns/ui'
const open = ref(false)
const homeRef = ref()
const appsRef = ref()
const userRef = ref()
const steps: TourStep[] = [
{
target: () => homeRef.value,
title: '首页',
description: '这一步 placement 是 right。',
placement: 'right'
},
{
target: () => appsRef.value,
title: '应用',
description: '这一步 type 是 primary。',
type: 'primary'
},
{
target: () => userRef.value,
title: '个人中心',
description: '这一步 mask 是 false,页面可以操作。',
mask: false
}
]
</script>
<template>
<div>
<NsSpace direction="vertical" align="start" size="large">
<NsButton type="primary" @click="open = true">开始引导</NsButton>
<NsSpace>
<NsButton ref="homeRef" icon="home">首页</NsButton>
<NsButton ref="appsRef" icon="apps">应用</NsButton>
<NsButton ref="userRef" icon="user">个人中心</NsButton>
</NsSpace>
</NsSpace>
<NsTour v-model:open="open" :steps="steps" />
</div>
</template>
插槽
title、默认插槽:自定义标题和正文,参数是{ step, current, total }。indicator:自定义步骤指示,参数是{ current, total }。actions:自定义底部按钮,参数在上面的基础上多了isFirst、isLast和prev、next、close三个方法;最后一步调用next等同于点“完成”。
width 是卡片宽度,默认 320px,内容多时可以加宽。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTag, NsTour } from '@ns/ui'
import type { TourStep } from '@ns/ui'
const open = ref(false)
const exportRef = ref()
const chartRef = ref()
const steps: TourStep[] = [
{ target: () => exportRef.value, title: '批量导出', description: '勾选多行后一次导出。' },
{ target: () => chartRef.value, title: '图表视图', description: '把表格数据切换成图表。' }
]
</script>
<template>
<div>
<NsSpace direction="vertical" align="start" size="large">
<NsButton type="primary" @click="open = true">看看新功能</NsButton>
<NsSpace>
<NsButton ref="exportRef" icon="download">导出</NsButton>
<NsButton ref="chartRef" icon="eye">图表</NsButton>
</NsSpace>
</NsSpace>
<NsTour v-model:open="open" :steps="steps" :width="360">
<template #title="{ step }">
<NsSpace size="small">
<span>{{ step.title }}</span>
<NsTag size="small" type="success">新功能</NsTag>
</NsSpace>
</template>
<template #default="{ step, current }">
<p class="tour-text">{{ step.description }}</p>
<p class="tour-tip">小提示:按 ← → 也能切换,这是第 {{ current + 1 }} 个新功能。</p>
</template>
<template #indicator="{ current, total }">
<span class="tour-tip">还剩 {{ total - current - 1 }} 个</span>
</template>
<template #actions="{ isLast, next, close }">
<NsButton size="small" variant="text" @click="close">跳过</NsButton>
<NsButton size="small" type="primary" @click="next">
{{ isLast ? '开始使用' : '继续' }}
</NsButton>
</template>
</NsTour>
</div>
</template>
<style scoped>
.tour-text {
margin: 0;
}
.tour-tip {
margin: var(--ns-spacing-2) 0 0;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
span.tour-tip {
margin: 0;
}
</style>
事件
change:点上一步、下一步或按方向键切换了步骤,参数是新的步骤序号。外部改current不触发。finish:在最后一步点了“完成”。close:点了关闭按钮或按了 Esc,参数是关闭时所在的步骤。点“完成”不触发close。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourStep } from '@ns/ui'
const open = ref(false)
const logs = ref<string[]>([])
const undoRef = ref()
const redoRef = ref()
const refreshRef = ref()
const steps: TourStep[] = [
{ target: () => undoRef.value, title: '撤销', description: '撤销上一次修改。' },
{ target: () => redoRef.value, title: '重做', description: '恢复刚才撤销的修改。' },
{ target: () => refreshRef.value, title: '刷新', description: '重新加载数据。' }
]
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 5)
}
</script>
<template>
<div>
<NsSpace direction="vertical" align="start" size="large">
<NsButton type="primary" @click="open = true">开始引导</NsButton>
<NsSpace>
<NsButton ref="undoRef" icon="rotate-left">撤销</NsButton>
<NsButton ref="redoRef" icon="rotate-right">重做</NsButton>
<NsButton ref="refreshRef" icon="refresh">刷新</NsButton>
</NsSpace>
<div>
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
<div v-if="!logs.length">打开引导试试,事件会显示在这里</div>
</div>
</NsSpace>
<NsTour
v-model:open="open"
:steps="steps"
@change="(current) => log(`change:切到第 ${current + 1} 步`)"
@finish="log('finish:完成了引导')"
@close="(current) => log(`close:在第 ${current + 1} 步关闭`)"
/>
</div>
</template>
重新定位
页面滚动、窗口缩放,以及卡片、目标或页面的尺寸变化时会自动重新定位。目标被移动、但尺寸没变(例如改了外边距、做了位移动画)时,调用 updatePosition() 手动重新定位。
这个示例关掉了遮罩,打开后点“移动目标”:
<script setup lang="ts">
import { nextTick, ref } from 'vue'
import { NsButton, NsSpace, NsTour } from '@ns/ui'
import type { TourExpose, TourStep } from '@ns/ui'
const open = ref(false)
const moved = ref(false)
const tourRef = ref<TourExpose>()
const boxRef = ref<HTMLElement>()
const steps: TourStep[] = [
{
target: () => boxRef.value,
title: '会移动的目标',
description: '点“移动目标”,高亮区域和卡片会跟过去。'
}
]
const move = async () => {
moved.value = !moved.value
await nextTick()
tourRef.value?.updatePosition()
}
</script>
<template>
<div>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap>
<NsButton type="primary" @click="open = true">打开</NsButton>
<NsButton @click="move">移动目标</NsButton>
</NsSpace>
<div class="track">
<div ref="boxRef" class="box" :class="{ 'box--moved': moved }">目标</div>
</div>
</NsSpace>
<NsTour ref="tourRef" v-model:open="open" :steps="steps" :mask="false" />
</div>
</template>
<style scoped>
.track {
padding-bottom: 160px;
}
.box {
width: 80px;
padding: var(--ns-spacing-3) 0;
text-align: center;
color: var(--ns-color-white);
background: var(--ns-color-primary);
border-radius: var(--ns-border-radius);
}
.box--moved {
margin-left: 240px;
}
</style>
键盘操作
| 按键 | 作用 |
|---|---|
| Esc | 关闭,触发 close |
| → | 下一步。最后一步时不动,不会直接完成 |
| ← | 上一步。第一步时不动 |
| Tab | 有遮罩时在卡片里循环;没有遮罩时可以移到页面上 |
打开后焦点移到卡片上,关闭后还给打开前聚焦的元素。焦点在输入框里,或者没有遮罩、焦点在页面别处时,方向键不切换步骤。keyboard 为 false 时 Esc 和方向键都不响应。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| open | boolean | false | 是否显示,支持 v-model:open |
| current | number | — | 当前第几步(从 0 开始),支持 v-model:current。不传时组件自己记录,每次打开从第一步开始 |
| steps | TourStep[] | [] | 步骤,见下面的 TourStep |
| type | 'default' | 'primary' | 'default' | 卡片外观 |
| mask | boolean | { color?: string } | true | 遮罩。false 不显示,传 color 改颜色 |
| gap | { offset?: number; radius?: number } | { offset: 6, radius: 6 } | 高亮区域每边外扩的距离和圆角(px) |
| placement | PopperPlacement | 'bottom' | 卡片相对目标的位置,12 个方向,放不下时自动翻转 |
| arrow | boolean | true | 是否显示指向目标的箭头,没有目标时不显示 |
| width | number | string | 320 | 卡片宽度,数字按 px 处理;最宽不超过视口宽度减 16px |
| indicator | 'text' | 'dots' | 'none' | 'text' | 步骤指示:文字“2 / 4”、圆点、不显示 |
| showClose | boolean | true | 是否显示右上角的关闭按钮 |
| keyboard | boolean | true | 是否响应键盘:Esc 关闭,左右方向键切换 |
| prevButtonText | string | '上一步' | “上一步”按钮的文字 |
| nextButtonText | string | '下一步' | “下一步”按钮的文字 |
| finishButtonText | string | '完成' | 最后一步“完成”按钮的文字 |
TourStep
| 属性 | 类型 | 说明 |
|---|---|---|
| target | TourTarget | 要高亮的目标:选择器、元素、组件实例、ref,或返回它们的函数。不写时卡片在屏幕中间 |
| title | string | 标题 |
| description | string | 说明 |
| placement | PopperPlacement | 这一步卡片的位置,优先于组件的 placement |
| mask | boolean | { color?: string } | 这一步的遮罩,优先于组件的 mask |
| type | 'default' | 'primary' | 这一步卡片的外观,优先于组件的 type |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:open | (value: boolean) | 关闭(点关闭按钮、按 Esc、点“完成”)时触发,值是 false |
| update:current | (value: number) | 切换步骤时触发 |
| change | (current: number) | 点上一步、下一步或按方向键切换了步骤。外部改 current 不触发 |
| finish | — | 在最后一步点了“完成” |
| close | (current: number) | 点了关闭按钮或按了 Esc,参数是关闭时所在的步骤。点“完成”、外部改 open 不触发 |
Slots
| 插槽 | 参数 | 说明 |
|---|---|---|
| title | { step, current, total } | 标题 |
| default | { step, current, total } | 正文,替换步骤的 description |
| indicator | { current, total } | 步骤指示 |
| actions | { step, current, total, isFirst, isLast, prev, next, close } | 底部按钮,替换“上一步”“下一步”按钮 |
方法
| 方法 | 说明 |
|---|---|
| updatePosition | 重新计算高亮区域和卡片位置。目标被移动(不是滚动、缩放引起的)后调用 |
类型
import type {
TourProps,
TourEmits,
TourStep,
TourTarget,
TourTargetElement,
TourType,
TourMask,
TourGap,
TourIndicator,
TourStepSlotProps,
TourIndicatorSlotProps,
TourActionsSlotProps,
TourSlots,
TourExpose
} from '@ns/ui'
注意事项
target写成buttonRef.value时,定义步骤那一刻元素可能还没渲染,取到的是undefined,整个引导都会按“没有目标”显示。写成函数() => buttonRef.value就没有这个问题。- 写了
target但找不到元素(选择器没匹配到、函数返回空、选择器不合法)时,开发环境会在控制台警告,卡片按没有目标显示在屏幕中间。之后页面滚动、窗口缩放时会再找一次,找到了就移过去。 - 目标是组件实例时取它的根元素;多根节点的组件(例如
NsButton)取第一个元素。 - 引导时不锁定页面滚动。目标不在可视区域时会平滑滚到中间(系统设置了减少动态效果时直接跳过去)。
- 有遮罩时整个页面(包括高亮的目标)都不能点击。需要用户边看引导边操作页面时,关掉这一步的遮罩(
mask: false)。 - 关闭只发
update:open,要用v-model:open绑定才会真正关闭。current同理:传了current就由外部控制,要用v-model:current。 steps为空时不显示,开发环境会警告。current超出范围时按第一步或最后一步显示。- 关闭按钮的
aria-label固定是“关闭”。 - 写在
NsTour上的class、style等属性加在最外层的全屏节点上(它不接收鼠标事件),不是卡片上。 - 卡片挂在
body下,层级取NsConfigProvider的zIndex,默认 2000。 - 服务端渲染时不访问
window,打开状态下输出居中的卡片,到浏览器里再按目标定位。