---
title: Message 轻提示
description: 命令式轻提示：info / success / warning / error
---

# Message 轻提示

`Message` 用于给用户一个**不打断操作**的反馈：保存成功、校验失败、复制完成。

## 何时使用

- 操作结果反馈（成功 / 失败 / 警告）时；
- 需要用户**确认**或做选择时，用 [Modal.confirm](/ui/overlay/modal)；
- 需要承载标题 + 描述、停留更久时，用 [Notification](/ui/feedback/notification)。

## 基础用法

`G3Message` 是一个对象，直接调用即可——它会自己挂载容器到 `body`，无需在模板里写组件。

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

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

G3Message.info('普通提示')
G3Message.success('保存成功')
G3Message.warning('磁盘空间不足')
G3Message.error('保存失败，请重试')
```

## 选项与句柄

第二个参数是选项对象；调用返回 `{ close }` 句柄，可以提前关闭。

<demo vue="message/options.vue" />

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `duration` | `number` | `3000` | 自动关闭时长（ms）。`<= 0` 表示不自动关闭 |
| `closable` | `boolean` | `false` | 是否显示关闭按钮 |
| `placement` | `MessagePlacement` | 全局配置 | 显示方位（9 个） |

## 方位与全局配置

`placement` 可逐条指定；`G3Message.config()` 设置全局默认，只影响之后的调用。

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

```ts
G3Message.config({ placement: 'top-right', duration: 2000 })
```

## 使用注意

- `G3Message` 在**组件树之外**创建实例：命名空间、语言包、初始方位来自全局配置（`G3UI.config()` / `ConfigProvider` 无法 inject 到它），因此多主题场景请在 `G3UI.config({ namespace })` 里统一；
- 消息是「短反馈」，不要放按钮、链接等需要交互的内容——那属于 Notification 或 Modal；
- 同一时刻的消息默认堆叠在同一个方位，超过屏幕高度时请自行控制数量（例如 `duration` 缩短）。

## API

### 方法

| 方法 | 签名 | 说明 |
| --- | --- | --- |
| `open` | `(options: MessageOptions) => MessageHandle` | 通用入口 |
| `info` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 信息提示 |
| `success` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 成功 |
| `warning` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 警告 |
| `error` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 错误 |
| `close` | `(id: string) => void` | 按 id 关闭一条 |
| `config` | `(config: MessageConfig) => void` | 设置全局默认（`placement` / `duration`） |
| `destroy` | `() => void` | 清空全部消息并卸载容器（登出 / 切租户时用） |
| `count` | `() => number` | 当前存活条数（调试用） |

`ShortcutOptions` = `Omit<MessageOptions, 'content' | 'type'>`，即 `{ duration?, closable?, placement? }`。

### 类型定义

```ts
export type MessageType = 'info' | 'success' | 'warning' | 'error'

export type MessagePlacement =
  | 'top-left' | 'top-center' | 'top-right'
  | 'center-left' | 'center' | 'center-right'
  | 'bottom-left' | 'bottom-center' | 'bottom-right'

export interface MessageOptions {
  content: string
  type?: MessageType
  duration?: number
  closable?: boolean
  placement?: MessagePlacement
}

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

export interface MessageConfig {
  placement?: MessagePlacement
  duration?: number
}
```

### 组件形式（G3MessageItem / G3MessageContainer）

一般不需要直接使用；如果要把消息渲染进自己的容器（例如某个面板内部），可以组合它们：

| 组件 | Props | 说明 |
| --- | --- | --- |
| `G3MessageItem` | `id` / `type` / `content` / `duration` / `closable` | 单条消息，`close` 事件表示「该关闭了」（自动计时到期或点了关闭按钮） |
| `G3MessageContainer` | `zIndex` | 9 个方位的容器，读取全局 `messageState` 渲染 |

### 样式变量

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

## 实现说明

- **组件树外挂载**：首次调用时创建单例容器（`createVNode` + `render` 挂到 `body`），之后复用；`destroy()` 才会卸载并回收 z-index；
- 全局状态放在 `messageState`（`reactive`），容器读它、管理器写它，因此消息增删是响应式的；容器对 9 个方位各渲染一个常驻的 `TransitionGroup`，**只让消息项进出**，这是进出场动画能稳定触发的前提；
- 层级取 z-index 注册表的 `feedback` 档（高于 modal / popup），保证弹窗里的操作提示也能看到；容器本身 `pointer-events: none`，只有消息卡片可交互，避免挡住页面；
- `duration` 计时在消息项内部完成（`onMounted` 启动、卸载时清除），因此手动关闭与自动关闭不会互相干扰；
- 文案来自语言包（关闭按钮的 `aria-label` 等），可用 `ConfigProvider.locale` / `G3UI.config({ locale })` 切换。