通知 - Semi Design Next

代码演示

如何引入

import { Notification } from '@fibrous/semi-ui-solid';

静态方法在组件树之外渲染，读取 Notification.config() 与全局默认值以及默认语言包，不继承所在位置的 ConfigProvider 与 LocaleProvider；需要读取时改用 Notification.useNotification()。

普通通知

最基本的用法，3s 后自动关闭

代码

import { Button, Notification } from '@fibrous/semi-ui-solid';

export default function NotificationDemo() {
    return (
        <Button
            onClick={() =>
                Notification.open({
                    title: 'Hi, Bytedance',
                    content: 'ies dance dance dance',
                    duration: 3,
                })
            }
        >
            Display Notification
        </Button>
    );
}

不同位置弹出

可以从多个不同位置弹出：默认右上角 topRight。可选值：top、bottom、topLeft、topRight、bottomLeft、bottomRight。

代码

import { Button, ButtonGroup, Notification } from '@fibrous/semi-ui-solid';

const opts = {
    duration: 3,
    position: 'topRight',
    content: 'semi-ui-notification',
    title: 'Hi bytedance',
} as const;

export default function NotificationDemo() {
    return (
        <>
            <ButtonGroup>
                <Button onClick={() => Notification.info({ ...opts, position: 'top' })}>top</Button>
                <Button onClick={() => Notification.info({ ...opts, position: 'topLeft' })}>topLeft</Button>
                <Button onClick={() => Notification.info(opts)}>topRight</Button>
            </ButtonGroup>
            <br />
            <br />
            <ButtonGroup>
                <Button onClick={() => Notification.info({ ...opts, position: 'bottom' })}>bottom</Button>
                <Button onClick={() => Notification.info({ ...opts, position: 'bottomRight' })}>bottomRight</Button>
                <Button onClick={() => Notification.info({ ...opts, position: 'bottomLeft' })}>bottomLeft</Button>
            </ButtonGroup>
        </>
    );
}

带有图标的通知

包括成功、失败、警告、提示

默认的图标

自定义图标

代码

import { IconToutiaoLogo, IconVigoLogo } from '@fibrous/semi-icons-solid';
import { Button, Notification } from '@fibrous/semi-ui-solid';

const opts = {
    title: 'Hi, Bytedance',
    content: 'ies dance dance dance',
    duration: 3,
};

export default function NotificationDemo() {
    return (
        <>
            <h5>默认的图标</h5>
            <Button type="primary" onClick={() => Notification.success(opts)} style={{ margin: '4px' }}>
                Success
            </Button>
            <Button onClick={() => Notification.info(opts)} style={{ margin: '4px' }}>
                Info
            </Button>
            <Button type="warning" onClick={() => Notification.warning(opts)} style={{ margin: '4px' }}>
                Warning
            </Button>
            <Button type="danger" onClick={() => Notification.error(opts)} style={{ margin: '4px' }}>
                Error
            </Button>
            <h5>自定义图标</h5>
            <Button
                aria-label="Toutiao 图标通知"
                icon={<IconToutiaoLogo />}
                style={{ 'margin-right': '5px' }}
                onClick={() =>
                    Notification.info({
                        ...opts,
                        icon: <IconToutiaoLogo style={{ color: 'red' }} />,
                    })
                }
            />
            <Button aria-label="Vigo 图标通知" icon={<IconVigoLogo />} style={{ 'margin-right': '5px' }} onClick={() => Notification.info({ ...opts, icon: <IconVigoLogo /> })} />
            <Button aria-label="粉色 Vigo 图标通知" icon={<IconVigoLogo />} onClick={() => Notification.info({ ...opts, icon: <IconVigoLogo style={{ color: 'pink' }} /> })} />
        </>
    );
}

多色样式

可以使用 theme 设置浅色填充样式提高与界面的对比，默认为 'normal' 的白色模式。

代码

import { Button, Notification } from '@fibrous/semi-ui-solid';

const opts = {
    title: 'Hi, Bytedance',
    content: 'Hi, Bytedance dance dance',
    duration: 3,
    theme: 'light',
} as const;

export default function NotificationDemo() {
    return (
        <>
            <Button onClick={() => Notification.info(opts)}>Info</Button>
            <br />
            <br />
            <Button onClick={() => Notification.success(opts)}>Success</Button>
            <br />
            <br />
            <Button type="warning" onClick={() => Notification.warning(opts)}>
                Warning
            </Button>
            <br />
            <br />
            <Button type="danger" onClick={() => Notification.error(opts)}>
                Error
            </Button>
        </>
    );
}

链接文本

配合 Typography 可以自定义操作区链接文本，用来配合更复杂的场景的使用。

