用户引导 - Semi Design Next

代码演示

如何引入

import { UserGuide } from '@fibrous/semi-ui-react';

基本用法

Default Tag

代码

import { useState } from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@fibrous/semi-ui-react';

export default function UserGuideDemo() {
    const [visible, setVisible] = useState(false);
    const showDialog = () => {
        setVisible(true);
    };
    return (
        <div>
            <Button onClick={showDialog}>开始引导</Button>
            <br />
            <br />
            <Space>
                <Switch aria-label="示例开关" id="basic-demo-1" defaultChecked />
                <Tag id="basic-demo-2"> Default Tag </Tag>
                <Button id="basic-demo-3">确定</Button>
            </Space>
            <UserGuide
                mode="popup"
                mask
                visible={visible}
                steps={[
                    {
                        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',
                    },
                ]}
                onChange={(current) => {
                    console.log('当前引导步骤', current);
                }}
                onNext={() => {
                    console.log('下一步引导');
                }}
                onPrev={() => {
                    console.log('上一步引导');
                }}
                onFinish={() => {
                    setVisible(false);
                    console.log('引导完成');
                }}
                onSkip={() => {
                    setVisible(false);
                    console.log('跳过引导');
                }}
            />
        </div>
    );
}

主题

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

Default Tag

代码

import { useState } from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@fibrous/semi-ui-react';

export default function UserGuideDemo() {
    const [visible, setVisible] = useState(false);
    const showDialog = () => {
        setVisible(true);
    };
    return (
        <div>
            <Button onClick={showDialog}>开始引导</Button>
            <br />
            <br />
            <Space>
                <Switch aria-label="示例开关" id="theme-demo-1" defaultChecked />
                <Tag id="theme-demo-2"> Default Tag </Tag>
                <Button id="theme-demo-3">确定</Button>
            </Space>
            <UserGuide
                mode="popup"
                mask
                visible={visible}
                theme="primary"
                steps={[
                    {
                        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',
                    },
                ]}
                onFinish={() => {
                    setVisible(false);
                    console.log('引导完成');
                }}
                onSkip={() => {
                    setVisible(false);
                    console.log('跳过引导');
                }}
            />
        </div>
    );
}

气泡卡片弹出位置

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

代码

import { useState } from 'react';
import { UserGuide, Button } from '@fibrous/semi-ui-react';

export default function UserGuideDemo() {
    const [visible, setVisible] = useState(false);
    const showDialog = () => {
        setVisible(true);
    };
    return (
        <div>
            <Button id="position-demo" onClick={showDialog}>
                开始引导
            </Button>
            <UserGuide
                mode="popup"
                mask
                visible={visible}
                steps={[
                    {
                        target: () => document.querySelector('#position-demo'),
                        title: '新手引导',
                        description: 'Hello ByteDancer!',
                        position: 'top',
                    },
                    {
                        target: () => document.querySelector('#position-demo'),
                        title: 'New Position',
                        description: 'This is Right Position',
                        position: 'right',
                    },
                    {
                        target: () => document.querySelector('#position-demo'),
                        title: 'Hide Arrow',
                        description: 'We hide the arrow',
                        position: 'bottom',
                        showArrow: false,
                    },
                ]}
                onFinish={() => {
                    setVisible(false);
                    console.log('引导完成');
                }}
                onSkip={() => {
                    setVisible(false);
                    console.log('跳过引导');
                }}
            />
        </div>
    );
}

设置高亮区域大小

通过 spotlightPadding 属性设置。

Default Tag

代码

import { useState } from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@fibrous/semi-ui-react';

export default function UserGuideDemo() {
    const [visible, setVisible] = useState(false);
    const showDialog = () => {
        setVisible(true);
    };
    return (
        <div>
            <Button onClick={showDialog}>开始引导</Button>
            <br />
            <br />
            <Space>
                <Switch aria-label="示例开关" id="padding-demo-1" defaultChecked />
                <Tag id="padding-demo-2"> Default Tag </Tag>
                <Button id="padding-demo-3">确定</Button>
            </Space>
            <UserGuide
                mode="popup"
                mask
                visible={visible}
                spotlightPadding={10}
                steps={[
                    {
                        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',
                    },
                ]}
                onFinish={() => {
                    setVisible(false);
                    console.log('引导完成');
                }}
                onSkip={() => {
                    setVisible(false);
                    console.log('跳过引导');
                }}
            />
        </div>
    );
}

