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。
居中布局
内容可居中展示。
将 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 变体则为第四参数),以继承当前应用上下文。
import { getCurrentInstance } from 'vue'
import { UMessageBox } from 'uniboot-ui'
// 在 setup 中
const { appContext } = getCurrentInstance()!
// 直接调用:
UMessageBox({}, appContext)
// 或使用变体:
UMessageBox.alert('Hello world!', 'Title', {}, appContext)按需引入
import { UMessageBox } from 'uniboot-ui'对应方法:UMessageBox、UMessageBox.alert、UMessageBox.confirm、UMessageBox.prompt,参数与上文一致。
消息弹框 API
选项
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| autofocus | 打开时是否自动聚焦 | boolean | true |
| title | 标题 | string | '' |
| message | 内容 | string / VNode / Function | — |
| dangerouslyUseHTMLString | message 是否按 HTML 解析 | boolean | false |
| type | 类型,用于图标展示 | enum | '' |
| icon | 自定义图标,覆盖 type 对应的内置图形;可与 type 同时传入以沿用该类型的图标颜色 | string / Component | '' |
| closeIcon | 自定义关闭图标,默认 Close | string / Component | '' |
| customClass | 自定义类名 | string | '' |
| customStyle | 自定义内联样式 | CSSProperties | {} |
| modal | 是否显示遮罩 | boolean | true |
| modalClass | 遮罩自定义类名 | string | — |
| callback | 不使用 Promise 时的关闭回调 | Function | null |
| showClose | 是否显示关闭图标 | boolean | false |
| beforeClose | 关闭前回调,可阻止关闭 | Function | null |
| distinguishCancelAndClose | 是否区分取消与关闭 | boolean | false |
| lockScroll | 是否锁定 body 滚动 | boolean | true |
| showCancelButton | 是否显示取消按钮 | boolean | false(confirm/prompt 调用时为 true) |
| showConfirmButton | 是否显示确定按钮 | boolean | true |
| cancelButtonText | 取消按钮文案 | string | Cancel |
| confirmButtonText | 确定按钮文案 | string | OK |
| cancelButtonType | 取消按钮类型 | enum | — |
| confirmButtonType | 确定按钮类型 | enum | primary |
| cancelButtonLoadingIcon | 取消按钮加载图标 | string / Component | Loading |
| confirmButtonLoadingIcon | 确定按钮加载图标 | string / Component | Loading |
| cancelButtonClass | 取消按钮自定义类名 | string | '' |
| confirmButtonClass | 确定按钮自定义类名 | string | '' |
| closeOnClickModal | 点击遮罩是否关闭(alert 调用时默认 false) | boolean | true(alert 时为 false) |
| closeOnPressEscape | 按 ESC 是否关闭(alert 调用时默认 false) | boolean | true(alert 时为 false) |
| closeOnHashChange | 路由哈希变化时是否关闭 | boolean | true |
| showInput | 是否显示输入框(prompt 调用时为 true) | boolean | false(prompt 时为 true) |
| inputPlaceholder | 输入框占位符 | string | '' |
| inputType | 输入框类型,详见 MDN | string | text |
| inputValue | 输入框初始值 | string | '' |
| inputPattern | 输入校验正则 | regexp | null |
| inputValidator | 校验函数,返回布尔或字符串;返回字符串时作为错误信息 | Function/ undefined | undefined |
| inputErrorMessage | 校验失败提示 | string | Illegal input |
| center | 内容是否居中 | boolean | false |
| draggable | 是否可拖拽 | boolean | false |
| overflow | 可拖拽时是否允许超出视口 | boolean | false |
| roundButton | 是否使用圆角按钮 | boolean | false |
| buttonSize | 确定与取消按钮尺寸 | string | default |
| appendTo | 消息弹框挂载根元素 | CSSSelector / HTMLElement | — |