前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载Tour引导是 ant-design-vue 提供的一个弹层组件用于引导用户了解产品功能自4.0.0版本开始提供。本文以 components/tour/index.en-US.md 为骨架结合仓库内 Tour 组件源码、底层 vc-tour 实现 与官方 Demo 示例系统讲解 Tour 的完整 API、事件、进阶用法与底层实现原理帮助你快速把「新手引导」能力落地到实际 Vue 3 项目中。When To Use 使用场景当你想引导用户了解产品例如首次进入某个新功能模块时通过步骤化的高亮卡片依次介绍页面上的关键操作区时就可以使用 Tour。它适合承担产品功能引导Onboarding、新版本功能播报、复杂表单填写指引等任务。与传统的Tooltip/Popover被动提示不同Tour 是主动式、步骤化的引导它把多个提示步骤串成一条路径配合遮罩高亮目标元素用户在引导下依次完成了解与操作。要按步骤依次高亮多个元素只需在steps数组中配置多个TourStep即可。快速上手基本用法先看官方 basic.vue 演示的最简用法。其核心思路是用ref拿到目标 DOM通过target回调返回元素把步骤配置在steps数组中用open控制开关template a-button typeprimary clickhandleOpen(true)Begin Tour/a-button a-divider / a-space a-button refref1Upload/a-button a-button refref2 typeprimarySave/a-button a-button refref3EllipsisOutlined //a-button /a-space a-tour v-model:currentcurrent :openopen :stepssteps closehandleOpen(false) / /template script langts setup import { ref, createVNode } from vue; import { EllipsisOutlined } from ant-design/icons-vue; import type { TourProps } from ant-design-vue; const open refboolean(false); const ref1 ref(null); const ref2 ref(null); const ref3 ref(null); const current ref(0); const steps: TourProps[steps] [ { title: Upload File, description: Put your files here., cover: createVNode(img, { alt: tour.png, src: https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png, }), target: () ref1.value ref1.value.$el, }, { title: Save, description: Save your changes., target: () ref2.value ref2.value.$el, }, { title: Other Actions, description: Click to see other actions., target: () ref3.value ref3.value.$el, }, ]; const handleOpen (val: boolean): void { open.value val; }; /script几个关键细节target既可以是HTMLElement也可以是一个返回HTMLElement的函数由于 Vue 组件ref拿到的是组件实例需要用$el取真实 DOM。在script setup中target: () ref1.value ref1.value.$el会在引导弹出时求值此时 DOM 已挂载ref非空。v-model:current双向绑定当前步骤下标从 0 开始方便你在外部同步引导进度。Tour 组件 API 全解以下是 components/tour/index.en-US.md 中 Tour 组件的完整属性表结合 interface.ts 中tourProps()的定义补充了各属性的取值说明与默认值属性说明类型默认值版本arrow是否显示箭头可配置是否指向元素中心boolean|{ pointAtCenter: boolean }trueplacement引导卡片相对于目标元素的位置leftleftTopleftBottomrightrightToprightBottomtoptopLefttopRightbottombottomLeftbottomRightbottommask是否开启遮罩可传自定义属性修改遮罩样式与填充色boolean|{ style?: CSSProperties; color?: string }truetype类型影响底色与文字颜色defaultprimarydefaultopen是否开启引导boolean-current (v-model)当前步骤下标number-scrollIntoViewOptions支持传入自定义的 scrollIntoView 选项boolean|ScrollIntoViewOptionstrueindicatorsRender自定义指示器当前步骤/总步骤数展示v-slot:indicatorsRender{ current, total }-zIndexTour 的 zIndexnumber1001说明与补充属性声明位置open、steps、current、defaultCurrent、zIndex、mask、arrow、placement、scrollIntoViewOptions等基础属性实际声明在底层 vc-tour 的 tourProps() 中外层 Tour 组件 通过展开...VCTourProps()继承并额外叠加steps、current、type、prefixCls与onUpdate:current供v-model:current使用。placement 的 12 个取值共覆盖四边×三档top/topLeft/topRight、bottom/bottomLeft/bottomRight、left/leftTop/leftBottom、right/rightTop/rightBottom。当target为空时卡片展示在屏幕正中央此时该属性不生效。zIndex 默认 1001该默认值定义在 vc-tour/Tour.tsx 中zIndex: { type: Number, default: 1001 }同时透传给遮罩层与弹层确保引导浮层盖在常规内容之上。Tour 事件事件名说明参数版本close关闭时的回调Function-finish全部步骤完成时的回调Function-change步骤切换时的回调current 为切换前的步骤(current: number) void在 组件入口 index.tsx 中可以印证事件的传递链路const onStepChange (stepCurrent: number) { updateInnerCurrent(stepCurrent); emit(update:current, stepCurrent); emit(change, stepCurrent); };即每次步骤切换点击 Next/Prev 按钮都会依次触发update:current与change而close与finish事件由底层 vc-tour 的onClose/onFinish冒泡而来——finish会在点击最后一步的按钮时触发随后自动关闭引导见 vc-tour/Tour.tsx 中onFinish的处理handleClose(); onFinish?.()。TourStep 属性全解steps数组中的每个元素即一个TourStep其属性由 tourStepProps() 声明属性说明类型默认值版本target获取引导卡片指向的元素为空时居中显示() HTMLElement|HTMLElement-arrow是否显示箭头可配置是否指向元素中心boolean|{ pointAtCenter: boolean }truecover展示的图片或视频VueNode-title标题VueNode-description描述VueNode-placement引导卡片相对目标元素的位置取值同 Tour同上 12 个取值bottommask是否开启遮罩默认跟随 Tour 的 mask 属性boolean|{ style?: CSSProperties; color?: string }truetype类型影响底色与文字颜色default|primarydefaultnextButtonProps「下一步」按钮的属性{ children: VueNode; onClick: Function }-prevButtonProps「上一步」按钮的属性{ children: VueNode; onClick: Function }-scrollIntoViewOptions自定义 scrollIntoView 选项默认跟随 Tour 的属性boolean|ScrollIntoViewOptionstrue补充说明步骤级配置优先于组件级在 vc-tour/Tour.tsx 中mask、placement、scrollIntoViewOptions、arrow均遵循「当前步骤有值用当前步骤否则回退到组件属性」的合并策略例如const mergedMask computed(() mergedOpen.value (curStep.value.mask ?? mask.value)); const mergedPlacement computed(() curStep.value.placement ?? placement.value); const mergedScrollIntoViewOptions computed( () curStep.value.scrollIntoViewOptions ?? scrollIntoViewOptions.value, );arrow 的特殊行为只有当目标元素存在时才绘制箭头无目标居中展示时箭头自动隐藏mergedArrow中targetElement.value ? ... : false。step 内部还支持className与style这两项定义在底层 vc-tour/interface.ts 的tourStepInfo()中可对单个引导卡片的弹层做样式定制通过popupClassName与popupStyle生效。type与cover为外层组件新增的快捷属性cover可直接放置图片/视频节点type影响面板底色与文字颜色。TourStep 事件事件名说明参数版本close关闭时的回调Function-其余步骤级行为通过nextButtonProps/prevButtonProps的onClick定制。进阶实战一placement 位置控制官方 placement.vue 展示了位置控制的完整写法——单步可覆盖组件级默认位置且target: null时卡片居中template a-button refbtnRef typeprimary clickhandleOpen(true)Begin Tour/a-button a-tour :openopen :stepssteps closehandleOpen(false) / /template script langts setup import { ref } from vue; import type { TourProps } from ant-design-vue; const open refboolean(false); const btnRef ref(null); const steps: TourProps[steps] [ { title: Center, description: Displayed in the center of screen., target: null, }, { title: Right, description: On the right of target., placement: right, target: () btnRef.value btnRef.value.$el, }, { title: Top, description: On the top of target., placement: top, target: () btnRef.value btnRef.value.$el, }, ]; /script实现原理当步骤没有target时vc-tour/Tour.tsx 会使用一个CENTER_PLACEHOLDERleft: 50%; top: 50%; width: 1px; height: 1px作为定位占位并给弹层设置transform: translate(-50%, -50%)实现居中同时getTriggerDOMNode回退到document.body作为触发器。有目标时默认的内置定位由getPlacements({ arrowPointAtCenter: true, autoAdjustOverflow: true })生成见 index.tsx支持自动防溢出调整。进阶实战二自定义遮罩与非模态自定义遮罩样式官方 mask.vue 演示了如何在组件级与步骤级分别定制遮罩a-tour :openopen :stepssteps :mask{ style: { boxShadow: inset 0 0 15px #333, }, color: rgba(80, 255, 255, .4), } closehandleOpen(false) /其中color控制遮罩填充色默认rgba(0,0,0,0.5)style作为样式对象注入遮罩层。步骤内部还可以逐步骤覆盖甚至关闭遮罩mask: false。实现原理遮罩由 vc-tour/Mask.tsx 渲染本质是一个全屏定位的 SVG用mask在白色全屏矩形上「挖」出目标元素对应的黑色圆角矩形rx{pos.radius}再用fill填充并应用该 mask从而形成「目标区域透明、其余区域半透明」的挖洞效果同时绘制 4 个pointer-events: auto的透明矩形覆盖在目标四周拦截遮罩外的点击事件COVER_PROPS防止引导过程中误触页面其他区域。非模态引导官方 non-modal.vue 展示使用mask{false}可将引导变为非模态——不拦截外部交互同时推荐搭配typeprimary突出引导卡片本身a-tour :openopen :maskfalse typeprimary :stepssteps closehandleOpen(false) /实现上mask{false}会让 Mask.tsx 只渲染全屏占位容器而不渲染 SVG 挖洞层showMask ? ... : null用户仍可操作页面此时引导卡片更依赖自身样式如 primary 底色来获得视觉强调。进阶实战三自定义指示器 indicatorsRender默认指示器是一组小圆点活跃步骤高亮。官方 indicator.vue 演示如何用插槽完全替换为「1 / 3」式文本a-tour :openopen :stepssteps closehandleOpen(false) template #indicatorsRender{ current, total } span{{ current 1 }} / {{ total }}/span /template /a-tour插槽参数{ current, total }中current为当前步骤下标0 开始total为总步骤数所以展示时通常写作current 1。其底层在 panelRender.tsx 中消费if (slots.indicatorsRender) { mergeIndicatorNode slots.indicatorsRender({ current: current.value, total }); } else { // 默认渲染 total 个小圆点current 对应高亮 }另外默认圆点指示器仅在total 1时显示{total.value 1 (...)}单步骤引导不会出现多余指示器。进阶实战四type 与按钮定制type 影响卡片风格type支持default与primary它同时影响卡片底色/文字颜色面板容器增加${prefixCls}-primary类名按钮配色在 panelRender.tsx 中typeprimary时主按钮下一步/完成降级为default型副按钮上一步追加ghost属性避免按钮与卡片底色同色混淆const mainBtnType stepType primary ? default : primary; const secondaryBtnProps: ButtonProps { type: default, ghost: stepType primary, };步骤级 type 的合并逻辑组件级type与步骤级type的合并由 useMergedType.ts 完成它监听current/defaultCurrent优先取「当前步骤自身的 type」其次回退到组件级type并以currentMergedType驱动整卡片的 primary 样式类。按钮文案与定制按钮文案默认来自国际化上一步Previous、下一步Next、最后一步Finish见 panelRender.tsx 中LocaleReceiver componentNameTour默认取 locale/en_US.ts 的Tour配置。如需逐步骤替换文案或追加点击逻辑用prevButtonProps/nextButtonProps{ title: Save, description: Save your changes., target: () ref2.value ref2.value.$el, nextButtonProps: { children: () 下一步去保存, onClick: () console.log(custom next click), }, }从源码看nextButtonProps.onClick会在内置的onNext/onFinish之后被追加调用panelRender.tsx 的nextBtnClick。进阶实战五scrollIntoViewOptions 与自动滚动当目标元素不在视口内时Tour 会先调用element.scrollIntoView(...)将目标滚动进可视区再弹出引导。这一步由 vc-tour/hooks/useTarget.ts 实现if (!isInViewPort(targetElement.value) open.value) { targetElement.value.scrollIntoView(scrollIntoViewOptions.value); }scrollIntoViewOptions可为boolean或标准ScrollIntoViewOptions如{ block: center, behavior: smooth }默认true组件级默认值定义在 vc-tour/Tour.tsxscrollIntoViewOptions: someTypeboolean | ScrollIntoViewOptions([Boolean, Object], true)步骤级可覆盖同文件还处理了窗口resize时重新计算目标位置window.addEventListener(resize, updatePos)并在组件卸载时移除监听。源码级原理一次引导的完整渲染链路把前面各节串起来一次引导的渲染链路如下配置合并外层 components/tour/index.tsx 接收steps、open、current等通过useConfigInject(tour, props)注入prefixCls与direction支持 RTL通过useStyle注入 CSS-in-JS 样式与hashId并把步骤面板渲染函数mergedRenderPanel下发给底层。步骤状态vc-tour/Tour.tsx 用useMergedState管理mergedCurrent与mergedOpen当open首次变为 true 时自动把current重置为 0若current越界小于 0 或大于等于步骤数则视为关闭。目标定位useTarget.ts 求值target函数或元素必要时scrollIntoView再用getBoundingClientRect计算目标位置并外扩一个gap默认offset: 6、radius: 2生成PosInfo用于遮罩挖洞与占位元素。遮罩与弹层mergedOpen为真时同时渲染 Mask.tsxSVG 挖洞遮罩 点击拦截和Trigger弹层基于 vc-trigger 定位弹层内容为 TourStep 包裹的 panelRender.tsx 默认面板。交互回调点击下一步/上一步调用onInternalChange同步mergedCurrent并触发change/update:current点击关闭或完成触发close/finish。测试保障仓库在 components/tour/tests/index.test.js 中对 Tour 做了挂载级冒烟测试mountTest验证组件可正常渲染。小结Tour 组件把「步骤管理 目标定位 遮罩挖洞 弹层定位」四件事封装成一套简单声明式 API你只需提供steps数组每个步骤含target、title、description并用open控制开关即可获得可定制位置12 种 placement、可定制遮罩颜色/样式/非模态、可定制指示器与按钮的完整产品引导能力。若需更深层的定制如完全重写面板结构可参考 panelRender.tsx 与 vc-tour/Tour.tsx 继续扩展。赞分享前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载相关推荐ant-design-vue Tour 漫游式引导组件完全指南从 API 参数到源码级实现原理ant design vue Tour 漫游式引导组件完全指南从 API 参数到源码级实现原理 Tour漫游式引导是 ant design vue 中用于前端UI组件设计系统Ant Design Tour 组件完全指南从 API 到源码级实现原理Ant Design Tour 组件完全指南从 API 到源码级实现原理 Tour 是 Ant Design 提供的用户引导Guided Tour浮层组件前端UI组件设计系统Ant Design Tour 漫游式引导组件实战指南从入门配置到源码级原理Ant Design Tour 漫游式引导组件实战指南从入门配置到源码级原理 本文围绕 ant design 仓库中 components/tour/inde前端UI组件设计系统上一篇Exa MCP Server容器编排Kubernetes部署与管理下一篇Guardrails监控数据可视化LLM交互分析仪表盘完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考