定制按钮

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

Default Tag

代码

import { useState } from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@fibrous/semi-ui-react';

export default function UserGuideDemo() {
    const [visible, setVisible] = useState(false);
    const showDialog = () => {
        setVisible(true);
    };
    return (
        <div>
            <Button onClick={showDialog}>开始引导</Button>
            <br />
            <br />
            <Space>
                <Switch aria-label="示例开关" id="button-demo-1" defaultChecked />
                <Tag id="button-demo-2"> Default Tag </Tag>
                <Button id="button-demo-3">确定</Button>
            </Space>
            <UserGuide
                mode="popup"
                mask
                visible={visible}
                nextButtonProps={{
                    children: 'Next',
                }}
                prevButtonProps={{
                    children: 'Prev',
                    theme: 'borderless',
                }}
                finishText="我知道啦！"
                steps={[
                    {
                        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',
                    },
                ]}
                onFinish={() => {
                    setVisible(false);
                    console.log('引导完成');
                }}
                onSkip={() => {
                    setVisible(false);
                    console.log('跳过引导');
                }}
            />
        </div>
    );
}

受控

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

Default Tag

代码

import { useState } from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@fibrous/semi-ui-react';

export default function UserGuideDemo() {
    const [visible, setVisible] = useState(false);
    const [current, setCurrent] = useState(0);

    const showDialog = () => {
        setVisible(true);
    };
    return (
        <div>
            <Button onClick={showDialog}>开始引导</Button>
            <br />
            <br />
            <Space>
                <Switch aria-label="示例开关" id="controlled-demo-1" defaultChecked />
                <Tag id="controlled-demo-2"> Default Tag </Tag>
                <Button id="controlled-demo-3">确定</Button>
            </Space>
            <UserGuide
                mode="popup"
                mask
                visible={visible}
                current={current}
                steps={[
                    {
                        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',
                    },
                ]}
                onChange={(current) => {
                    setCurrent(current);
                }}
                onFinish={() => {
                    setVisible(false);
                    setCurrent(0);
                    console.log('引导完成');
                }}
                onSkip={() => {
                    setVisible(false);
                    setCurrent(0);
                    console.log('跳过引导');
                }}
            />
        </div>
    );
}

弹窗式引导

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

代码

import { useState } from 'react';
import { UserGuide, Button, Image, Typography } from '@fibrous/semi-ui-react';

export default function UserGuideDemo() {
    const [visible, setVisible] = useState(false);
    const showDialog = () => {
        setVisible(true);
    };
    return (
        <div>
            <Button onClick={showDialog}>开始引导</Button>
            <UserGuide
                mode="modal"
                mask
                visible={visible}
                steps={[
                    {
                        title: '欢迎使用 Semi DSM!',
                        description: (
                            <div>
                                你可以从已发布的主题出发，或者选择<Typography.Text strong>立即创造</Typography.Text>
                                来创造一个新的主题
                            </div>
                        ),
                        cover: <Image width="600px" height="100%" src="/assets/root-web-sites/sky.jpg" />,
                        position: 'bottom',
                    },
                    {
                        title: '高可用的色盘',
                        description: '选取主色后，我们的颜色算法会为你生成一套高可用的色盘',
                        cover: <Image width="600px" height="100%" src="/assets/root-web-sites/greenleaf.jpg" />,
                        position: 'bottom',
                    },
                    {
                        title: '自由定制',
                        description: '开始定制属于你的设计系统吧！',
                        cover: <Image width="600px" height="100%" src="/assets/root-web-sites/colorful.jpg" />,
                        position: 'bottom',
                    },
                ]}
                onChange={(current) => {
                    console.log('当前引导步骤', current);
                }}
                onNext={() => {
                    console.log('下一步引导');
                }}
                onPrev={() => {
                    console.log('上一步引导');
                }}
                onFinish={() => {
                    setVisible(false);
                    console.log('引导完成');
                }}
                onSkip={() => {
                    setVisible(false);
                    console.log('跳过引导');
                }}
            />
        </div>
    );
}

