0 Fork 0

Files

T

2026-10-08 22:38:34 +08:00

5.1 KiB

Raw Blame History

title, description

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

Message 轻提示

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

何时使用

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

基础用法

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

:::demo{name="message/basic"} :::

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"} :::

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? }。

类型定义

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 }) 切换。

5.1 KiB Raw Blame History Unescape Escape