title、content、icon 接受 JSX 元素，或返回 JSX 的函数；示例中的内容在点击时用 JSX 构造，每次弹出都是新节点。

代码

import { Button, Notification, Typography } from '@fibrous/semi-ui-solid';

const { Text } = Typography;

export default function NotificationDemo() {
    // content is JSX built inside the handler: a static notification renders it once, so each click needs a new node
    return (
        <Button
            onClick={() =>
                Notification.info({
                    title: 'This is a title',
                    content: (
                        <>
                            <div>Hi, Bytedance dance dance</div>
                            <div style={{ 'margin-top': '8px' }}>
                                <Text link>查看详情</Text>
                                <Text link style={{ 'margin-left': '20px' }}>
                                    一会再看
                                </Text>
                            </div>
                        </>
                    ),
                    duration: 3,
                })
            }
        >
            Display Notification
        </Button>
    );
}

修改延时

自定义时长 10s，默认时长为 3s

代码

import { Button, Notification } from '@fibrous/semi-ui-solid';

const opts = {
    content: 'Hi, Bytedance dance dance',
    duration: 10,
};

export default function NotificationDemo() {
    return <Button onClick={() => Notification.info(opts)}>Close After 10s</Button>;
}

手动关闭

设置 duration 为 0 时，通知将不会自动关闭，此时只能手动关闭。

代码

import { createSignal } from 'solid-js';
import { Button, Notification } from '@fibrous/semi-ui-solid';

const opts = {
    content: 'Not auto close',
    title: 'Hi',
    duration: 0,
};

export default function NotificationDemo() {
    const [ids, setIds] = createSignal<string[]>([]);

    function show() {
        const id = Notification.info(opts);
        setIds([...ids(), id]);
    }

    function hide() {
        const [first, ...rest] = ids();
        if (first) {
            Notification.close(first);
        }
        setIds(rest);
    }

    return (
        <>
            <Button type="primary" onClick={show}>
                Show Notification
            </Button>
            <br />
            <br />
            <Button type="primary" onClick={hide}>
                Hide Notification
            </Button>
        </>
    );
}

堆叠样式

设置 stack 后，同一位置的通知超过阈值时堆叠展示，悬停展开。true 的阈值为 3，传数字可自定义阈值；堆叠时只显示最前面的 3 层。

代码

import { Button, Notification } from '@fibrous/semi-ui-solid';

export default function NotificationDemo() {
    return (
        <Button
            onClick={() => {
                Notification.info({ title: 'Hi', content: 'Hi, Bytedance dance dance', duration: 10, stack: true });
            }}
        >
            Click multiple times
        </Button>
    );
}

更新内容

可以通过唯一的 id 来更新内容。

代码

import { Button, Notification } from '@fibrous/semi-ui-solid';

export default function NotificationDemo() {
    return (
        <Button
            onClick={() => {
                const id = Notification.open({
                    title: 'Hi, Bytedance',
                    content: 'ies dance dance dance',
                    duration: 3,
                });
                setTimeout(() => {
                    Notification.open({
                        title: 'Hi, Bytedance',
                        content: 'updated',
                        duration: 10,
                        id,
                    });
                }, 1000);
            }}
        >
            Display Notification
        </Button>
    );
}

消费 Context

通过 Notification.useNotification() 创建 contextHolder，并把它放在需要继承上下文的位置。hook 须在该位置的 Provider 之下调用：通知渲染在 contextHolder 所在的节点处，继承那里的 context、ConfigProvider 和语言，进场、离场动画与静态方法相同。content、icon、title 传函数时，函数在通知内部渲染，可以读取该位置的 context；事件处理函数中创建的 JSX 没有所属组件，读不到 context。

代码

import { createContext, createSignal, useContext } from 'solid-js';
import { Button, Notification, Space } from '@fibrous/semi-ui-solid';

const ReachableContext = createContext<string>();

// The holder must be created under the Provider: its notifications read the context around it
function HookDemo() {
    const [notification, contextHolder] = Notification.useNotification();
    const [ids, setIds] = createSignal<string[]>([]);

    function show() {
        const id = notification.info({
            title: 'Hook Notification',
            // A function is called where the notice renders, so it reads the context around contextHolder
            content: () => `ReachableContext: ${useContext(ReachableContext)}`,
            duration: 0,
        });
        setIds([...ids(), id]);
    }

    function hide() {
        const [first, ...rest] = ids();
        if (first) {
            notification.close(first);
        }
        setIds(rest);
    }

    return (
        <>
            <Space>
                <Button onClick={show}>Show Notification</Button>
                <Button onClick={hide}>Hide Notification</Button>
            </Space>
            {contextHolder}
        </>
    );
}