无遮罩

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

代码

import { useState } from 'react';
import { UserGuide, Button } from '@fibrous/semi-ui-react';

export default function UserGuideDemo() {
    const [visible, setVisible] = useState(false);
    const showDialog = () => {
        setVisible(true);
    };
    return (
        <div>
            <Button id="mask-demo" onClick={showDialog}>
                开始引导
            </Button>
            <UserGuide
                mode="popup"
                mask={false}
                visible={visible}
                steps={[
                    {
                        target: () => document.querySelector('#mask-demo'),
                        title: 'No Mask',
                        description: 'Hello ByteDancer!',
                    },
                ]}
                onFinish={() => {
                    setVisible(false);
                    console.log('引导完成');
                }}
                onSkip={() => {
                    setVisible(false);
                    console.log('跳过引导');
                }}
            />
        </div>
    );
}

API 参考

Props

属性	说明	类型	默认值
children	组件不渲染 children，传入的内容会被忽略。	`ReactNode`	-
className	自定义类名。popup 模式下落在气泡卡片上，modal 模式下落在弹窗的外层元素上。	`string`	-
current	当前步骤的索引，从 0 开始。设置后由外部控制，配合 onChange 回写；不设置时从第 0 步开始，由组件自己保存步骤。	`number`	-
finishText	最后一步完成按钮的文本；未设置时使用语言包中的文案。	`string`	-
getPopupContainer	modal 模式下弹窗渲染至该 DOM 中；popup 模式下指向 body 以外的元素时不锁定 body 滚动。气泡卡片位于 top layer，不受此属性影响。	`Type`	-
mask	是否显示蒙层，可被步骤的 mask 覆盖。	`boolean`	`true`
mode	引导模式：popup 为气泡卡片，modal 为弹窗。	`'popup' \| 'modal'`	`"popup"`
nextButtonProps	下一步按钮的属性，可含 className、style 与 onClick；onClick 先于内置处理调用。按钮文本使用 children，最后一步的文本由 finishText 决定。	`ButtonProps`	`{}`
onChange	上一步或下一步改变步骤时的回调，参数为新的索引；点击完成或跳过时不调用。	`Type`	-
onFinish	点击最后一步的完成按钮时的回调。	`Type`	-
onNext	点击下一步按钮时的回调，参数为新的索引；最后一步不触发，由 onFinish 处理。	`Type`	-
onPrev	点击上一步按钮时的回调，参数为新的索引。	`Type`	-
onSkip	点击跳过按钮或按 Esc 时的回调。	`Type`	-
position	气泡卡片相对于目标元素的位置，可被步骤的 position 覆盖。可选值：`top`、`topLeft`、`topRight`、`left`、`leftTop`、`leftBottom`、`right`、`rightTop`、`rightBottom`、`bottom`、`bottomLeft`、`bottomRight`、`leftTopOver`、`rightTopOver`、`leftBottomOver`、`rightBottomOver`。	`Position`	`"bottom"`
prevButtonProps	上一步按钮的属性，可含 className、style 与 onClick；onClick 先于内置处理调用。按钮文本使用 children。	`ButtonProps`	`{}`
showPrevButton	是否显示上一步按钮，第一步不显示。	`boolean`	`true`
showSkipButton	是否显示跳过按钮，最后一步不显示。	`boolean`	`true`
spotlightPadding	高亮区域的外扩距离，单位为像素，可被步骤的 spotlightPadding 覆盖；都未设置时为 5。	`number`	-
steps	引导步骤的数据，必填。每一步的 title、description 与 cover 可以是 ReactNode。	`StepItem[]`	-
style	自定义样式。popup 模式下落在气泡卡片上，modal 模式下落在 .semi-modal 上。	`React.CSSProperties`	-
theme	popup 模式的主题，可被步骤的 theme 覆盖。	`'default' \| 'primary'`	`"default"`
visible	是否显示引导。	`boolean`	`false`
zIndex	popup 模式下遮罩的层级，modal 模式下弹窗的层级。气泡卡片位于 top layer，始终在遮罩之上。	`number`	`1030`

