u

2026-10-09 17:32:14 +08:00
1 parent e99a9fb274
commit 0be0b0767a
@@ -0,0 +1,110 @@
+---
+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)` 只关一条。