---
title: Notification 通知提醒
description: 命令式通知：带标题与描述，适合承载需要阅读的信息
---

# Notification 通知提醒

`Notification` 与 [Message](/ui/feedback/message) 是同一套机制，但**承载更多信息**：有标题、有描述、默认停留更久（4500ms），适合「需要被读到」的内容。

## 何时使用

- 后台任务完成 / 失败，用户当前可能不在看那一块界面；
- 需要标题 + 详细描述的信息（版本发布、审核结果、系统告警）；
- 只是「一句话结果」时用 Message 更轻；需要用户做出选择时用 [Modal](/ui/overlay/modal)。

## 基础用法

<demo vue="notification/basic.vue" />

```ts
import { G3Notification } from '@g3soft/ui'

G3Notification.success({ title: '发布成功', description: '版本 1.2.0 已上线' })
G3Notification.error({ title: '构建失败', description: '单元测试未通过', duration: 0 })
```

## 方位

通知只出现在四角（避免遮挡页面中央内容）；逐条可指定 `placement`，也可以用 `config()` 设全局默认。

<demo vue="notification/placement.vue" />

```ts
G3Notification.config({ placement: 'bottom-right', duration: 6000 })
```

## 关闭与清理

<demo vue="notification/close.vue" />

## 使用注意

- 通知是「异步结果」的表达，不要在用户操作的同一瞬间用它替代即时反馈——那种场景用 Message；
- `duration: 0` 的通知必须带 `closable`（默认就是 `true`），否则用户无法关闭；
- 登出、切换租户、路由跳转到登录页时建议调用 `G3Notification.destroy()`，避免残留旧上下文的通知。

## API

### 方法

| 方法 | 签名 | 说明 |
| --- | --- | --- |
| `open` | `(options: NotificationOptions) => NotificationHandle` | 通用入口 |
| `info` | `(options: ShortcutOptions) => NotificationHandle` | 信息 |
| `success` | `(options: ShortcutOptions) => NotificationHandle` | 成功 |
| `warning` | `(options: ShortcutOptions) => NotificationHandle` | 警告 |
| `error` | `(options: ShortcutOptions) => NotificationHandle` | 错误 |
| `close` | `(id: string) => void` | 按 id 关闭一条 |
| `config` | `(config: NotificationConfig) => void` | 设置全局默认（`placement` / `duration`） |
| `destroy` | `() => void` | 清空全部通知并卸载容器 |
| `count` | `() => number` | 当前存活条数（调试用） |

`ShortcutOptions` = `Omit<NotificationOptions, 'type'>`，即 `{ title?, description?, duration?, closable?, placement? }`。

### 类型定义

```ts
export type NotificationType = 'info' | 'success' | 'warning' | 'error'
export type NotificationPlacement = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'

export interface NotificationOptions {
  title?: string
  description?: string
  type?: NotificationType
  duration?: number
  closable?: boolean
  placement?: NotificationPlacement
}

export interface NotificationHandle {
  close: () => void
}

export interface NotificationConfig {
  placement?: NotificationPlacement
  duration?: number
}
```

### 组件形式（G3NotificationItem / G3NotificationContainer）

| 组件 | Props | 说明 |
| --- | --- | --- |
| `G3NotificationItem` | `id` / `type` / `title` / `description` / `duration` / `closable` | 单条通知，`close` 事件表示「该关闭了」 |
| `G3NotificationContainer` | `zIndex` | 四角容器，读取全局 `notificationState` 渲染 |

### 样式变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `--g3-feedback-offset` | `24px` | 距视口边缘的距离 |
| `--g3-feedback-icon-size` | `18px` | 类型图标尺寸 |
| `--g3-shadow-popup` | 浮层阴影 | 通知卡片阴影 |

## 实现说明

- 与 Message 同构：组件树外单例容器（`createVNode` + `render`）、`reactive` 全局列表、四角常驻 `TransitionGroup`；
- 单条宽度固定 `340px`，`max-width: calc(100vw - offset*2)`，窄屏不会溢出；描述文字换行不截断（通知的意义就在于把话说完）；
- 层级的 `feedback` 档高于 modal / popup：弹窗里触发的通知一定能被看到；
- `destroy()` 会卸载容器并回收 z-index，适合登出等「上下文整体切换」的场景；`close(id)` 只关一条。