u

code/g3soft-libs/docs/content/ui/5.feedback/message.md

@@ -0,0 +1,131 @@
+---
+title: Message 轻提示
+description: 命令式轻提示：info / success / warning / error
+---
+
+# Message 轻提示
+
+`Message` 用于给用户一个**不打断操作**的反馈：保存成功、校验失败、复制完成。
+
+## 何时使用
+
+- 操作结果反馈（成功 / 失败 / 警告）时；
+- 需要用户**确认**或做选择时，用 [Modal.confirm](/ui/overlay/modal)；
+- 需要承载标题 + 描述、停留更久时，用 [Notification](/ui/feedback/notification)。
+
+## 基础用法
+
+`G3Message` 是一个对象，直接调用即可——它会自己挂载容器到 `body`，无需在模板里写组件。
+
+:::demo{name="message/basic"}
+:::
+
+```ts
+import { G3Message } from '@g3soft/ui'
+
+G3Message.info('普通提示')
+G3Message.success('保存成功')
+G3Message.warning('磁盘空间不足')
+G3Message.error('保存失败，请重试')
+```
+
+## 选项与句柄
+
+第二个参数是选项对象；调用返回 `{ close }` 句柄，可以提前关闭。
+
+:::demo{name="message/options"}
+:::
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `duration` | `number` | `3000` | 自动关闭时长（ms）。`<= 0` 表示不自动关闭 |
+| `closable` | `boolean` | `false` | 是否显示关闭按钮 |
+| `placement` | `MessagePlacement` | 全局配置 | 显示方位（9 个） |
+
+## 方位与全局配置
+
+`placement` 可逐条指定；`G3Message.config()` 设置全局默认，只影响之后的调用。
+
+:::demo{name="message/placement"}
+:::
+
+```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 })` 切换。