notification 通知

角落卡片式通知。有标题、能承载更多内容、可带操作按钮。

基础用法

vue

<script setup>
import { notification } from '@starriver/ui'

notification.success({
  title: '操作成功',
  content: '数据已保存。'
})
</script>

与 toast / message 的分工

三个都是命令式提示，先想清楚该用哪个：

	形态	内容量	位置
`toast`	单行胶囊	一句话	顶部居中
`message`	单行胶囊	一句话	顶部居中
`notification`	卡片	标题 + 正文	四角

判断方法：需不需要标题？

一句话能说清（「保存成功」）→ toast
需要解释一下（「有新的版本可用 / v0.6.0 已发布…」）→ notification

notification 的位置在角落，不遮挡页面中部—— 内容是"可以稍后再看"的信息，不该打断用户当前的操作。

四角定位

notification.success({
  title: '标题',
  content: '内容',
  placement: 'topRight'   // 默认
})

位置	适用
`topRight`	默认，多数场景
`topLeft`	页面右侧已有固定面板时
`bottomRight`	消息中心、持续更新的流
`bottomLeft`	同上，但右侧有交互控件时

右上角是默认值的原因

视线在阅读时从左上到右下移动，右上角是"扫过但不会被重点关注"的位置。

通知的定位是"告知但尽量不打断"——放在右上角，用户需要时会主动看过去，不需要时它也不会挡住主要内容。

时长

duration 传 0 表示不自动关闭。

notification.warning({
  title: '需要手动关闭',
  content: '内容较长，需要用户确认看到。',
  duration: 0
})

通知的默认时长应该比 toast 长

toast 是一句话，3 秒够读；notification 有标题加正文，内容量翻倍。

更何况用户可能正在别处操作，注意不到角落里的变化。建议 notification 的默认时长设在 4.5–5 秒，内容重要时直接用 duration: 0。

读屏用户朗读一段标题 + 正文通常需要 6 秒以上—— 自动消失的通知对他们来说等同于不存在。

带操作按钮

actions 传一组按钮。

notification.info({
  title: '更新已下载',
  content: '重启应用即可生效。',
  duration: 0,
  actions: [
    { text: '稍后', onClick: () => {} },
    { text: '立即重启', type: 'primary', onClick: () => {} }
  ]
})

带操作按钮时必须 duration: 0

用户看到通知、理解内容、决定点哪个按钮——这几秒里通知不能消失。

不是"应该"而是"必须"：一个会跑掉的按钮比没有按钮更糟，用户会觉得自己点不到、或者点了没反应。

关闭与堆叠

const id = notification.info({ title: '标题', content: '内容' })

notification.close(id)       // 关闭指定通知
notification.closeAll()      // 关闭全部

多条通知会在同一角落向下堆叠，相互不遮挡。超出屏幕高度时最旧的会被顶出——这是有意的，避免通知区无限增长。

API

方法	参数	返回
`notification.success(options)`	见下表	id
`notification.error(options)`	同上	id
`notification.warning(options)`	同上	id
`notification.info(options)`	同上	id
`notification.close(id)`	通知 id	—
`notification.closeAll()`	—	—

options

字段	类型	默认值	说明
`title`	`string`	—	标题
`content`	`string`	—	正文
`duration`	`number`	`4500`	时长（毫秒），`0` 表示不自动关闭
`placement`	`'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight'`	`'topRight'`	位置
`actions`	`{ text, type?, onClick }[]`	—	操作按钮（需配合 `duration: 0`）
`onClose`	`() => void`	—	关闭时的回调

也支持独立函数形式：

import { showNotification, closeNotification } from '@starriver/ui'

showNotification({ type: 'success', title: '标题', content: '内容' })

无障碍

容器带 role="status" 与 aria-live="polite"；error 类型用 aria-live="assertive"（需要立即打断）
标题渲染为真实标题元素，读屏软件能按结构跳转
自动消失的通知对读屏用户是障碍（WCAG 2.2.1 要求可延长）—— 内容重要时用 duration: 0，或提供"通知中心"让用户回看
操作按钮是真实的 <button>，且带 duration: 0 保证来得及点击

notification 通知 ​

基础用法 ​

与 toast / message 的分工 ​

四角定位 ​

时长 ​

带操作按钮 ​

关闭与堆叠 ​

API ​

options ​

无障碍 ​