Message Box 消息弹框 ​

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

TIP

设计上消息弹框对应系统的 alert、confirm 与 prompt,内容应尽量简洁;复杂内容请使用对话框。

警告框 ​

阻断操作直至用户确认。

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

确认框 ​

用于请求用户确认。

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

输入框 ​

需要用户输入时使用。

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

使用 VNode ​

message 可为 VNode。

自定义 ​

可展示更丰富的内容。

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

使用 HTML 字符串 ​

message 支持 HTML 字符串。

将 dangerouslyUseHTMLString 设为 true 时按 HTML 解析 message。

WARNING

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

区分取消与关闭 ​

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

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

居中布局 ​

内容可居中展示:图标在标题上方(位于弹框内)、标题与描述文本居中,底部操作按钮居中排列。可通过 confirmButtonType / cancelButtonType 或 confirmButtonColor / cancelButtonColor 自定义按钮颜色。

将 center 设为 true 启用居中布局。

自定义图标 ​

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

自定义图标与颜色 ​

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

可拖拽 ​

消息弹框可拖拽。

draggable 为 true 时可拖拽;overflow 为 true 允许拖出视口。

全局方法 ​

完整引入 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'

对应方法:UMessageBox、UMessageBox.alert、UMessageBox.confirm、UMessageBox.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''
confirmButtonColor确定按钮自定义颜色string—
cancelButtonColor取消按钮自定义颜色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—