UserGuide 没有根元素：popup 模式下 className、style 落在气泡卡片上；modal 模式下 className、style 交给 Modal，落点与 Modal 一致。未声明的属性（包括 aria-* 与原生事件）会被丢弃。对话框的可访问名称只来自当前步骤的 title。

StepItem

属性	说明	类型	默认值
className	步骤的自定义类名	string	-
cover	步骤的封面图	ReactNode	-
target	目标元素，高亮区域会聚焦到这个元素上	(() => Element \| null \| undefined) \| Element \| null	-
title	步骤标题	string \| ReactNode	-
description	步骤描述	ReactNode	-
mask	是否显示此步骤的蒙层，会覆盖全局配置	boolean	-
showArrow	是否显示箭头（仅在 mode=`popup` 时有效）	boolean	true
spotlightPadding	此步骤高亮区域的内边距，会覆盖全局配置	number	-
theme	此步骤的主题，会覆盖全局配置	`default` \| `primary`	-
position	此步骤弹出层的位置，会覆盖全局配置	Position	-

Accessibility

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

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$transition_duration-userGuide_spotLight	200ms	spotLight 动画持续时间
$transition_function-userGuide_spotLight	cubic-bezier(0.4, 0, 0.2, 1)	spotLight 过渡曲线
$color-userGuide_popup-text-default	var(--semi-color-text-0)	气泡卡片文字颜色 - 默认
$color-userGuide_popup-text-primary	var(--semi-color-tertiary-light-default)	气泡卡片文字颜色 - primary
$color-userGuide_modal_content_indicator-bg	var(--semi-color-primary-light-active)	弹窗指示器背景颜色
$color-userGuide_modal_content_indicator-bg-active	var(--semi-color-primary)	弹窗指示器背景颜色 - 选中态
$width-userGuide_popover-default	400px	默认气泡卡片宽度
$height-userGuide_popup_content_cover-default	200px	默认气泡卡片封面高度
$width-userGuide_modal_content_cover-default	600px	默认弹窗式卡片封面宽度
$height-userGuide_modal_content_cover-default	300px	默认弹窗式卡片封面高度
$height-userGuide_modal_content_indicator-default	30px	默认弹窗式卡片指示器整体高度
$width-userGuide_modal_content_indicator_item-default	6px	默认弹窗式卡片单个指示器宽度
$height-userGuide_modal_content_indicator_item-default	6px	默认弹窗式卡片单个指示器高度
$font-userGuide_popup_content_title-lineHeight	24px	气泡卡片标题行高
$font-userGuide_popup_content_description-lineHeight	20px	气泡卡片详情行高
$font-userGuide_popup_content_indicator-lineHeight	20px	气泡卡片指示器行高
$font-userGuide_modal_content_title-lineHeight	24px	弹窗式卡片标题行高
$font-userGuide_modal_content_description-lineHeight	20px	弹窗式卡片详情行高
$spacing-userGuide_popup_content_body-padding	24px	气泡卡片内边距
$spacing-userGuide_popup_content_title-marginBottom	8px	气泡卡片标题底部外边距
$spacing-userGuide_popup_content_description-marginBottom	48px	气泡卡片详情底部外边距
$spacing-userGuide_popup_content_button-gap	12px	气泡卡片底部按钮间距
$spacing-userGuide_popup_content_button-marginLeft	120px	气泡卡片按钮组左边距
$spacing-userGuide_modal_content_title-marginBottom	8px	弹窗式卡片标题底部外边距
$spacing-userGuide_modal_content_body-padding	24px 48px	弹窗式卡片body内边距
$spacing-userGuide_modal_content_footer-padding	24px	弹窗式卡片footer内边距
$spacing-userGuide_popup_content_indicator-gap	8px	弹窗式片指示器间距
$spacing-userGuide_modal_content_button-gap	12px	弹窗式卡片底部按钮间距
$radius-userGuide_popup_content_cover	var(--semi-border-radius-medium) var(--semi-border-radius-medium) 0 0	气泡卡片封面圆角
$radius-userGuide_modal_content_indicator	var(--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	弹窗式卡片标题字重