MessageBox 消息弹框

模拟系统的消息提示框而实现的一套模态对话框组件，用于消息提示、确认消息和提交内容。MessageBox 提供了 alert、confirm 和 prompt 三种基本类型，支持多种自定义配置。

提示

从场景上说，MessageBox 的作用是美化系统自带的 alert、confirm 和 prompt，因此适合展示较为简单的内容。如果需要更复杂的交互，建议使用 Dialog 组件。

基础用法

最简单的消息提示，类似于系统的 alert。

确认消息

用于需要用户确认的操作，提供确认和取消两个选项。

提交内容

用于需要用户输入内容的场景，支持输入验证。可以使用 inputPattern 正则表达式或 inputValidator 函数来验证用户输入。

自定义验证

使用 inputValidator 属性可以自定义验证逻辑。

消息类型

支持四种消息类型：success（成功）、warning（警告）、info（信息）、error（错误），每种类型都有对应的图标和颜色。

自定义按钮

可以自定义确认和取消按钮的文字内容，以适应不同的业务场景。

关闭行为

可以控制用户通过点击遮罩层或按下 ESC 键关闭弹框的行为。

隐藏关闭按钮

在某些场景下，可以隐藏右上角的关闭按钮，强制用户通过底部按钮进行操作。

自定义样式

支持通过 customClass 和 customStyle 属性自定义弹框的外观样式。

使用方式

直接导入（推荐）

javascript

import { VkMessageBox } from "vakao-ui";

// 使用
VkMessageBox.alert("消息内容", "标题");
VkMessageBox.confirm("确认内容", "标题");
VkMessageBox.prompt("输入提示", "标题");

组件形式使用

除了函数式调用，也可以直接在模板中使用组件：

vue

<template>
  <VkMessageBox v-model:visible="visible" title="标题" message="消息内容" type="info" @action="handleAction" />
</template>

<script setup>
import { ref } from "vue";
import { VkMessageBox } from "vakao-ui";

const visible = ref(false);

const handleAction = (action, instance) => {
  console.log("用户操作:", action);
  visible.value = false;
};
</script>

全局方法

完整引入 Vakao UI 后，可以通过全局属性访问：

javascript

// main.js
import { createApp } from 'vue'
import VakaoUI from 'vakao-ui'

const app = createApp(App)
app.use(VakaoUI)

// 组件中使用
<script setup>
import { getCurrentInstance } from 'vue'

const { proxy } = getCurrentInstance()

const showAlert = () => {
  proxy.$alert('消息内容', '标题')
}
</script>

方法说明

基本方法

方法	说明	参数	返回值
`VkMessageBox.alert`	警告框	`(message, title?, options?)`	`Promise<{ action: 'confirm', instance, value? }>`
`VkMessageBox.confirm`	确认框	`(message, title?, options?)`	`Promise<{ action: 'confirm'\|'cancel', instance, value? }>`
`VkMessageBox.prompt`	输入框	`(message, title?, options?)`	`Promise<{ action: 'confirm'\|'cancel', instance, value? }>`
`VkMessageBox.close`	关闭当前弹框	`()`	`void`

参数说明

message: 消息内容（必填）
title: 标题（可选，默认为 "提示"）
options: 配置选项（可选）

回调模式使用

除了 Promise 模式，MessageBox 还支持回调模式，通过配置回调函数来处理用户操作。回调模式特别适合需要在用户操作后执行异步任务的场景。

onAction 回调

当用户点击按钮时触发，提供三个参数：

action: 用户操作类型 ('confirm' | 'cancel')
instance: MessageBox 实例对象
done: 关闭弹框的函数

javascript

VkMessageBox.confirm("确认提交表单吗？", "提交确认", {
  onAction: (action, instance, done) => {
    if (action === "confirm") {
      // 执行提交操作
      submitForm()
        .then(() => {
          console.log("提交成功");
          done(); // 关闭弹框
        })
        .catch(() => {
          console.log("提交失败");
          // 不调用 done()，保持弹框打开
        });
    } else {
      done(); // 直接关闭
    }
  },
});

onClose 回调

当弹框关闭时触发，适合执行清理操作：

beforeClose 回调

在弹框关闭前触发，可以进行验证或阻止关闭：

回调函数组合使用

多个回调可以同时使用，实现复杂的交互逻辑：

Promise 返回值

所有方法都返回 Promise 对象，便于处理用户操作结果：

javascript

// alert 方法
VkMessageBox.alert("操作成功", "提示")
  .then(({ action, instance, value }) => {
    console.log("用户点击了确定按钮", action); // 'confirm'
  })
  .catch(() => {
    console.log("用户关闭了弹框");
  });

// confirm 方法
VkMessageBox.confirm("确认删除吗？", "删除确认")
  .then(({ action, instance, value }) => {
    if (action === "confirm") {
      console.log("用户确认删除");
    } else {
      console.log("用户取消删除");
    }
  })
  .catch(() => {
    console.log("用户关闭了弹框");
  });

// prompt 方法
VkMessageBox.prompt("请输入用户名", "登录")
  .then(({ action, instance, value }) => {
    if (action === "confirm") {
      console.log("用户输入的内容:", value);
    }
  })
  .catch(() => {
    console.log("用户取消了输入");
  });

// 使用 async/await
async function handleConfirm() {
  try {
    const { action, value } = await VkMessageBox.prompt("请输入密码", "验证");
    if (action === "confirm") {
      console.log("密码:", value);
    }
  } catch (error) {
    console.log("用户取消操作");
  }
}

返回值说明

属性	说明	类型
action	用户操作类型 ('confirm' \| 'cancel')	string
instance	MessageBox 实例对象	object
value	输入框的值（仅 prompt 方法或有输入时）	string

常见用法示例

