反馈类

通知

通知用于主动向用户发出消息通知

代码演示

如何引入

<script setup lang="ts">
    import { Notification } from '@fibrous/semi-ui-vue';
</script>

静态方法在组件树之外渲染。可选 app.use(Notification):安装后静态通知用该 app 的上下文渲染,可以读到 app.provide() 的值和全局注册的组件;Toast、Notification、Modal 的静态方法共用这一记录,安装其中任何一个即对三者生效,多个 app 都安装时以最后一次为准。

普通通知

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

代码
<script setup lang="ts">
    import { Button, Notification } from '@fibrous/semi-ui-vue';

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

<template>
    <Button @click="Notification.open(opts)">Display Notification</Button>
</template>

不同位置弹出

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



代码
<script setup lang="ts">
    import { Button, ButtonGroup, Notification } from '@fibrous/semi-ui-vue';

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

<template>
    <ButtonGroup>
        <Button @click="Notification.info({ ...opts, position: 'top' })">top</Button>
        <Button @click="Notification.info({ ...opts, position: 'topLeft' })">topLeft</Button>
        <Button @click="Notification.info(opts)">topRight</Button>
    </ButtonGroup>
    <br />
    <br />
    <ButtonGroup>
        <Button @click="Notification.info({ ...opts, position: 'bottom' })">bottom</Button>
        <Button @click="Notification.info({ ...opts, position: 'bottomRight' })">bottomRight</Button>
        <Button @click="Notification.info({ ...opts, position: 'bottomLeft' })">bottomLeft</Button>
    </ButtonGroup>
</template>

带有图标的通知

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

默认的图标
自定义图标
代码
<script setup lang="ts">
    import { h } from 'vue';
    import { IconToutiaoLogo, IconVigoLogo } from '@fibrous/semi-icons-vue';
    import { Button, Notification } from '@fibrous/semi-ui-vue';

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

    // icon is a VNode or a render function, which a template cannot express
    const showIcon = (icon: typeof IconVigoLogo, color?: string) => Notification.info({ ...opts, icon: h(icon, color ? { style: { color } } : null) });
</script>

<template>
    <h5>默认的图标</h5>
    <Button :style="{ margin: '4px' }" type="primary" @click="Notification.success(opts)">Success</Button>
    <Button :style="{ margin: '4px' }" @click="Notification.info(opts)">Info</Button>
    <Button :style="{ margin: '4px' }" type="warning" @click="Notification.warning(opts)">Warning</Button>
    <Button :style="{ margin: '4px' }" type="danger" @click="Notification.error(opts)">Error</Button>
    <h5>自定义图标</h5>
    <Button aria-label="Toutiao 图标通知" :style="{ marginRight: '5px' }" @click="showIcon(IconToutiaoLogo, 'red')">
        <template #icon>
            <IconToutiaoLogo />
        </template>
    </Button>
    <Button aria-label="Vigo 图标通知" :style="{ marginRight: '5px' }" @click="showIcon(IconVigoLogo)">
        <template #icon>
            <IconVigoLogo />
        </template>
    </Button>
    <Button aria-label="粉色 Vigo 图标通知" @click="showIcon(IconVigoLogo, 'pink')">
        <template #icon>
            <IconVigoLogo />
        </template>
    </Button>
</template>

多色样式

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







代码
<script setup lang="ts">
    import { Button, Notification } from '@fibrous/semi-ui-vue';

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

<template>
    <Button @click="Notification.info(opts)">Info</Button>
    <br />
    <br />
    <Button @click="Notification.success(opts)">Success</Button>
    <br />
    <br />
    <Button type="warning" @click="Notification.warning(opts)">Warning</Button>
    <br />
    <br />
    <Button type="danger" @click="Notification.error(opts)">Error</Button>
</template>

链接文本

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

title、content、icon 接受 string、VNode 或返回 VNodeChild 的函数;下面示例中的 Typography 文本用 h() 构造。

修改延时

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

代码
<script setup lang="ts">
    import { Button, Notification } from '@fibrous/semi-ui-vue';

    const opts = {
        content: 'Hi, Bytedance dance dance',
        duration: 10,
    };
</script>

<template>
    <Button @click="Notification.info(opts)">Close After 10s</Button>
</template>

手动关闭

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



代码
<script setup lang="ts">
    import { ref } from 'vue';
    import { Button, Notification } from '@fibrous/semi-ui-vue';

    const opts = {
        content: 'Not auto close',
        title: 'Hi',
        duration: 0,
    };
    const ids = ref<string[]>([]);

    function show() {
        ids.value.push(Notification.info(opts));
    }

    function hide() {
        const first = ids.value.shift();
        if (first) {
            Notification.close(first);
        }
    }
</script>

<template>
    <Button type="primary" @click="show">Show Notification</Button>
    <br />
    <br />
    <Button type="primary" @click="hide">Hide Notification</Button>
</template>

堆叠样式

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

代码
<script setup lang="ts">
    import { Button, Notification } from '@fibrous/semi-ui-vue';

    const opts = {
        title: 'Hi',
        content: 'Hi, Bytedance dance dance',
        duration: 10,
        stack: true,
    };
</script>

<template>
    <Button @click="Notification.info(opts)">Click multiple times</Button>
</template>

更新内容

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

代码
<script setup lang="ts">
    import { Button, Notification } from '@fibrous/semi-ui-vue';

    function show() {
        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);
    }
</script>

<template>
    <Button @click="show">Display Notification</Button>
</template>

消费 Context