export default function NotificationDemo() {
    return (
        <ReachableContext.Provider value="Light">
            <HookDemo />
        </ReachableContext.Provider>
    );
}

API 参考

组件提供的静态方法，使用方式如下：

展示：可以直接传入 options 对象，返回值为id：const id = Notification.open({ /*...options*/ })

Notification.open({content: 'message', duration: 3})
Notification.info({content: 'message', duration: 3})
Notification.error({content: 'message', duration: 3})
Notification.warning({content: 'message', duration: 3})
Notification.success({content: 'message', duration: 3})

手动关闭（id 为展示方法的返回值）

Notification.close(id)

属性	说明	类型	默认值
class	通知元素的类名	string
content	通知内容；函数在通知内部渲染，可以读取该位置的 context	JSX.Element \| (() => JSX.Element)	''
direction	文字方向，只作为单条通知的选项，不属于全局配置；不传时跟随 ConfigProvider	`ltr` \| `rtl`
duration	自动关闭的延时，单位 s，设为 0 时不自动关闭	number	3
getPopupContainer	指定父级 DOM，弹层将会渲染至该 DOM 中，自定义需要设置 `position: relative`。这会改变浮层 DOM 树位置，但不会改变视图渲染位置。只在首次创建容器时生效。	() => HTMLElement	() => document.body
icon	左上角图标	JSX.Element \| (() => JSX.Element)
id	自定义通知 id；已有相同 id 的通知时更新其内容	string
position	弹出位置，可选 `top`、`bottom`、`topLeft`、`topRight`、`bottomLeft`、`bottomRight`	string	`topRight`
showClose	是否展示关闭按钮	boolean	true
stack	同一位置的通知超过多少条时堆叠展示，`true` 为 3，`false` 不堆叠；以该位置最新一条通知的设置为准	boolean \| number	false
style	通知元素的内联样式，对象的键为 CSS 属性名，或字符串	JSX.CSSProperties \| string
theme	填充样式，可选 `light`、`normal`	string	`normal`
title	通知标题；函数在通知内部渲染，可以读取该位置的 context	JSX.Element \| (() => JSX.Element)	''
zIndex	弹层 z-index 值，每次弹出时生效	number	1010
onClick	点击通知的回调函数，落在通知元素上	(e: MouseEvent) => void
onClose	通知关闭的回调函数，主动关闭、延时到达关闭都会触发，每次关闭只触发一次	() => void
onCloseClick	主动点击关闭按钮时的回调函数	(id: string) => void

class、style 与原生属性和事件（如 aria-*、data-*）落在通知的根 div 上。选项不接受 ref，通知元素由组件内部管理。回调保留 onClick、onClose、onCloseClick 的键名，直接传入函数。

全局配置在调用前提前配置，全局一次生效：

Notification.config(config)
Notification.resetConfig() 将全局配置恢复为默认值，只影响之后弹出的通知

Notification.config 不接受 direction，文字方向只能作为单条通知的选项。

属性	说明	类型	默认值
bottom	弹出位置 bottom	number \| string	-
duration	自动关闭的延时，单位 s，设为 0 时不自动关闭	number	3
left	弹出位置 left	number \| string	-
position	弹出位置，可选 `top`、`bottom`、`topLeft`、`topRight`、`bottomLeft`、`bottomRight`	string	`topRight`
right	弹出位置 right	number \| string	-
stack	同一位置的通知超过多少条时堆叠展示，`true` 为 3，`false` 不堆叠	boolean \| number	false
top	弹出位置 top	number \| string	-
zIndex	弹层 z-index 值	number	1010

全局销毁：

Notification.destroyAll()

Hook Notification：

Notification.useNotification()
返回元组 [notification, contextHolder]，把 contextHolder 放进相应的节点中，此时通过 hook 创建的通知将会得到 contextHolder 所在位置的所有上下文。notification 对象拥有以下方法：info、success、warning、error、open、close；前五个接收不含 type、id、zIndex、getPopupContainer 的选项，返回通知 id，close(id) 手动关闭。hook 创建的通知使用内置默认值与全局默认值，不受 Notification.config() 影响；close(id) 播放离场动画后移除通知，不触发 onClose。contextHolder 外包一层带 data-semi-keep-interactive 的容器，模态层打开时 hook 通知仍可交互。

Accessibility

ARIA

通知的 role 按类型区分：warning、error 为 alert，info、success 与 open 为 status
status 类通知由列表常驻的 aria-live="polite" 播报区朗读，通知自身为 aria-live="off"，只播报标题与内容的文本；warning、error 仍由 alert 自行播报
通知的 aria-labelledby 标记为对应通知标题

