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。
← API 文档使用建议
用户引导: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。
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--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) |