通过 Notification.useNotification() 创建支持读取 context 的 Holder,通知渲染在 <Holder /> 所在的节点处,继承该位置的 provide、ConfigProvider 和语言,进场、离场动画与静态方法相同。content、icon、title 传函数时,函数在通知内部作为函数式组件渲染,里面可以 inject。

代码
<script setup lang="ts">
    import { inject, provide, ref, type InjectionKey } from 'vue';
    import { Button, Notification, Space } from '@fibrous/semi-ui-vue';

    const reachableKey: InjectionKey<string> = Symbol('reachable');
    provide(reachableKey, 'Light');

    const [notification, Holder] = Notification.useNotification();
    const ids = ref<string[]>([]);
    // The function is rendered as a functional component inside the notification, so it can inject from where Holder sits
    const content = () => `ReachableContext: ${inject(reachableKey)}`;

    function show() {
        ids.value.push(notification.info({ title: 'Hook Notification', content, duration: 0 }));
    }

    function hide() {
        const first = ids.value.shift();
        if (first) {
            notification.close(first);
        }
    }
</script>

<template>
    <Space>
        <Button @click="show">Show Notification</Button>
        <Button @click="hide">Hide Notification</Button>
    </Space>
    <Holder />
</template>

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 | object | array
content通知内容;函数在通知内部作为函数式组件渲染,可以 injectstring | VNode | (() => VNodeChild)''
direction文字方向,只作为单条通知的选项,不属于全局配置;不传时跟随 ConfigProviderltr | rtl
duration自动关闭的延时,单位 s,设为 0 时不自动关闭number3
getPopupContainer指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relative 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。只在首次创建容器时生效。() => HTMLElement() => document.body
icon左上角 iconstring | VNode | (() => VNodeChild)
id自定义通知 id;已有相同 id 的通知时更新其内容string
position弹出位置,可选 top、bottom、topLeft、topRight、bottomLeft、bottomRightstringtopRight
showClose是否展示关闭按钮booleantrue
stack同一位置的通知超过多少条时堆叠展示,true 为 3,false 不堆叠;以该位置最新一条通知的设置为准boolean | numberfalse
style通知元素的内联样式StyleValue
theme填充样式,支持light, normalstringnormal
title通知标题string | VNode | (() => VNodeChild)''
zIndex弹层 z-index 值,每次弹出时生效number1010
onClick点击通知的回调函数,落在通知元素上(e: MouseEvent) => void
onClose通知关闭的回调函数(主动关闭、延时到达关闭都会触发,每次关闭只触发一次)() => void
onCloseClick主动点击关闭按钮时的回调函数(id: string) => void

选项里的 onClick、onClose、onCloseClick 保留回调的键名,不使用 emit。

全局配置在调用前提前配置,全局一次生效:

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

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

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

全局销毁:

  • Notification.destroyAll()

Hook Notification:

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

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-show300ms出现时-动画持续时间
$animation_function-notification-showcubic-bezier(0.62, 0.63, 0, 1.13)出现时-过渡曲线
$animation_delay-notification-show0ms出现时-延迟时间
$animation_duration-notification-hide300ms消失时-动画持续时间
$animation_function-notification-hidecubic-bezier(0.62, 0.63, 0, 1.13)消失时-过渡曲线
$animation_delay-notification-hide0ms消失时-延迟时间
$animation_opacity-notification-show0出现时-初始透明度
$animation_opacity-notification-hide0消失时-结束透明度
$color-notification-bg-defaultvar(--semi-color-bg-3)通知背景色
$color-notification_info-iconvar(--semi-color-info)通知 信息 图标颜色
$color-notification_warning-iconvar(--semi-color-warning)通知 警告 图标颜色
$color-notification_danger-iconvar(--semi-color-danger)通知 危险 图标颜色
$color-notification_success-iconvar(--semi-color-success)通知 成功 图标颜色
$color-notification_title-textvar(--semi-color-text-0)通知 标题 文本颜色
$color-notification_content-textvar(--semi-color-text-1)通知 内容 文本颜色
$color-notification_closeBtn-iconvar(--semi-color-text-2)通知 关闭按钮 图标颜色
$color-notification_warning_light-bgvar(--semi-color-warning-light-default)彩色通知警告背景色
$color-notification_warning_light-bordervar(--semi-color-warning)彩色通知警告描边色
$color-notification_success_light-bgvar(--semi-color-success-light-default)彩色通知成功背景色
$color-notification_success_light-bordervar(--semi-color-success)彩色通知成功描边色
$color-notification_info_light-bgvar(--semi-color-info-light-default)彩色通知信息背景色
$color-notification_info_light-bordervar(--semi-color-info)彩色通知信息描边色
$color-notification_danger_light-bgvar(--semi-color-danger-light-default)彩色通知危险背景色
$color-notification_danger_light-bordervar(--semi-color-danger)彩色通知危险描边色
$color-notification_ambient-bgvar(--semi-color-bg-0)透明背景色叠加层(与bg0保持一致不建议修改)
$width-notification_noticeauto通知宽度
$width-notification_notice_minWidth320px通知最小宽度
$width-notification_notice-icon$width-icon-extra-large通知图标宽度
$width-notification_notice-border1px通知描边宽度
$spacing-notification_list-margin0通知列表外边距
$spacing-notification_list-padding0通知列表内边距
$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-marginRight8px通知卡片内容右侧外边距
$spacing-notification_notice_icon-marginRight$spacing-base-tight通知卡片图标右侧外边距
$radius-notification_noticevar(--semi-border-radius-medium)通知卡片圆角大小
$font-notification_notice_title-fontWeight$font-weight-bold通知卡片标题字重
$font-notification_notice_content-fontWeight$font-weight-regular通知卡片内容字重