javascript

// 简单警告
VkMessageBox.alert("操作成功！");

// 带标题的确认
VkMessageBox.confirm("确定要删除吗？", "危险操作", {
  type: "warning",
});

// 输入验证
VkMessageBox.prompt("请输入用户名", "注册", {
  inputValidator: (value) => {
    if (!value) return "用户名不能为空";
    if (value.length < 3) return "用户名至少3个字符";
    return true;
  },
});

// 自定义样式
VkMessageBox.confirm("确认提交吗？", "提交确认", {
  customClass: "my-message-box",
  customStyle: { borderRadius: "10px" },
  confirmText: "立即提交",
  cancelText: "稍后再说",
});

HTML 内容渲染

如果需要在消息内容中使用 HTML，需要使用 VNode 而不是 HTML 字符串：

javascript

import { h } from "vue";
import { VkMessageBox } from "vakao-ui";

// ❌ 错误：HTML 字符串不会被解析
VkMessageBox.alert("<strong>警告：</strong>此操作不可逆！", "提示");

// ✅ 正确：使用 VNode
VkMessageBox.alert(h("div", [h("strong", { style: { color: "red" } }, "警告："), "此操作不可逆！"]), "提示");

// ✅ 或者使用 JSX（需要配置 JSX 支持）
VkMessageBox.alert(
  <div>
    <strong style={{ color: "red" }}>警告：</strong>
    此操作不可逆！
  </div>,
  "提示",
);

复杂 HTML 内容示例

javascript

import { h } from "vue";

// 创建包含多种元素的复杂内容
const complexMessage = h(
  "div",
  {
    style: { lineHeight: "1.6" },
  },
  [
    h("p", { style: { margin: "0 0 10px 0" } }, [h("strong", { style: { color: "#e74c3c" } }, "重要提醒："), "以下操作将会："]),
    h("ul", { style: { margin: "10px 0", paddingLeft: "20px" } }, [
      h("li", "删除所有相关数据"),
      h("li", "清空缓存信息"),
      h("li", "重置用户配置"),
    ]),
    h("p", { style: { margin: "10px 0 0 0", fontSize: "12px", color: "#666" } }, "此操作不可撤销，请谨慎操作！"),
  ],
);

VkMessageBox.confirm(complexMessage, "确认删除", {
  type: "warning",
  confirmText: "确认删除",
  cancelText: "取消",
});

API

配置选项 (Options)

参数	说明	类型	可选值	默认值
title	MessageBox 标题	string	—	提示
message	MessageBox 消息正文内容，支持字符串或 VNode	string / VNode	—	—
type	消息类型，用于显示图标	string	success / info / warning / error	info
customClass	MessageBox 的自定义类名	string	—	—
customStyle	MessageBox 的自定义样式	string / object	—	—
showClose	是否显示右上角关闭按钮	boolean	—	true
showConfirmButton	是否显示确定按钮	boolean	—	true
showCancelButton	是否显示取消按钮	boolean	—	false
confirmText	确定按钮的文本内容	string	—	确定
cancelText	取消按钮的文本内容	string	—	取消
closeOnClickModal	是否可通过点击遮罩关闭 MessageBox	boolean	—	true
closeOnPressEscape	是否可通过按下 ESC 键关闭 MessageBox	boolean	—	true
showInput	是否显示输入框	boolean	—	false
inputPlaceholder	输入框的占位符	string	—	—
inputValue	输入框的初始文本	string	—	—
inputPattern	输入框的校验表达式	regexp	—	—
inputValidator	输入框的校验函数。可以返回布尔值或字符串，若返回一个字符串, 则返回结果会被赋值给 inputErrorMessage	function	—	—
onAction	当用户点击按钮时的回调函数	function	—	—
onClose	当弹框关闭时的回调函数	function	—	—
beforeClose	关闭前的回调，返回 false 或 Promise.reject 时阻止关闭	function	—	—
inputErrorMessage	校验失败时的提示文本	string	—	—

注意事项

Promise vs 回调: 可以选择使用 Promise 模式或回调模式，两者可以同时使用
实例管理: 同一时间只能显示一个 MessageBox 实例
输入验证: 使用 inputValidator 进行输入验证，返回字符串表示错误信息
样式定制: 通过 customClass 和 customStyle 进行样式定制
关闭控制: 使用 beforeClose 可以阻止弹框关闭，适用于异步操作场景
HTML 渲染: 不支持 HTML 字符串解析，需要使用 VNode 来实现富文本内容

MessageBox 消息弹框 ​

基础用法 ​

确认消息 ​

提交内容 ​

自定义验证 ​

消息类型 ​

自定义按钮 ​

关闭行为 ​

隐藏关闭按钮 ​

自定义样式 ​

使用方式 ​

直接导入（推荐） ​

组件形式使用 ​

全局方法 ​

方法说明 ​

基本方法 ​

参数说明 ​

回调模式使用 ​

onAction 回调 ​

onClose 回调 ​

beforeClose 回调 ​

回调函数组合使用 ​

Promise 返回值 ​

返回值说明 ​

常见用法示例 ​

HTML 内容渲染 ​

复杂 HTML 内容示例 ​

API ​

配置选项 (Options) ​

注意事项 ​

MessageBox 消息弹框

基础用法

确认消息

提交内容

自定义验证

消息类型

自定义按钮

关闭行为

隐藏关闭按钮

自定义样式

使用方式

直接导入（推荐）

组件形式使用

全局方法

方法说明

基本方法

参数说明

回调模式使用

onAction 回调

onClose 回调

beforeClose 回调

回调函数组合使用

Promise 返回值

返回值说明

常见用法示例

HTML 内容渲染

复杂 HTML 内容示例

API

配置选项 (Options)

注意事项