Tour 漫游引导
uni-appH5微信小程序App
uni-app 跨端漫游式引导。按步骤依次高亮页面目标元素并弹出说明气泡,支持上一步/下一步/跳过,target 为 null 时气泡居中展示。目标测量使用 uni.createSelectorQuery,跨端可用。
何时使用
新用户上手、新功能发布、复杂流程的分布讲解。
何时不使用
单点提示用 Toast;步骤超过 5 个考虑改用帮助文档。App 端若无稳定选择器,建议 target 传 null 走居中气泡。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | boolean | false | 显隐,配合 v-model 使用 |
steps | TourStep[] | - | 引导步骤,每项形如 { target, title, description }:target 为目标元素选择器(uni.createSelectorQuery 语法,如 '#id' 或 '.class'),null 表示无目标居中展示;title 为步骤标题;description 为可选描述 |
current | number | 0 | 当前步骤索引,配合 v-model:current 使用;不绑定时组件内部维护步骤,点击上一步/下一步即可推进 |
showClose | boolean | true | 是否显示右上角关闭按钮 |
zIndex | number | 1001 | 遮罩层层级 |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
update:modelValue | boolean | 显隐变化时触发 |
update:current | number | 步骤切换时触发 |
finish | void | 最后一步点击“完成”时触发(随后自动关闭) |
close | void | 关闭(关闭按钮/跳过/完成)时触发 |
示例
引导流程
vue
<Button variant="primary" @click="tourOpen = true">开始引导</Button>
<Tour v-model="tourOpen" :steps="tourSteps" />隐藏关闭按钮
vue
<Button variant="secondary" @click="welcomeOpen = true">强引导</Button>
<Tour v-model="welcomeOpen" :steps="tourSteps" :show-close="false" />从第二步开始
vue
<Button variant="ghost" @click="tourOpen = true">续看引导</Button>
<Tour v-model="tourOpen" :steps="tourSteps" :current="1" />