UserGuide
用户引导：popup 模式复用本库 Popover（trigger="custom"）贴气泡讲解 + svg mask 挖洞 spotlight 遮罩逐个高亮目标元素（4 块透明 rect 让高亮区可交互，目标不在视口时 scrollIntoView）；modal 模式复用本库 Modal（header/footer=null、centered、bodyStyle padding:0）图文引导（cover 封面 + 圆点指示器）。步进状态机在 core createUserGuide：current 受控（提供 current 即受控，内部不改需配合 onChange 回写）/非受控，handlePrev/handleNext/handleSkip 回调去重（current 未变不 notify onChange），末步 handleNext 触发 onFinish，visible false→true 重置 current=0 并锁 body 滚动（getPopupContainer 时跳过、补偿滚动条宽），按钮显隐规则（跳过=非末步、上一步=非首步、下一步/完成）。指示器 popup 为纯文本 n/total（对齐 Semi 无 i18n），modal 为圆点。onFinish/onSkip 不自动关闭，使用方置 visible=false。严格对齐 Semi：无 focus-trap/inert/Esc/箭头键/进度 aria/live-announcer。
如何引入
import { UserGuide } from '@chenzy-design/svelte';基本用法
popup 气泡模式逐个高亮目标元素，配合标题与描述引导用户操作
主题
popup 气泡卡片提供 default 与 primary 两种主题，通过 theme 设置
气泡卡片弹出位置
popup 提供 12 种弹出位置，可通过 showArrow 设置是否显示箭头
设置高亮区域大小
通过 spotlightPadding 设置高亮区域内边距，支持 step 级覆盖
定制按钮
通过 nextButtonProps / prevButtonProps 与 finishText 定制按钮样式与文案
受控
通过 current + onChange 由外部状态托管当前引导步骤
弹窗式引导
mode="modal" 开启居中弹窗式图文引导，含封面图与底部圆点指示器
无遮罩
mask={false} 开启无遮罩引导，不遮挡背景内容
API 参考
UserGuide
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
steps | 必填，引导步骤数组 | StepItem[] | [] |
visible | 是否显示；false→true 重置到第 0 步 | boolean | false |
current | 当前步索引；提供即受控（内部不改，配合 onChange 回写） | number | 0 |
mode | popup=气泡+spotlight；modal=居中弹窗 | 'popup'|'modal' | 'popup' |
mask | 是否显示遮罩 | boolean | true |
theme | 气泡主题（popup） | 'default'|'primary' | 'default' |
position | 气泡相对目标位置（14 方位，可被 step 覆盖） | Position | 'bottom' |
spotlightPadding | 高亮区内边距 px（可被 step 覆盖） | number | 5 |
showPrevButton | 显示上一步（首步自动隐藏） | boolean | true |
showSkipButton | 显示跳过（末步自动隐藏） | boolean | true |
finishText | 末步完成按钮文本 | string | i18n finish |
nextButtonProps | 下一步按钮属性透传 | ButtonProps | {} |
prevButtonProps | 上一步按钮属性透传 | ButtonProps | {} |
getPopupContainer | 挂载父级；提供时不锁 body 滚动 | () => HTMLElement | undefined |
zIndex | 弹层/spotlight 层级 | number | 1030 |
class | 气泡 popover 类名 | string | undefined |
style | 气泡 popover 内联样式 | string | undefined |
onChange | 步骤改变（去重） | (current: number) => void | undefined |
onNext | 点下一步（非末步），参数为新 current | (current: number) => void | undefined |
onPrev | 点上一步，参数为 current-1 | (current: number) => void | undefined |
onFinish | 末步点完成（不自动关闭） | () => void | undefined |
onSkip | 点跳过（不自动关闭） | () => void | undefined |
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--cd-userguide-modal-indicator-bg | var(--cd-color-primary-light-active) | modal 指示器未激活态（.cd-userGuide-modal-indicator-item） |
--cd-userguide-modal-indicator-bg-active | var(--cd-color-primary) | modal 指示器激活态（.cd-userGuide-modal-indicator-item-active） |
--cd-userguide-popup-text-default | var(--cd-color-text-0) | popup default 主题文字（.cd-userGuide-popup-content） |
--cd-userguide-popup-text-primary | var(--cd-color-tertiary-light-default) | popup primary 主题文字（.cd-userGuide-popup-content-primary） |
--cd-userguide-spotlight-mask-bg | var(--cd-color-overlay-bg) | popup spotlight 遮罩背景（.cd-userGuide-spotlight rect fill） |