Notification 通知
在窗口的一角弹出带标题的通知卡片,用来告诉用户后台任务完成、收到新消息等不需要立即处理的信息,几秒后自动消失。用函数调用,不用在模板里写组件。
引入
import { NsNotification } from '@ns/ui'
基础用法
传配置对象,title 是标题,message 是内容。默认出现在右上角,info 类型,4.5 秒后自动关闭,右上角有关闭按钮。
只传一段文字时,这段文字作为内容,没有标题。
<script setup lang="ts">
import { NsButton, NsNotification, NsSpace } from '@ns/ui'
const show = () => {
NsNotification({ title: '导出完成', message: '报表已经生成,可以在下载中心查看。' })
}
const showText = () => {
NsNotification('这是一条通知')
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="show">显示通知</NsButton>
<NsButton @click="showText">只传文字(没有标题)</NsButton>
</NsSpace>
</template>
不同类型
有 success、warning、info、error 四种类型,左侧图标不同。可以用对应的快捷方法,也可以在配置里写 type。快捷方法也能只传文字。
<script setup lang="ts">
import { NsButton, NsNotification, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">快捷方法</span>
<NsButton
type="success"
@click="NsNotification.success({ title: '成功', message: '数据已同步' })"
>
成功(success)
</NsButton>
<NsButton
type="warning"
@click="NsNotification.warning({ title: '警告', message: '存储空间不足 10%' })"
>
警告(warning)
</NsButton>
<NsButton
type="info"
@click="NsNotification.info({ title: '提示', message: '有新版本可用' })"
>
信息(info)
</NsButton>
<NsButton
type="danger"
@click="NsNotification.error({ title: '错误', message: '同步失败,请重试' })"
>
错误(error)
</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">配置 type</span>
<NsButton
@click="NsNotification({ title: 'success', message: '数据已同步', type: 'success' })"
>
success
</NsButton>
<NsButton
@click="NsNotification({ title: 'warning', message: '存储空间不足 10%', type: 'warning' })"
>
warning
</NsButton>
<NsButton @click="NsNotification({ title: 'info', message: '有新版本可用', type: 'info' })">
info
</NsButton>
<NsButton
@click="NsNotification({ title: 'error', message: '同步失败,请重试', type: 'error' })"
>
error
</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">只传文字</span>
<NsButton @click="NsNotification.success('数据已同步')">success</NsButton>
<NsButton @click="NsNotification.warning('存储空间不足 10%')">warning</NsButton>
<NsButton @click="NsNotification.info('有新版本可用')">info</NsButton>
<NsButton @click="NsNotification.error('同步失败,请重试')">error</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 72px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
快捷方法传配置对象时,type 以方法名为准,配置里的 type 不生效。
位置
position 有 top-right(默认)、top-left、bottom-right、bottom-left 四种。每个位置的通知各自排列,互不影响。
<script setup lang="ts">
import { NsButton, NsNotification, NsSpace } from '@ns/ui'
import type { NotificationPosition } from '@ns/ui'
const show = (position: NotificationPosition) => {
NsNotification({ title: position, message: `出现在窗口的 ${position}`, position })
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="show('top-right')">右上(top-right,默认)</NsButton>
<NsButton @click="show('top-left')">左上(top-left)</NsButton>
<NsButton @click="show('bottom-right')">右下(bottom-right)</NsButton>
<NsButton @click="show('bottom-left')">左下(bottom-left)</NsButton>
</NsSpace>
</template>
多条通知和 offset
同一位置连续弹出多条时:顶部的位置从上往下排,后弹出的在下面;底部的位置从下往上排,后弹出的在上面。offset 是这条通知和同一位置上一条之间的距离,排在第一条时是和窗口上边(top-*)或下边(bottom-*)的距离,默认 16(像素)。有一条关闭后,其余的依次移动补位。通知和窗口左右边缘的距离固定是 16 像素。
<script setup lang="ts">
import { NsButton, NsNotification, NsSpace } from '@ns/ui'
const showTop = () => {
NsNotification({ title: '第 1 条', message: '离窗口顶部 16px' })
NsNotification({ title: '第 2 条', message: '离上一条 60px', offset: 60 })
}
const showBottom = () => {
NsNotification({ title: '第 1 条', message: '先弹出,在最下面', position: 'bottom-right' })
NsNotification({ title: '第 2 条', message: '后弹出,排在上面', position: 'bottom-right' })
NsNotification({
title: '第 3 条',
message: '离上一条 40px',
position: 'bottom-right',
offset: 40
})
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="showTop">右上角两条(第二条 offset 60)</NsButton>
<NsButton @click="showBottom">右下角三条(从下往上排)</NsButton>
</NsSpace>
</template>
显示时长和手动关闭
duration 是显示多少毫秒后自动关闭,默认 4500,为 0 时不自动关闭。鼠标移到通知上时暂停计时,移开后重新计时。showClose 默认是 true,设为 false 时不显示关闭按钮。
<script setup lang="ts">
import { NsButton, NsNotification, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsButton @click="NsNotification({ title: '2 秒', message: '2 秒后关闭', duration: 2000 })">
2 秒
</NsButton>
<NsButton @click="NsNotification({ title: '4.5 秒', message: '4.5 秒后关闭' })">
4.5 秒(默认)
</NsButton>
<NsButton
@click="NsNotification({ title: '不自动关闭', message: '点右上角的 × 关闭', duration: 0 })"
>
不自动关闭(0)
</NsButton>
<NsButton
@click="
NsNotification({
title: '没有关闭按钮',
message: '3 秒后自动关闭',
showClose: false,
duration: 3000
})
"
>
不显示关闭按钮
</NsButton>
</NsSpace>
</template>
每次调用都返回一个 NotificationInstance,调用它的 close() 可以随时关闭这条通知。
<script setup lang="ts">
import { NsButton, NsNotification, NsSpace } from '@ns/ui'
import type { NotificationInstance } from '@ns/ui'
let instance: NotificationInstance | null = null
const open = () => {
instance = NsNotification({
title: '正在上传',
message: '上传完成前不会自动关闭',
duration: 0,
showClose: false
})
}
const close = () => {
instance?.close()
instance = null
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="open">打开</NsButton>
<NsButton @click="close">关闭</NsButton>
</NsSpace>
</template>
点击和关闭回调
onClick在点击通知时调用,点关闭按钮不会调用它。onClose在通知关闭、淡出动画结束后调用一次。自动关闭、点关闭按钮、调用close()或closeAll()都会调用。
点击通知本身不会关闭通知,需要时在 onClick 里关闭。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsMessage, NsNotification } from '@ns/ui'
import type { NotificationInstance } from '@ns/ui'
const status = ref('还没有打开通知')
const open = () => {
status.value = '通知显示中,点一下通知试试'
const instance: NotificationInstance = NsNotification({
title: '新消息',
message: '点这里查看',
duration: 0,
onClick: () => {
NsMessage.success('onClick:打开消息中心')
instance.close()
},
onClose: () => {
status.value = `onClose 已调用(${new Date().toLocaleTimeString()})`
}
})
}
</script>
<template>
<NsButton @click="open">打开通知</NsButton>
<p style="margin-top: 12px">{{ status }}</p>
</template>
内容传 VNode
message 除了字符串,还可以传用 h() 创建的 VNode。字符串按纯文本显示,不会解析 HTML,写在字符串里的标签会原样显示出来。title 只能是字符串。
<script setup lang="ts">
import { h } from 'vue'
import { NsButton, NsNotification, NsSpace } from '@ns/ui'
const showVNode = () => {
NsNotification({
title: '审批通过',
message: h('span', ['申请单 ', h('b', 'SQ-0012'), ' 已通过审批'])
})
}
const showString = () => {
NsNotification({ title: '审批通过', message: '申请单 <b>SQ-0012</b> 已通过审批' })
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="showVNode">VNode:加粗单号</NsButton>
<NsButton @click="showString">字符串:标签原样显示</NsButton>
</NsSpace>
</template>
关闭全部
NsNotification.closeAll() 关闭所有位置上的通知,每条都有正常的淡出动画,也会调用各自的 onClose。
<script setup lang="ts">
import { NsButton, NsNotification, NsSpace } from '@ns/ui'
const openMany = () => {
NsNotification.success({ title: '右上', message: '不会自动关闭', duration: 0 })
NsNotification.warning({
title: '左上',
message: '不会自动关闭',
duration: 0,
position: 'top-left'
})
NsNotification.info({
title: '右下',
message: '不会自动关闭',
duration: 0,
position: 'bottom-right'
})
NsNotification.error({
title: '左下',
message: '不会自动关闭',
duration: 0,
position: 'bottom-left'
})
}
</script>
<template>
<NsSpace wrap>
<NsButton @click="openMany">四个角各弹一条</NsButton>
<NsButton type="primary" @click="NsNotification.closeAll()">关闭全部</NsButton>
</NsSpace>
</template>
调用方式
| 写法 | 说明 |
|---|---|
NsNotification(options: NotificationOptions) | 按配置弹出一条通知 |
NsNotification(message: string) | 弹出一条只有内容、没有标题的 info 类型通知 |
NsNotification.success(message | options) | 弹出 success 类型的通知 |
NsNotification.warning(message | options) | 弹出 warning 类型的通知 |
NsNotification.info(message | options) | 弹出 info 类型的通知 |
NsNotification.error(message | options) | 弹出 error 类型的通知 |
NsNotification.closeAll() | 关闭所有位置上的通知,没有返回值 |
除了 closeAll,其他写法都返回这条通知的 NotificationInstance。
配置项
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title | string | '' | 标题,为空时不显示标题行 |
| message | string | VNode | '' | 内容。字符串按纯文本显示 |
| type | 'success' | 'warning' | 'info' | 'error' | 'info' | 类型,决定图标 |
| duration | number | 4500 | 显示多少毫秒后自动关闭,为 0 时不自动关闭 |
| showClose | boolean | true | 是否显示关闭按钮 |
| position | 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-right' | 出现在窗口的哪个角 |
| offset | number | 16 | 和同一位置上一条通知的距离(像素),排在第一条时是和窗口上边或下边的距离 |
| onClick | () => void | — | 点击通知时调用,点关闭按钮不调用 |
| onClose | () => void | — | 关闭的淡出动画结束后调用 |
返回值
NotificationInstance:
| 属性 | 类型 | 说明 |
|---|---|---|
| id | string | 这条通知的编号 |
| vm | HTMLElement | 通知的 DOM 元素 |
| props | NotificationProps | 这条通知最终使用的配置(没传的项是默认值) |
| close | () => void | 关闭这条通知,有淡出动画。已经在关闭的通知再调用不做任何事 |
类型
import type {
NotificationType,
NotificationPosition,
NotificationProps,
NotificationOptions,
NotificationInstance,
NotificationFn
} from '@ns/ui'
import type { VNode } from 'vue'
type NotificationType = 'success' | 'warning' | 'info' | 'error'
type NotificationPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
interface NotificationProps {
title?: string
message: string | VNode
type?: NotificationType
duration?: number
showClose?: boolean
position?: NotificationPosition
offset?: number
onClose?: () => void
onClick?: () => void
}
interface NotificationOptions extends Omit<NotificationProps, 'message'> {
title?: string
message?: string | VNode
}
interface NotificationInstance {
id: string
vm: HTMLElement
props: NotificationProps
close: () => void
}
interface NotificationFn {
(options: NotificationOptions): NotificationInstance
(message: string): NotificationInstance
success: (message: string | NotificationOptions) => NotificationInstance
warning: (message: string | NotificationOptions) => NotificationInstance
info: (message: string | NotificationOptions) => NotificationInstance
error: (message: string | NotificationOptions) => NotificationInstance
closeAll: () => void
}
另外导出了通知本身的组件 NsNotificationComponent,NsNotification 内部用它渲染,一般不需要直接用。
注意事项
- 每条通知都是单独创建的 Vue 应用,挂在
body下按位置分开的.ns-notification-container里。message传的 VNode 拿不到当前应用的全局组件、provide和插件,VNode 里用到的组件要直接 import。 - 通知的
z-index固定是 9999,盖在对话框和消息弹框上面,不读NsConfigProvider的zIndex(通知是单独创建的应用,读不到它)。 - 通知宽 330 像素,窄屏下不超过窗口宽度减 32 像素,多条叠在一起时边缘对齐。
- 通知的根元素是
role="alert",屏幕阅读器会读出内容。关闭按钮是原生<button>,可以用 Tab 键聚焦,按回车或空格关闭;onClick只响应鼠标点击,通知本身不能用键盘聚焦。
优化点
- [ ] 支持自定义图标
- [ ]
title支持传 VNode - [ ] 通知本身支持键盘聚焦和回车触发
onClick - [ ] 支持限制同时显示的条数