# 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）

跳到第 2 步（current=1）

跳到第 3 步（current=2）

结束（移除 open）

受控高亮区域一

受控高亮区域二

受控高亮区域三

## 定位与箭头 `placement` 支持 12 向（top/bottom/left/right × start/end/center）+ `center`，空间不足时自动沿主轴翻转；`arrow="false"` 隐藏箭头。

右侧定位（placement=right）

贴底自动翻转

无箭头（arrow=false）

右侧定位目标

多向定位目标

贴底目标（视口底部）

## 滚动到目标与重定位目标在视口外时自动滚动到目标（`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 级优先）。

按钮显隐 + props 透传

隐藏全部操作

按钮定制目标一

按钮定制目标二

## 关闭按钮定制 `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 状态持久化，路由切换重新挂载后自动恢复（多页引导）。

打开引导（已记忆则不显示）

清除记忆

记忆目标

开始引导

模拟路由切换（重新挂载）

多页目标一

多页目标二

## 打字机与锁滚动 `typewriter`（opt-in，未设置即不开）+ `typewriter-speed` 描述逐字显示动画；`lock-scroll` 引导期间锁定页面滚动；`close-on-press-escape="false"` 关闭 Esc。

开始引导

打字机目标一（含 cover 封面）

打字机目标二

## hints 信标模式 `hints` 常驻脉冲信标（无需 open），点击弹出气泡；`dismissable` + `id` 的提示关闭后记忆到 localStorage（`oas-tour-hint-${id}`）不再显示。

信标目标一（dismissable）

信标目标二（常驻）

## 挂载点与层级 `append-to="body"`（或选择器）把整个浮层挂载到指定容器；`z-index` 定制层级。

append-to body + 高层级

挂载目标

## 高级定制（gap 双轴 / 箭头指向 / 关闭自动翻转） `gap` 支持 `offset` 双轴外扩（`number` 四周同值 / `[水平, 垂直]` 数组，与 `padding` 正交）；`arrow-point-at-center` 让箭头在弹层被视口避让偏移后仍指向目标中心；`auto-reposition="false"` 关闭溢出翻转与视口避让（保持声明 placement）。

gap 双轴 offset

箭头指向中心

关闭自动翻转

gap 双轴目标

贴左目标

贴底目标（视口底部）

## 自定义指示器与动作区（插槽） `slot="indicators"` 替换内置圆点/数字指示器（宿主用 `oas-step` 事件的 `current/total` 渲染）；`slot="actions"` 替换整个内置按钮区，用自定义按钮控制跳步。

开始引导

1 / 2

上一步

下一步

自定义插槽目标一

自定义插槽目标二

## 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。