Message Box 消息弹框

模拟系统消息框的一组模态框,用于信息提示、确认操作与输入提示。

TIP

设计上消息弹框对应系统的 alertconfirmprompt,内容应尽量简洁;复杂内容请使用对话框

警告框

阻断操作直至用户确认。

调用 UMessageBox.alert 打开警告框,行为类似系统 alert,不可通过 ESC 或点击遮罩关闭。本例接收 messagetitle;关闭时返回 Promise。若目标环境不支持 Promise,可引入 polyfill 或改用回调(见示例)。

确认框

用于请求用户确认。

调用 UMessageBox.confirm 打开确认框,类似系统 confirm。第三个参数可传入 options 对象精细配置;type 表示类型,可选 primarysuccesserrorinfowarning。注意第二个参数 title 必须为字符串,若为对象则视为 options。本例使用 Promise 处理结果。

输入框

需要用户输入时使用。

调用 UMessageBox.prompt 打开输入框,类似系统 promptinputPattern 可指定正则;inputValidator 校验函数返回布尔或字符串,返回 false 或字符串表示失败,字符串会作为 inputErrorMessageinputPlaceholder 可自定义占位符。

使用 VNode

message 可为 VNode。

自定义

可展示更丰富的内容。

上述三个方法均为 UMessageBox 的封装。本例直接调用 UMessageBox,通过 showCancelButton 控制是否显示取消按钮,并用 cancelButtonClasscancelButtonText 自定义样式与文案(确定按钮亦有对应字段,完整列表见文末表格)。同时使用 beforeClose:在实例即将关闭时触发,可阻止关闭;参数为 actioninstancedone,可在关闭前操作实例(如为确定按钮开启 loading),调用 done 关闭;若未调用 done 则不会关闭。

使用 HTML 字符串

message 支持 HTML 字符串。

dangerouslyUseHTMLString 设为 true 时按 HTML 解析 message

WARNING

虽然 message 支持 HTML,但动态渲染不可信 HTML 易导致 XSS。启用 dangerouslyUseHTMLString 时请确保内容可信,切勿将用户输入直接作为 message

区分取消与关闭

某些场景下取消与关闭含义不同。

默认情况下,Promise 的 rejectcallback 在用户取消(点取消)与关闭(点关闭图标或遮罩、按 ESC)时参数均为 cancel。若 distinguishCancelAndClosetrue,上述两种操作参数分别为 cancelclose

居中布局

内容可居中展示。

center 设为 true 居中内容。

自定义图标

图标可为任意 Vue 组件或渲染函数(JSX)

自定义图标与颜色

icon 会覆盖 type 对应的内置图标,但仍可保留 type,以便头部图标使用与类型一致的主题色(如 type: 'primary' 配合主色)。

可拖拽

消息弹框可拖拽。

draggabletrue 时可拖拽;overflowtrue 允许拖出视口。

全局方法

完整引入 Uniboot UI 后,会在 app.config.globalProperties 注册 $msgbox$alert$confirm$prompt。在选项式 API 中可如本文示例调用:

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

应用上下文继承

消息弹框构造函数可传入 context 作为第二参数(若使用 alert/confirm/prompt 变体则为第四参数),以继承当前应用上下文。

ts
import { getCurrentInstance } from 'vue'
import { UMessageBox } from 'uniboot-ui'

// 在 setup 中
const { appContext } = getCurrentInstance()!
// 直接调用:
UMessageBox({}, appContext)
// 或使用变体:
UMessageBox.alert('Hello world!', 'Title', {}, appContext)

按需引入

ts
import { UMessageBox } from 'uniboot-ui'

对应方法:UMessageBoxUMessageBox.alertUMessageBox.confirmUMessageBox.prompt,参数与上文一致。

消息弹框 API

选项

名称说明类型默认值
autofocus打开时是否自动聚焦booleantrue
title标题string''
message内容string / VNode / Function
dangerouslyUseHTMLStringmessage 是否按 HTML 解析booleanfalse
type类型,用于图标展示enum''
icon自定义图标,覆盖 type 对应的内置图形;可与 type 同时传入以沿用该类型的图标颜色string / Component''
closeIcon自定义关闭图标,默认 Closestring / Component''
customClass自定义类名string''
customStyle自定义内联样式CSSProperties{}
modal是否显示遮罩booleantrue
modalClass遮罩自定义类名string
callback不使用 Promise 时的关闭回调Functionnull
showClose是否显示关闭图标booleanfalse
beforeClose关闭前回调,可阻止关闭Functionnull
distinguishCancelAndClose是否区分取消与关闭booleanfalse
lockScroll是否锁定 body 滚动booleantrue
showCancelButton是否显示取消按钮booleanfalse(confirm/prompt 调用时为 true)
showConfirmButton是否显示确定按钮booleantrue
cancelButtonText取消按钮文案stringCancel
confirmButtonText确定按钮文案stringOK
cancelButtonType取消按钮类型enum
confirmButtonType确定按钮类型enumprimary
cancelButtonLoadingIcon取消按钮加载图标string / ComponentLoading
confirmButtonLoadingIcon确定按钮加载图标string / ComponentLoading
cancelButtonClass取消按钮自定义类名string''
confirmButtonClass确定按钮自定义类名string''
closeOnClickModal点击遮罩是否关闭(alert 调用时默认 false)booleantrue(alert 时为 false)
closeOnPressEscape按 ESC 是否关闭(alert 调用时默认 false)booleantrue(alert 时为 false)
closeOnHashChange路由哈希变化时是否关闭booleantrue
showInput是否显示输入框(prompt 调用时为 true)booleanfalse(prompt 时为 true)
inputPlaceholder输入框占位符string''
inputType输入框类型,详见 MDNstringtext
inputValue输入框初始值string''
inputPattern输入校验正则regexpnull
inputValidator校验函数,返回布尔或字符串;返回字符串时作为错误信息Function/ undefinedundefined
inputErrorMessage校验失败提示stringIllegal input
center内容是否居中booleanfalse
draggable是否可拖拽booleanfalse
overflow可拖拽时是否允许超出视口booleanfalse
roundButton是否使用圆角按钮booleanfalse
buttonSize确定与取消按钮尺寸stringdefault
appendTo消息弹框挂载根元素CSSSelector / HTMLElement