键盘和焦点

关闭按钮是原生 button，可以用 Tab 聚焦，Enter 或 Space 触发关闭
通知出现时不会抢走焦点
指针或键盘焦点进入通知时暂停自动关闭的计时，并展开堆叠；移出后恢复计时

文案规范

Task completed

400 tasks succeed and 600 failed

Check failed tasks

标题
- 使用简洁明了的语言进行说明
- 避免使用逗号，句号等标点符号
正文
- 在信息传递完整的前提下，尽可能地将正文压缩至 1 -2 句话
- 对标题进行详尽地描述或者解释，而不是对标题的重复说明
- 使用正确的标点符号，句子内使用逗号，句子间使用句号
操作
- 文案需要展示操作的具体含义

✅ 推荐用法	❌ 不推荐用法
Task completed 400 tasks succeed and 600 failed Check failed tasks	Status editing tasks completed 400 tasks succeed and 600 failed Check

设计变量

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

Sass 变量	值	用法
$animation_duration-notification-show	300ms	出现时-动画持续时间
$animation_function-notification-show	cubic-bezier(0.62, 0.63, 0, 1.13)	出现时-过渡曲线
$animation_delay-notification-show	0ms	出现时-延迟时间
$animation_duration-notification-hide	300ms	消失时-动画持续时间
$animation_function-notification-hide	cubic-bezier(0.62, 0.63, 0, 1.13)	消失时-过渡曲线
$animation_delay-notification-hide	0ms	消失时-延迟时间
$animation_opacity-notification-show	0	出现时-初始透明度
$animation_opacity-notification-hide	0	消失时-结束透明度
$color-notification-bg-default	var(--semi-color-bg-3)	通知背景色
$color-notification_info-icon	var(--semi-color-info)	通知信息图标颜色
$color-notification_warning-icon	var(--semi-color-warning)	通知警告图标颜色
$color-notification_danger-icon	var(--semi-color-danger)	通知危险图标颜色
$color-notification_success-icon	var(--semi-color-success)	通知成功图标颜色
$color-notification_title-text	var(--semi-color-text-0)	通知标题文本颜色
$color-notification_content-text	var(--semi-color-text-1)	通知内容文本颜色
$color-notification_closeBtn-icon	var(--semi-color-text-2)	通知关闭按钮图标颜色
$color-notification_warning_light-bg	var(--semi-color-warning-light-default)	彩色通知警告背景色
$color-notification_warning_light-border	var(--semi-color-warning)	彩色通知警告描边色
$color-notification_success_light-bg	var(--semi-color-success-light-default)	彩色通知成功背景色
$color-notification_success_light-border	var(--semi-color-success)	彩色通知成功描边色
$color-notification_info_light-bg	var(--semi-color-info-light-default)	彩色通知信息背景色
$color-notification_info_light-border	var(--semi-color-info)	彩色通知信息描边色
$color-notification_danger_light-bg	var(--semi-color-danger-light-default)	彩色通知危险背景色
$color-notification_danger_light-border	var(--semi-color-danger)	彩色通知危险描边色
$color-notification_ambient-bg	var(--semi-color-bg-0)	透明背景色叠加层(与bg0保持一致不建议修改)
$width-notification_notice	auto	通知宽度
$width-notification_notice_minWidth	320px	通知最小宽度
$width-notification_notice-icon	$width-icon-extra-large	通知图标宽度
$width-notification_notice-border	1px	通知描边宽度
$spacing-notification_list-margin	0	通知列表外边距
$spacing-notification_list-padding	0	通知列表内边距
$spacing-notification_notice-paddingTop	$spacing-base	通知卡片顶部内边距
$spacing-notification_notice-paddingRight	$spacing-base-tight	通知卡片右侧内边距
$spacing-notification_notice-paddingBottom	$spacing-base	通知卡片底部内边距
$spacing-notification_notice-paddingLeft	$spacing-base-loose	通知卡片左侧内边距
$spacing-notification_notice-margin	$spacing-base-loose	通知卡片外边距
$spacing-notification_notice_title-marginBottom	$spacing-extra-tight	通知卡片标题底部外边距
$spacing-notification_notice_content_wrapper-marginRight	8px	通知卡片内容右侧外边距
$spacing-notification_notice_icon-marginRight	$spacing-base-tight	通知卡片图标右侧外边距
$radius-notification_notice	var(--semi-border-radius-medium)	通知卡片圆角大小
$font-notification_notice_title-fontWeight	$font-weight-bold	通知卡片标题字重
$font-notification_notice_content-fontWeight	$font-weight-regular	通知卡片内容字重