代码演示
如何引入
<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() 构造。
代码
<script setup lang="ts">
import { h } from 'vue';
import { Button, Notification, Typography } from '@fibrous/semi-ui-vue';
const { Text } = Typography;
// content is a VNode or a render function, which a template cannot express
const opts = {
title: 'This is a title',
content: () => [h('div', 'Hi, Bytedance dance dance'), h('div', { style: { marginTop: '8px' } }, [h(Text, { link: true }, () => '查看详情'), h(Text, { link: true, style: { marginLeft: '20px' } }, () => '一会再看')])],
duration: 3,
};
</script>
<template>
<Button @click="Notification.info(opts)">Display Notification</Button>
</template>修改延时
自定义时长 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 | 通知内容;函数在通知内部作为函数式组件渲染,可以 inject | string | VNode | (() => VNodeChild) | '' |
| direction | 文字方向,只作为单条通知的选项,不属于全局配置;不传时跟随 ConfigProvider | ltr | rtl | |
| duration | 自动关闭的延时,单位 s,设为 0 时不自动关闭 | number | 3 |
| getPopupContainer | 指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relative 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。只在首次创建容器时生效。 | () => HTMLElement | () => document.body |
| icon | 左上角 icon | string | VNode | (() => VNodeChild) | |
| id | 自定义通知 id;已有相同 id 的通知时更新其内容 | string | |
| position | 弹出位置,可选 top、bottom、topLeft、topRight、bottomLeft、bottomRight | string | topRight |
| showClose | 是否展示关闭按钮 | boolean | true |
| stack | 同一位置的通知超过多少条时堆叠展示,true 为 3,false 不堆叠;以该位置最新一条通知的设置为准 | boolean | number | false |
| style | 通知元素的内联样式 | StyleValue | |
| theme | 填充样式,支持light, normal | string | normal |
| title | 通知标题 | string | VNode | (() => VNodeChild) | '' |
| zIndex | 弹层 z-index 值,每次弹出时生效 | number | 1010 |
| onClick | 点击通知的回调函数,落在通知元素上 | (e: MouseEvent) => void | |
| onClose | 通知关闭的回调函数(主动关闭、延时到达关闭都会触发,每次关闭只触发一次) | () => void | |
| onCloseClick | 主动点击关闭按钮时的回调函数 | (id: string) => void |
选项里的 onClick、onClose、onCloseClick 保留回调的键名,不使用 emit。
全局配置在调用前提前配置,全局一次生效:
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, 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触发关闭 - 通知出现时不会抢走焦点
- 指针或键盘焦点进入通知时暂停自动关闭的计时,并展开堆叠;移出后恢复计时
文案规范
- 标题
- 使用简洁明了的语言进行说明
- 避免使用逗号,句号等标点符号
- 正文
- 在信息传递完整的前提下,尽可能地将正文压缩至 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 变量 | 值 | 用法 |
|---|---|---|
| $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 | 通知卡片内容字重 |