展示类

用户引导

用于页面对新用户进行功能引导

代码演示

如何引入

<script lang="ts">
    import { UserGuide } from '@fibrae/semi-ui-svelte';
</script>

基本用法



Default Tag
代码
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#basic-demo-1'),
            title: '新手引导',
            description: 'Hello ByteDancer!',
            position: 'bottom',
        },
        {
            target: () => document.querySelector('#basic-demo-2'),
            title: 'Switch',
            description: 'This is a Semi Switch',
            position: 'bottom',
        },
        {
            target: () => document.querySelector('#basic-demo-3'),
            title: 'Button',
            description: 'This is a Semi Button',
            position: 'bottom',
        },
    ];
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="basic-demo-1" />
        <Tag id="basic-demo-2">Default Tag</Tag>
        <Button id="basic-demo-3">确定</Button>
    </Space>
    <UserGuide bind:visible mask mode="popup" onChange={(current) => console.log('当前引导步骤', current)} onFinish={() => console.log('引导完成')} onNext={() => console.log('下一步引导')} onPrev={() => console.log('上一步引导')} onSkip={() => console.log('跳过引导')} {steps} />
</div>

主题

popup 气泡卡片模式下提供两种主题 default 和 primary,通过 theme 属性设置。



Default Tag
代码
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#theme-demo-1'),
            title: '新手引导',
            description: 'Hello ByteDancer!',
            position: 'bottom',
        },
        {
            target: () => document.querySelector('#theme-demo-2'),
            title: 'Switch',
            description: 'This is a Semi Switch',
            position: 'bottom',
        },
        {
            target: () => document.querySelector('#theme-demo-3'),
            title: 'Button',
            description: 'This is a Semi Button',
            position: 'bottom',
        },
    ];
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="theme-demo-1" />
        <Tag id="theme-demo-2">Default Tag</Tag>
        <Button id="theme-demo-3">确定</Button>
    </Space>
    <UserGuide bind:visible mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} {steps} theme="primary" />
</div>

气泡卡片弹出位置

popup 气泡卡片模式下提供 16 种弹出位置,可选值有 top, topLeft, topRight, left, leftTop, leftBottom, right, rightTop, rightBottom, bottom, bottomLeft, bottomRight, leftTopOver, rightTopOver, leftBottomOver, rightBottomOver,还可以通过 showArrow 属性设置是否显示箭头。

代码
<script lang="ts">
    import { Button, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const target = () => document.querySelector('#position-demo');
    const steps: UserGuideStepItem[] = [
        { target, title: '新手引导', description: 'Hello ByteDancer!', position: 'top' },
        { target, title: 'New Position', description: 'This is Right Position', position: 'right' },
        { target, title: 'Hide Arrow', description: 'We hide the arrow', position: 'bottom', showArrow: false },
    ];
</script>

<div>
    <Button id="position-demo" onclick={() => (visible = true)}>开始引导</Button>
    <UserGuide bind:visible mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} {steps} />
</div>

设置高亮区域大小

通过 spotlightPadding 属性设置。



Default Tag
代码
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#padding-demo-1'),
            title: '新手引导',
            description: 'Hello ByteDancer!',
        },
        {
            target: () => document.querySelector('#padding-demo-2'),
            title: 'New Padding',
            description: 'This is 10px padding',
        },
        {
            target: () => document.querySelector('#padding-demo-3'),
            title: 'Change Padding',
            spotlightPadding: 15,
            description: 'We change the Padding to 15px',
        },
    ];
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="padding-demo-1" />
        <Tag id="padding-demo-2">Default Tag</Tag>
        <Button id="padding-demo-3">确定</Button>
    </Space>
    <UserGuide bind:visible mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} spotlightPadding={10} {steps} />
</div>

定制按钮

通过 nextButtonProps 和 prevButtonProps 属性设置按钮的样式。

按钮文本使用 nextText、prevText snippet;最后一步的按钮文本由 finishText 决定。



