Message 全局提示

轻量的全局反馈提示，从顶部弹入，几秒后自动消失。适合用于操作成功 / 失败的简短确认，不打断用户操作。

基本使用

调用 message.info / success / warning / error / loading 即可弹出对应类型的提示。

加载中

message.loading 用于异步操作前的占位提示，自动播放旋转图标。

自定义停留时长

第二个参数推荐传秒；传 0 时不会自动关闭，需要手动调用返回的 close()。

单位规则

• duration ≤ 100 视为「秒」（如 3 → 3 秒、1.5 → 1.5 秒）
• duration > 100 视为「毫秒」（如 3000、8000）
• duration === 0 永远表示不自动关闭

多 placement

支持 6 个位置：top / topLeft / topRight / bottom / bottomLeft / bottomRight。默认 top。

全局配置 message.config

message.config(...) 可一次性设定 maxCount / stack / pauseOnHover / role / duration / top / bottom / getContainer 等全局默认值。再次调用以覆盖前一次配置。

主动关闭

当 duration 设为 0，或希望提前关闭时，使用调用返回的 MessageHandle。

显示关闭按钮 + 回调

showClose 显示关闭图标；onClose 在关闭（自动 / 主动）时触发，用于清理或埋点。

全局清空

message.destroy() 关闭所有当前显示的提示并卸载容器；下次再调用 message.* 会重新挂载。

useMessage composable

useMessage() 返回 { message, holder } 对象（不是 React 的 [modal, contextHolder] 元组）。容器渲染在当前 Vue 子树里，自动继承父组件 provide 的 ConfigProvider / 主题等上下文——与模块级 message 的最大差异。

何时用模块级 vs Hook 版？

• 模块级 import { message } from '@vaebe/ccui'：脚手架 / utils / 命令式弹一条，简单直接，但容器走独立 createApp，拿不到调用方 app 的 inject（如自定义 ConfigProvider、主题、locale）。
• Hook useMessage()：当弹层需要继承组件树上下文（深色主题、自定义 locale、自定义 ConfigProvider）时用。必须在模板中挂 <component :is="holder" />。

UseMessageReturn

字段	类型	说明
message	MessageApi	与全局 message 同 API：info/success/warning/error/loading/open/config/destroy
holder	Component	必须挂到模板：<component :is="holder" />

API

message 命名空间

方法	说明
message.open(options)	通用入口，传完整 MessageOptions，返回 MessageHandle
message.info(content, duration?)	信息（默认 3 秒），返回 MessageHandle
message.success(content, duration?)	成功
message.warning(content, duration?)	警告
message.error(content, duration?)	错误
message.loading(content, duration?)	加载（带旋转图标）
message.config(cfg)	全局默认值配置
message.destroy()	关闭全部当前提示并卸载容器

MessageOptions

字段	类型	默认	说明
content	string | VNode	—	提示内容（必填）
type	MessageType	'info'	类型：info / success / warning / error / loading
duration	number	3	停留时长。≤100 按秒，>100 按毫秒；0 不自动关闭
showClose	boolean	false	是否显示关闭按钮
icon	string	''	自定义 icon 名（覆盖默认类型图标）
customClass	string	''	自定义类名，便于做样式覆盖
onClose	() => void	—	关闭时回调（自动 / 主动 / destroy 都会触发）
key	string | number	—	标识，便于以同一 key 替换已存在的提示
placement	MessagePlacement	'top'	6 位置之一：top / topLeft / topRight / bottom / bottomLeft / bottomRight
role	'alert' | 'status'	'alert'	DOM role + aria-live（alert → assertive；status → polite）
pauseOnHover	boolean	true	鼠标悬停暂停自动关闭计时器

MessageGlobalConfig

通过 message.config({...}) 设置；优先级低于单次 open() 选项。

字段	类型	默认	说明
duration	number	3	默认停留时长（秒）
maxCount	number	Infinity	单 placement 最多并发条数，超出顶掉最旧
stack	boolean	false	视觉堆叠模式（容器加 --stack modifier）
pauseOnHover	boolean	true	全局默认 pauseOnHover
role	'alert' | 'status'	'alert'	全局默认 role
top	number | string	—	顶部偏移（仅作用于 top* placement）
bottom	number | string	—	底部偏移（仅作用于 bottom* placement）
getContainer	() => HTMLElement	body	自定义挂载父节点

MessageHandle

字段	类型	说明
close	() => void	主动关闭该提示