MessageBox 消息弹框

模拟系统原生体验的消息对话框，集成了 YH-UI 标志性的亚克力视觉语言、GPU 加速拖拽交互以及严谨的业务生命周期控制。

基础用法

提供了 alert、confirm 和 prompt 三种最常用的交互模式。

消息提示

确认对话框

提交内容

不同状态

用来显示「成功、警告、消息、错误」类的操作反馈。

成功状态

警告状态

错误状态

信息状态

自定义内容

message 属性支持传入 HTML 字符串或 VNode。

VNode 渲染

使用 HTML 片段

警告

dangerouslyUseHTMLString 属性虽然方便，但容易导致 XSS 攻击。请确保 message 的内容是可信的，永远不要将用户提交的内容赋值给 message 属性。

视觉与布局

YH-UI 旗舰级特性，提供磨砂玻璃质感、拖拽定位以及全方位的中轴对齐。

居中布局

可拖拽

异步关闭拦截

通过 beforeClose 钩子可以精准拦截退出动作。常用于处理异步接口逻辑，并由组件自动维护确认按钮的加载状态。

异步拦截

加载状态

通过 confirmButtonLoading 属性或在 beforeClose 钩子中手动操作 instance.confirmLoading = true，可以直接在确认按钮上显示加载动画。组件会自动处理按钮的禁用逻辑。

异步加载演示

全局默认配置

如果应用中大部分弹窗具有一致的视觉偏好（如全量开启亚克力特效），可以通过 setDefaults 一键启用全局配置，避免重复传参。

全局配置演示

在 Nuxt 中使用

YhMessageBox 已全面适配 Nuxt 3/4。作为一个指令式调用的组件，它在 SSR（服务端渲染）时会自动检测运行环境，确保弹窗逻辑仅在客户端执行。

Nuxt 中使用演示

注意事项：

• ✅ 全自动导入：在 Nuxt 项目中，YhMessageBox 及其别名函数会自动映射，无需手动显式 import。
• ✅ SSR 安全：函数内部已封装 process.client 检测，可放心在生命周期或方法中调用。
• 💡 样式同步：组件样式会通过 Nuxt 插件自动注入，确保首屏激活后视觉风格的连续性。

生产实践

在 Nuxt 生态中，推荐在 defineNuxtComponent 或 setup 逻辑中使用 YhMessageBox 进行业务拦截，配合 useFetch 的拦截器可以实现极佳的全局错误提示体验。

全局方法

如果你完整引入了 YH-UI，它会为 app.config.globalProperties 添加如下全局方法：$msgbox、$alert、$confirm 和 $prompt。 因此在 Vue 实例中可以采用本页面中的方式来调用 MessageBox。

• $msgbox(options)
• $alert(message, title, options) 或 $alert(message, options)
• $confirm(message, title, options) 或 $confirm(message, options)
• $prompt(message, title, options) 或 $prompt(message, options)

应用程序上下文继承

现在 MessageBox 接受构造器的 context 作为第二个 (如果你正在使用消息框变量的话) 参数。 这个参数允许你将当前应用的上下文注入到消息中，这将允许你继承应用程序的所有属性。

import { getCurrentInstance } from 'vue'
import { YhMessageBox } from '@yh-ui/yh-ui'

// 在你的 setup 方法中
const { appContext } = getCurrentInstance()!
// 你可以像这样传递参数：
YhMessageBox({}, appContext)
// 或者正在使用不同的调用方式
YhMessageBox.alert('Hello world!', 'Title', {}, appContext)

API

方法

方法名	说明	参数类型	返回值
alert	弹出消息提示框	(message, title?, options?, appContext?)	Promise<void>
confirm	弹出操作确认框	(message, title?, options?, appContext?)	Promise<MessageBoxAction>
prompt	弹出内容输入框	(message, title?, options?, appContext?)	Promise<{ value, action }>
setDefaults	修改全局默认配置项	(defaults: MessageBoxOptions)	—

MessageBoxOptions

参数	说明	类型	默认值
title	标题	string	提示
message	内容	string | VNode | (() => VNode)	—
type	弹窗类型	'alert' | 'confirm' | 'prompt'	—
iconType	状态图标类型	'success' | 'warning' | 'info' | 'error'	—
icon	自定义图标	string | Component | VNode	—
width	弹窗宽度	string | number	420
dangerouslyUseHTMLString	是否将 message 渲染为 HTML	boolean	false
showClose	是否显示右上角关闭按钮	boolean	true
showConfirmButton	是否显示确认按钮	boolean	true
showCancelButton	是否显示取消按钮	boolean	true
confirmButtonText	确认按钮文案	string	确定
cancelButtonText	取消按钮文案	string	取消
closeOnClickModal	点击遮罩层是否关闭	boolean	true
closeOnPressEscape	按下 ESC 是否关闭	boolean	true
lockScroll	是否锁定滚动条	boolean	true
glass	是否开启亚克力玻璃模式	boolean	false
center	是否将内容居中排列	boolean	false
roundButton	是否采用圆角按钮	boolean	false
draggable	是否支持拖拽弹窗	boolean	false
draggableBoundary	是否防止拖拽超出可视区域	boolean	true
customClass	自定义类名	string	—
inputPlaceholder	输入框占位符 (仅 prompt)	string	—
inputValue	输入框初始值 (仅 prompt)	string	—
inputPattern	输入框校验正则表达式 (仅 prompt)	RegExp	—
inputValidator	输入框自定义校验函数 (仅 prompt)	(value: string) => boolean | string	—
inputErrorMessage	校验错误提示 (仅 prompt)	string	—
beforeClose	关闭前的钩子	(action, instance, done) => void	—
callback	关闭后的回调	(action, instance) => void	—
appContext	应用上下文 (Vue Context)	AppContext	—
autofocus	是否在打开时自动获取焦点	boolean	true
appendTo	设置组件的根元素	string | HTMLElement	document.body
confirmButtonLoading	确认按钮是否显示加载中状态	boolean	false
cancelButtonLoading	取消按钮是否显示加载中状态	boolean	false
loadingIcon	自定义加载图标	string | Component | VNode	—

MessageBoxInstance (instance in beforeClose)

属性/方法	说明	类型
confirmLoading	确认按钮的加载状态	boolean
cancelLoading	取消按钮的加载状态	boolean
open	打开弹窗	(options: MessageBoxOptions) => void
close	关闭弹窗	() => void

主题变量 (CSS Variables)

变量名	说明	默认值
--yh-scrollbar-width	当前系统的滚动条宽度 (自动注入)	—
--yh-bg-color-overlay	弹窗背景色	var(--yh-bg-color-overlay)
--yh-text-color-primary	标题颜色	var(--yh-text-color-primary)