Default Tag
代码
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#button-demo-1'),
            title: '新手引导',
            description: 'Hello ByteDancer!',
        },
        {
            target: () => document.querySelector('#button-demo-2'),
            title: 'New Button Style',
            description: 'Button text is Next',
        },
        {
            target: () => document.querySelector('#button-demo-3'),
            title: 'New finish button text',
            description: 'Button text is I know',
        },
    ];
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="button-demo-1" />
        <Tag id="button-demo-2">Default Tag</Tag>
        <Button id="button-demo-3">确定</Button>
    </Space>
    <UserGuide bind:visible finishText="我知道啦!" mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} prevButtonProps={{ theme: 'borderless' }} {steps}>
        {#snippet nextText()}Next{/snippet}
        {#snippet prevText()}Prev{/snippet}
    </UserGuide>
</div>

受控

通过 current 属性设置当前引导步骤。

用 bind:current 绑定当前步骤,bind:visible 绑定显示状态。



Default Tag
代码
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    let current = $state(0);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#controlled-demo-1'),
            title: '新手引导',
            description: 'Hello ByteDancer!',
            position: 'bottom',
        },
        {
            target: () => document.querySelector('#controlled-demo-2'),
            title: 'Switch',
            description: 'This is a Semi Switch',
            position: 'bottom',
        },
        {
            target: () => document.querySelector('#controlled-demo-3'),
            title: 'Button',
            description: 'This is a Semi Button',
            position: 'bottom',
        },
    ];

    const finish = (message: string) => {
        current = 0;
        console.log(message);
    };
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="controlled-demo-1" />
        <Tag id="controlled-demo-2">Default Tag</Tag>
        <Button id="controlled-demo-3">确定</Button>
    </Space>
    <UserGuide bind:current bind:visible mask mode="popup" onFinish={() => finish('引导完成')} onSkip={() => finish('跳过引导')} {steps} />
</div>

弹窗式引导

通过 mode 属性设置为 modal 开启弹窗式引导。

封面使用步骤数据里的 cover snippet,富文本描述把 description 写成 snippet,参数为 { item, index }。

