Tour 引导
分步功能引导，带全屏遮罩与目标高亮。支持 12 向定位与溢出翻转、滚动跟随、遮罩/形态定制、键盘导航、异步步骤、hints 信标与「不再显示」记忆。
基础用法
开始引导
引导事件
oas-step 步骤切换携带 detail: { index, current, total, next, prev }；关闭类事件（cancel/finish/close/skip/destroy）携带 detail: { index, total }（其中 oas-cancel 额外携带 source 标识取消来源）。
步骤事件
受控步骤与开关
open 与 current 均为受控属性：外部按钮 / JS 设置 open 启动引导，设置 current 直接跳到指定步骤（无需逐步点击）。
受控 open / current
定位与箭头
placement 支持 12 向（top/bottom/left/right × start/end/center）+ center，空间不足时自动沿主轴翻转；arrow="false" 隐藏箭头。
12 向定位与自动翻转
滚动到目标与重定位
目标在视口外时自动滚动到目标（scroll-into-view-options 透传，scroll-padding 写目标 scroll-margin 留白）；引导期间滚动/resize 高亮与弹层自动跟随（auto-reposition，默认开启）。
滚动到目标与滚动跟随
遮罩与形态
mask="false" 关闭遮罩（非模态，引导期间页面其余区域可交互）；mask='{"color":"..."}' 定制遮罩颜色；type="primary" 主色底弹层强调；gap 控制高亮内边距与圆角（数字或 {padding, radius}）。
非模态 + 主色弹层
键盘导航与指示器
keyboard（默认开启）支持 ←/→ 推进步骤；show-bullets 圆点指示器可点击跳步；show-progress 顶部进度条；progress-text 模板（占位符 current/total，各以双花括号包裹）自定义计数文本；indicators="number" 数字计数。
键盘导航 + 圆点 + 进度条
按钮显隐与透传
hide-prev / hide-skip / hide-next / hide-counter 控制按钮与计数显隐；next-button-props / prev-button-props / skip-button-props 透传任意属性到对应按钮（JSON 对象）。末步的「完成」由 next 按钮承载（文案切「完成」）；此时 finish-button-props 叠加在 next-button-props 之上（step 级优先）。
按钮显隐与属性透传
关闭按钮定制
show-close="false" 隐藏关闭按钮；close-icon 自定义关闭按钮内容（HTML）。
关闭按钮定制
遮罩点击与高亮区交互
mask-click-behavior：close（默认）/ next（点击遮罩推进）/ none（忽略）；target-area-clickable 高亮区可点击（点击穿透目标）；disabled-interaction 禁止高亮区交互；advance-on-click 点击高亮区推进（交互式引导「点这里试试」）。
遮罩点击行为 + 高亮区交互
异步步骤
wait-for-element（毫秒）等待目标出现（如「上一步点击打开了弹窗，等里面元素渲染」）；skip-missing-element 目标缺失/等待超时自动跳过该步骤。
异步目标等待与跳过
对话框模式
mode="dialog"（或 step 级 mode: "dialog"）无目标居中对话框步骤，作为一等形态混入引导。
对话框模式
生命周期事件
oas-highlight-start 在步骤 index 变化时即派发（先于异步目标等待），oas-highlight-end 在高亮定位完成后派发（目标异步等待命中后才进入定位）；oas-destroy 在引导关闭时派发（含外部移除 open）。
生命周期事件
不再显示与多页引导
dont-show-again 关闭时勾选「不再显示」，经 storage-key 记忆到 localStorage，下次启动被拦截并派发 oas-dismiss；persist 把 open/current 状态持久化，路由切换重新挂载后自动恢复（多页引导）。
「不再显示」记忆
多页引导（persist）
打字机与锁滚动
typewriter（opt-in，未设置即不开）+ typewriter-speed 描述逐字显示动画；lock-scroll 引导期间锁定页面滚动；close-on-press-escape="false" 关闭 Esc。
打字机动画 + 锁滚动
hints 信标模式
hints 常驻脉冲信标（无需 open），点击弹出气泡；dismissable + id 的提示关闭后记忆到 localStorage（oas-tour-hint-${id}）不再显示。
hints 信标模式
挂载点与层级
append-to="body"（或选择器）把整个浮层挂载到指定容器；z-index 定制层级。
挂载点与层级
高级定制（gap 双轴 / 箭头指向 / 关闭自动翻转）
gap 支持 offset 双轴外扩（number 四周同值 / [水平, 垂直] 数组，与 padding 正交）；arrow-point-at-center 让箭头在弹层被视口避让偏移后仍指向目标中心；auto-reposition="false" 关闭溢出翻转与视口避让（保持声明 placement）。
gap 双轴 + 箭头指向中心 + 关闭自动翻转
自定义指示器与动作区（插槽）
slot="indicators" 替换内置圆点/数字指示器（宿主用 oas-step 事件的 current/total 渲染）；slot="actions" 替换整个内置按钮区，用自定义按钮控制跳步。
自定义指示器与动作区
API
oas-tour
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
advance-on-click | 点击高亮区推进下一步（交互式引导） | boolean | — |
append-to | 挂载点：body 或 CSS 选择器（整个浮层移入目标容器） | string | — |
arrow | 是否显示箭头（布尔，默认 true，false 隐藏） | string | true |
arrow-point-at-center | 箭头指向目标中心投影（弹层被视口避让偏移后仍指准；默认箭头贴 placement 对齐端） | boolean | — |
auto-reposition | 滚动/resize 时自动重定位 + 溢出翻转/视口避让（默认 true；false 关闭翻转与避让，保持声明位置） | string | true |
close-icon | 自定义关闭按钮内容（HTML 字符串） | string | — |
close-on-press-escape | Esc 关闭（默认 true） | string | true |
current | 当前步骤索引 | string | 0 |
disabled-interaction | 禁止高亮区交互（拦截层覆盖目标） | — | — |
dont-show-again | 「不再显示」开关（布尔；关闭时勾选则记忆到 localStorage） | boolean | — |
finish-button-props | 末步「完成」按钮透传属性（JSON）：末步 next 即完成按钮，finish-button-props 叠加在 next-button-props 之上（step 级优先） | — | — |
gap | 高亮内边距：数字（padding px）或 {"padding","radius","offset"}；offset 为高亮外扩间距（number 四周同值 / [水平, 垂直] 双轴，与 padding 正交）；默认 padding 4 | string | — |
hide-counter | 隐藏步骤计数 | boolean | — |
hide-next | 隐藏下一步按钮 | — | — |
hide-prev | 隐藏上一步按钮 | — | — |
hide-skip | 隐藏跳过按钮 | — | — |
hints | hints 信标模式：JSON [{id,selector,title,description,placement,dismissable}]，常驻脉冲点，点击弹气泡，dismissable 关闭后记忆 | string | [] |
indicators | 计数样式：dots（默认）/ number / none | string | dots |
keyboard | 键盘 ←/→ 推进步骤（默认 true，false 关闭） | string | true |
lock-scroll | 引导期间锁定页面滚动（关闭恢复） | boolean | — |
mask | 遮罩开关/定制：false 关闭（非模态）或 {"color","style"} 定制颜色样式（默认 true）；step 级可覆盖 | string | true |
mask-click-behavior | 遮罩点击行为：close（默认）/ next（推进）/ none（忽略） | string | close |
mode | 弹层模式：popup（默认）/ dialog（无目标居中对话框）；step 级可覆盖 | string | popup |
next-button-props | 下一步按钮透传属性（JSON 对象，如 {"data-x":"1"}） | — | — |
open | 开始引导（布尔属性，存在即启动） | boolean | — |
persist | 多页引导：open/current 状态持久化到 localStorage，重新连接时恢复 | boolean | — |
placement | 弹层方位：12 向（top/bottom/left/right × start/end/center）+ center（空 target 居中）；默认 bottom；空间不足自动翻转；step 级可覆盖 | TourPlacement | bottom |
prev-button-props | 上一步按钮透传属性（JSON 对象） | — | — |
progress-text | 进度文本模板：以双花括号包裹的 current/total 占位符替换（如 current/total 各包一层花括号）；设置后计数区用模板渲染 | string | — |
scroll-into-view-options | 滚动到目标的 scrollIntoView options（JSON，默认 {"behavior":"smooth","block":"center"}） | string | — |
scroll-padding | 滚动到目标时的留白（px，写目标 scroll-margin） | — | — |
show-bullets | 圆点指示器（点击圆点跳步） | boolean | — |
show-close | 显示关闭按钮（默认 true，false 隐藏） | string | true |
show-progress | 弹层顶部进度条（宽度随步骤推进） | boolean | — |
skip-button-props | 跳过按钮透传属性（JSON 对象） | — | — |
skip-missing-element | 目标缺失/等待超时跳过该步骤（默认停在当前步骤） | boolean | — |
steps | 步骤 JSON（TourStep[] | string）；property 赋值支持函数/元素 target | TourStep[] | string | [] |
storage-key | localStorage 记忆键（dont-show-again / persist / hint dismiss 共用） | string | oas-tour-dismiss |
target-area-clickable | 高亮区可交互（opt-in）：未设置即关闭（拦截层覆盖目标、不可点）；设置后拦截层隐藏、点击穿透目标 | string | — |
type | 弹层类型：default / primary（主色底弹层，非模态场景强调） | string | default |
typewriter | 打字机动画（opt-in）：未设置即不开；设置后描述逐字显示，typewriter="false" 关闭 | string | — |
typewriter-speed | 打字机速率（ms/字符，默认 20） | string | 20 |
wait-for-element | 等待目标出现（毫秒，异步步骤；全局默认，step 级 waitForElement 优先） | — | — |
z-index | 遮罩层级（默认 --oas-z-modal） | — | — |
事件
| 事件 | 说明 |
|---|---|
oas-cancel | 跳过 / Esc / 遮罩点击关闭，detail: { index, total, source }（source: skip/esc/close/mask） |
oas-close | 点击关闭按钮，detail: { index, total } |
oas-destroy | 引导关闭（含外部移除 open），detail: { index, total } |
oas-dismiss | 「不再显示」命中，引导启动被拦截，detail: {} |
oas-finish | 最后一步点击「完成」，detail: { index, total } |
oas-highlight-end | 步骤高亮完成，detail: { index, total } |
oas-highlight-start | 步骤高亮开始（异步等待命中后），detail: { index, total } |
oas-skip | 点击「跳过」按钮，detail: { index, total } |
oas-step | 步骤切换，detail: { index, current, total, next, prev } |
插槽
| 名称 | 说明 |
|---|---|
actions | 自定义动作区（替换整个内置按钮区；有内容时隐藏内置 prev/skip/next 按钮） |
cover | 步骤封面富内容（插槽优先于 step.cover 图片） |
indicators | 自定义指示器区（宿主用 oas-step 的 current/total 渲染；有内容时隐藏内置圆点/数字指示器） |
CSS 变量
| CSS 变量 | 默认值 |
|---|---|
--oas-glass-blur | none |
--oas-glass-ring | transparent |
--oas-tour-arrow-align-offset | 16px |
--oas-tour-arrow-height | 12px |
--oas-tour-arrow-radius | 0 |
--oas-tour-arrow-width | 12px |
--oas-tour-mask-color | var(--oas-color-overlay) |
--oas-tour-popup-bg | var(--oas-color-bg) |
遮罩高亮目标，role="dialog" + aria-modal="true"（mask="false" 非模态时降级为 aria-modal="false"）；支持「上一步 / 下一步 / 跳过」、键盘 ←/→ 与 Esc。