代码
<script lang="ts">
    import { Button, Image, TypographyText, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const covers = ['/assets/root-web-sites/sky.jpg', '/assets/root-web-sites/greenleaf.jpg', '/assets/root-web-sites/colorful.jpg'];
</script>

{#snippet welcome()}
    <div>你可以从已发布的主题出发,或者选择<TypographyText strong>立即创造</TypographyText>来创造一个新的主题</div>
{/snippet}

{#snippet cover({ index }: { index: number })}
    <Image height="100%" src={covers[index]} width="600px" />
{/snippet}

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <UserGuide
        bind:visible
        mask
        mode="modal"
        onChange={(current) => console.log('当前引导步骤', current)}
        onFinish={() => console.log('引导完成')}
        onNext={() => console.log('下一步引导')}
        onPrev={() => console.log('上一步引导')}
        onSkip={() => console.log('跳过引导')}
        steps={[
            { title: '欢迎使用 Semi DSM!', description: welcome, cover, position: 'bottom' },
            { title: '高可用的色盘', description: '选取主色后,我们的颜色算法会为你生成一套高可用的色盘', cover, position: 'bottom' },
            { title: '自由定制', description: '开始定制属于你的设计系统吧!', cover, position: 'bottom' },
        ] satisfies UserGuideStepItem[]}
    />
</div>

无遮罩

通过 mask 属性设置为 false 开启无遮罩引导。

代码
<script lang="ts">
    import { Button, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#mask-demo'),
            title: 'No Mask',
            description: 'Hello ByteDancer!',
        },
    ];
</script>

<div>
    <Button id="mask-demo" onclick={() => (visible = true)}>开始引导</Button>
    <UserGuide bind:visible mask={false} mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} {steps} />
</div>

API 参考


Props

属性说明类型默认值
classpopup 模式落在气泡卡片上,modal 模式落在 Modal 的最外层元素上。string-
current当前步骤的索引,可用 bind:current 双向绑定;不传时由组件自己保存,从 0 开始。number-
finishText最后一步完成按钮的文本;为空时使用语言包中的文案。string-
getPopupContainermodal 模式下弹窗渲染至该 DOM 中;popup 模式下指向 body 以外的元素时不锁定 body 滚动。气泡卡片位于 top layer,不受此属性影响。Type() => HTMLElement-
mask是否显示蒙层,可被步骤的 mask 覆盖。booleantrue
mode引导模式:popup 为气泡卡片,modal 为弹窗。'popup' | 'modal'"popup"
nextButtonProps下一步按钮的属性,onclick 先于内置处理调用,按钮文本使用 nextText snippet。UserGuideButtonProps-
nextText下一步按钮文本的 snippet,最后一步显示 finishText;不提供时使用语言包中的文案。Snippet-
onChange步骤改变时调用,参数为新的索引,晚于 current 的写回。Type(current: number) => void-
onFinish点击最后一步的完成按钮时调用,晚于 visible 的写回。Type() => void-
onNext点击下一步按钮时调用,参数为新的索引;最后一步调用 onFinish。Type(current: number) => void-
onPrev点击上一步按钮时调用,参数为新的索引。Type(current: number) => void-
onSkip点击跳过按钮或按 Esc 时调用,晚于 visible 的写回。Type() => void-
position气泡卡片相对于目标元素的位置,可被步骤的 position 覆盖。Position"bottom"
prevButtonProps上一步按钮的属性,onclick 先于内置处理调用,按钮文本使用 prevText snippet。UserGuideButtonProps-
prevText上一步按钮文本的 snippet;不提供时使用语言包中的文案。Snippet-
showPrevButton是否显示上一步按钮,第一步不显示。booleantrue
showSkipButton是否显示跳过按钮,最后一步不显示。booleantrue
spotlightPadding高亮区域的外扩距离,单位为像素,可被步骤的 spotlightPadding 覆盖;都未设置时为 5。number-
steps引导步骤的数据;标题、描述可以是字符串或 snippet,封面是 snippet,snippet 的参数为 { item, index }。UserGuideStepItem[][]
style样式字符串;popup 模式落在气泡卡片上,modal 模式落在 .semi-modal 上。string-
themepopup 模式的主题,可被步骤的 theme 覆盖。'default' | 'primary'"default"
visible是否显示引导,可用 bind:visible 双向绑定;跳过、Esc 与完成会把它写回 false。boolean-
zIndexpopup 模式下遮罩的层级,modal 模式下弹窗的层级。气泡卡片位于 top layer,始终在遮罩之上。number1030

UserGuide 没有根元素:popup 模式下 class、style 落在气泡卡片上;modal 模式下 class 落在 Modal 的最外层元素上,style 落在 .semi-modal 上。未声明的属性(包括 aria-* 与原生事件)会被丢弃。对话框的可访问名称只来自当前步骤的 title。

StepItem

steps 的每一项(类型 UserGuideStepItem)只放数据,title、description 可以是字符串或 snippet,cover 是 snippet,snippet 的参数为 { item, index }(类型 UserGuideStepSnippetProps)。

属性说明类型默认值
class步骤的自定义类名string-
cover步骤的封面;不提供时该步骤没有封面区Snippet<[UserGuideStepSnippetProps]>-
target目标元素,高亮区域会聚焦到这个元素上;函数形式在测量步骤时调用,目标尚未出现时可返回 null 或 undefinedElement | (() => Element | null | undefined)-
title步骤标题,字符串或 snippetstring | Snippet<[UserGuideStepSnippetProps]>-
description步骤描述,字符串或 snippetstring | Snippet<[UserGuideStepSnippetProps]>-
mask是否显示此步骤的蒙层,会覆盖全局配置boolean-
showArrow是否显示箭头(仅在 mode=popup 时有效)booleantrue
spotlightPadding此步骤高亮区域的内边距,会覆盖全局配置number-
theme此步骤的主题,会覆盖全局配置default | primary-
position此步骤弹出层的位置,会覆盖全局配置Position-

Accessibility

  • 每一步是以步骤 title 命名的对话框,按 Esc 等同点击「跳过」。
  • 两种模式下每一步出现时,焦点都移到主按钮(「下一步」或「完成」)上。popup 模式下 Tab 在卡片内循环,引导关闭时焦点回到打开前的元素;modal 模式的焦点循环与归还由 Modal 管理。

设计变量

下表是组件内部的 Sass 变量,不能覆写。定制样式请覆写 --semi-* CSS 变量(见 Design Token 页),或写不分层的 CSS 规则。
Sass 变量值用法
$transition_duration-userGuide_spotLight200msspotLight 动画持续时间
$transition_function-userGuide_spotLightcubic-bezier(0.4, 0, 0.2, 1)spotLight 过渡曲线
$color-userGuide_popup-text-defaultvar(--semi-color-text-0)气泡卡片文字颜色 - 默认
$color-userGuide_popup-text-primaryvar(--semi-color-tertiary-light-default)气泡卡片文字颜色 - primary
$color-userGuide_modal_content_indicator-bgvar(--semi-color-primary-light-active)弹窗指示器背景颜色
$color-userGuide_modal_content_indicator-bg-activevar(--semi-color-primary)弹窗指示器背景颜色 - 选中态
$width-userGuide_popover-default400px默认气泡卡片宽度
$height-userGuide_popup_content_cover-default200px默认气泡卡片封面高度
$width-userGuide_modal_content_cover-default600px默认弹窗式卡片封面宽度
$height-userGuide_modal_content_cover-default300px默认弹窗式卡片封面高度
$height-userGuide_modal_content_indicator-default30px默认弹窗式卡片指示器整体高度
$width-userGuide_modal_content_indicator_item-default6px默认弹窗式卡片单个指示器宽度
$height-userGuide_modal_content_indicator_item-default6px默认弹窗式卡片单个指示器高度
$font-userGuide_popup_content_title-lineHeight24px气泡卡片标题行高
$font-userGuide_popup_content_description-lineHeight20px气泡卡片详情行高
$font-userGuide_popup_content_indicator-lineHeight20px气泡卡片指示器行高
$font-userGuide_modal_content_title-lineHeight24px弹窗式卡片标题行高
$font-userGuide_modal_content_description-lineHeight20px弹窗式卡片详情行高
$spacing-userGuide_popup_content_body-padding24px气泡卡片内边距
$spacing-userGuide_popup_content_title-marginBottom8px气泡卡片标题底部外边距
$spacing-userGuide_popup_content_description-marginBottom48px气泡卡片详情底部外边距
$spacing-userGuide_popup_content_button-gap12px气泡卡片底部按钮间距
$spacing-userGuide_popup_content_button-marginLeft120px气泡卡片按钮组左边距
$spacing-userGuide_modal_content_title-marginBottom8px弹窗式卡片标题底部外边距
$spacing-userGuide_modal_content_body-padding24px 48px弹窗式卡片body内边距
$spacing-userGuide_modal_content_footer-padding24px弹窗式卡片footer内边距
$spacing-userGuide_popup_content_indicator-gap8px弹窗式片指示器间距
$spacing-userGuide_modal_content_button-gap12px弹窗式卡片底部按钮间距
$radius-userGuide_popup_content_covervar(--semi-border-radius-medium) var(--semi-border-radius-medium) 0 0气泡卡片封面圆角
$radius-userGuide_modal_content_indicatorvar(--semi-border-radius-large)气泡卡片指示器圆角
$font-userGuide_popup_content_title-fontSize$font-size-header-5气泡卡片标题字体大小
$font-userGuide_popup_content_description-fontSize$font-size-regular气泡卡片详情字体大小
$font-userGuide_popup_content_title-fontWeight$font-weight-bold气泡卡片标题字重
$font-userGuide_modal_content_title-fontSize$font-size-header-5弹窗式卡片标题字体大小
$font-userGuide_modal_content_description-fontSize$font-size-regular弹窗式卡详情字体大小
$font-userGuide_modal_content_title-fontWeight$font-weight-bold弹窗式卡片标题字重