FxMsgBox 消息确认框

命令式消息确认框，提供 confirm / alert / prompt 三种用法，返回 Promise。不依赖任何 UI 框架，基于 fxOverlay + fxFocusTrap，样式走 @fx/styles token，图标走 @fx-core/icon（ep:xxx）。

基础用法（confirm）

以「确认 / 取消」为目的的二次确认。点击确定 resolve 'confirm'，点击取消 / 关闭 reject 'cancel'（distinguishCancelAndClose 时区分 'close'）。

<template>
  <FxBtn type="primary" @click="open">点击打开确认框</FxBtn>
</template>

<script setup lang="ts">
import { fxMsgBox, fxMsg } from "@fx/components"

function open() {
  fxMsgBox
    .confirm("此操作将永久删除该文件，是否继续？", "警告", {
      confirmButtonText: "确定",
      cancelButtonText: "取消",
      type: "warning",
    })
    .then(() => {
      fxMsg.success("删除完成")
    })
    .catch(() => {
      fxMsg.info("已取消删除")
    })
}
</script>

提示（alert）

仅展示信息、单个确定按钮。alert 默认 closeOnClickModal / closeOnPressEscape 为 false。也可改用 callback 替代 Promise 接收结果。

<template>
  <FxBtn @click="open">点击打开消息框</FxBtn>
</template>

<script setup lang="ts">
import { fxMsgBox, fxMsg } from "@fx/components"
import type { Action } from "@fx/components"

function open() {
  fxMsgBox.alert("这是一段内容", "标题", {
    // 若需关闭自动聚焦：autofocus: false,
    confirmButtonText: "确定",
    callback: (action: Action) => {
      fxMsg.info(`action: ${action}`)
    },
  })
}
</script>

输入（prompt）

带输入框的确认，resolve { value, action }。可用 inputPattern 或 inputValidator 校验。

<template>
  <FxBtn @click="open">点击打开输入框</FxBtn>
</template>

<script setup lang="ts">
import { fxMsgBox, fxMsg } from "@fx/components"

function open() {
  fxMsgBox
    .prompt("请输入邮箱", "提示", {
      confirmButtonText: "确定",
      cancelButtonText: "取消",
      inputPlaceholder: "请输入邮箱",
      inputPattern:
        /[\w!#$%&'*+/=?^_`{|}~-]+(?:\.[\w!#$%&'*+/=?^_`{|}~-]+)*@(?:[\w](?:[\w-]*[\w])?\.)+[\w](?:[\w-]*[\w])?/,
      inputErrorMessage: "邮箱格式不正确",
    })
    .then(({ value }) => {
      fxMsg.success(`邮箱为：${value}`)
    })
    .catch(() => {
      fxMsg.info("已取消输入")
    })
}
</script>

不同状态

通过 type 显示 success / warning / info / error 图标与配色。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn @click="open('success')">Success</FxBtn>
    <FxBtn @click="open('warning')">Warning</FxBtn>
    <FxBtn @click="open('info')">Info</FxBtn>
    <FxBtn @click="open('error')">Error</FxBtn>
  </div>
</template>

<script setup lang="ts">
import { fxMsgBox } from "@fx/components"

function open(type: "success" | "warning" | "info" | "error") {
  fxMsgBox.alert("这是一段内容", "标题", { type }).catch(() => {})
}
</script>

内容居中

center 让标题、图标、按钮区域居中。

<template>
  <FxBtn @click="open">点击打开消息框</FxBtn>
</template>

<script setup lang="ts">
import { fxMsgBox, fxMsg } from "@fx/components"

function open() {
  fxMsgBox
    .confirm("此操作将永久删除该文件，是否继续？", "警告", {
      confirmButtonText: "确定",
      cancelButtonText: "取消",
      type: "warning",
      center: true,
    })
    .then(() => {
      fxMsg.success("删除完成")
    })
    .catch(() => {
      fxMsg.info("已取消删除")
    })
}
</script>

自定义图标

icon 直接传图标名（图标集前缀，如 ep:delete），无需 markRaw。

<template>
  <FxBtn @click="open">点击打开消息框</FxBtn>
</template>

<script setup lang="ts">
import { fxMsgBox, fxMsg } from "@fx/components"

function open() {
  fxMsgBox
    .confirm("此操作将永久删除该文件，是否继续？", "警告", {
      confirmButtonText: "确定",
      cancelButtonText: "取消",
      type: "warning",
      // fx 增强：icon 直接传图标名（图标集前缀），无需 markRaw
      icon: "ep:delete",
    })
    .then(() => {
      fxMsg.success("删除完成")
    })
    .catch(() => {
      fxMsg.info("已取消删除")
    })
}
</script>

使用 HTML 字符串

dangerouslyUseHTMLString: true 时把 message 作为 HTML 渲染。注意：动态拼接 HTML 存在 XSS 风险，仅用于可信内容。

<template>
  <FxBtn @click="open">点击打开消息框</FxBtn>
</template>

<script setup lang="ts">
import { fxMsgBox } from "@fx/components"

function open() {
  fxMsgBox.alert(
    "<strong>这是 <i>HTML</i> 字符串</strong>",
    "HTML 字符串",
    {
      dangerouslyUseHTMLString: true,
    },
  )
}
</script>

自定义内容（VNode）

message 支持 VNode 或渲染函数，可渲染任意内容（含表单、动态 props）。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn @click="open">普通 VNode</FxBtn>
    <FxBtn @click="open1">动态 props</FxBtn>
  </div>
</template>

<script setup lang="ts">
import { h, ref } from "vue"
import { fxMsgBox, FxSwitch } from "@fx/components"

function open() {
  fxMsgBox({
    title: "消息",
    message: h("p", null, [
      h("span", null, "内容可以是 "),
      h("i", { style: "color: var(--fx-color-primary)" }, "VNode"),
    ]),
  }).catch(() => {})
}

const checked = ref<boolean | string | number>(false)

function open1() {
  fxMsgBox({
    title: "消息",
    // 包含动态 props 的 VNode 应以函数形式传入
    message: () =>
      h(FxSwitch, {
        modelValue: checked.value,
        "onUpdate:modelValue": (val: boolean | string | number) => {
          checked.value = val
        },
      }),
  }).catch(() => {})
}
</script>

自定义按钮 + action 处理器

message 作为函数时，参数会注入 { confirm, cancel, close } 三个处理器，可在自定义内容里触发对应动作。

<template>
  <FxBtn @click="open">点击打开消息框</FxBtn>
</template>

<script setup lang="ts">
import { h } from "vue"
import { fxMsgBox, fxMsg, FxBtn } from "@fx/components"

function open() {
  fxMsgBox
    .confirm(
      ({ confirm, cancel, close }) => {
        return h("div", [
          h(
            "p",
            { style: "margin: 0 0 8px" },
            "通过 message 渲染函数自定义按钮，并接入 action 处理器",
          ),
          h(
            FxBtn,
            { type: "primary", onClick: () => confirm() },
            () => "Resolve",
          ),
          h(
            FxBtn,
            { type: "danger", onClick: () => cancel() },
            () => "Reject",
          ),
          h(FxBtn, { onClick: () => close() }, () => "Close"),
        ])
      },
      {
        title: "消息",
        showConfirmButton: false,
        showCancelButton: false,
        distinguishCancelAndClose: true,
      },
    )
    .then((action) => {
      fxMsg.success(`resolved: ${action}`)
    })
    .catch((reason) => {
      fxMsg.error(`rejected: ${reason}`)
    })
}
</script>

关闭前处理（beforeClose）

beforeClose(action, instance, done) 拦截关闭，常用于「确定后异步提交、完成再关闭」，可结合 instance.confirmButtonLoading 显示加载态。

<template>
  <FxBtn @click="open">点击打开消息框</FxBtn>
</template>

<script setup lang="ts">
import { h } from "vue"
import { fxMsgBox, fxMsg } from "@fx/components"
import type { MessageBoxState } from "@fx/components"

function open() {
  fxMsgBox({
    title: "消息",
    message: h("p", null, [
      h("span", null, "内容可以是 "),
      h("i", { style: "color: var(--fx-color-primary)" }, "VNode"),
    ]),
    showCancelButton: true,
    confirmButtonText: "确定",
    cancelButtonText: "取消",
    beforeClose: (action, instance: MessageBoxState, done) => {
      if (action === "confirm") {
        instance.confirmButtonLoading = true
        instance.confirmButtonText = "加载中..."
        setTimeout(() => {
          done()
          setTimeout(() => {
            instance.confirmButtonLoading = false
          }, 300)
        }, 3000)
      } else {
        done()
      }
    },
  })
    .then((action) => {
      fxMsg.info(`action: ${action}`)
    })
    .catch(() => {})
}
</script>

区分取消与关闭

distinguishCancelAndClose: true 后，点击遮罩 / ESC / 关闭按钮 reject 'close'，点击取消按钮 reject 'cancel'。

<template>
  <FxBtn @click="open">点击打开消息框</FxBtn>
</template>

<script setup lang="ts">
import { fxMsgBox, fxMsg } from "@fx/components"
import type { Action } from "@fx/components"

function open() {
  fxMsgBox
    .confirm("存在未保存的改动，是否保存并继续？", "确认", {
      distinguishCancelAndClose: true,
      confirmButtonText: "保存",
      cancelButtonText: "放弃改动",
    })
    .then(() => {
      fxMsg.info("改动已保存，即将跳转到新路由")
    })
    .catch((action: Action) => {
      fxMsg.info(
        action === "cancel"
          ? "改动已放弃，即将跳转到新路由"
          : "留在当前路由",
      )
    })
}
</script>

可拖拽

draggable 开启拖拽，overflow 允许拖出视口；可配合 customClass 自定义拖拽态样式。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn @click="open1">可拖拽的消息框</FxBtn>
    <FxBtn @click="open2">可超出视口拖拽的消息框</FxBtn>
    <FxBtn @click="open3">自定义拖拽样式</FxBtn>
  </div>
</template>

<script setup lang="ts">
import { fxMsgBox, fxMsg } from "@fx/components"

function open1() {
  fxMsgBox
    .confirm("此操作将永久删除该文件，是否继续？", "警告", {
      confirmButtonText: "确定",
      cancelButtonText: "取消",
      type: "warning",
      draggable: true,
    })
    .then(() => fxMsg.success("删除完成"))
    .catch(() => fxMsg.info("已取消删除"))
}

function open2() {
  fxMsgBox
    .confirm("此操作将永久删除该文件，是否继续？", "警告", {
      confirmButtonText: "确定",
      cancelButtonText: "取消",
      type: "warning",
      draggable: true,
      overflow: true,
    })
    .then(() => fxMsg.success("删除完成"))
    .catch(() => fxMsg.info("已取消删除"))
}

function open3() {
  fxMsgBox
    .confirm(
      "此消息框带有自定义拖拽样式，试试拖动它查看效果！",
      "自定义拖拽样式",
      {
        confirmButtonText: "确定",
        cancelButtonText: "取消",
        type: "info",
        draggable: true,
        customClass: "custom-dragging-msg-box",
      },
    )
    .then(() => fxMsg.success("操作完成"))
    .catch(() => fxMsg.info("已取消操作"))
}
</script>

<style scoped>
:deep(.custom-dragging-msg-box).is-dragging {
  border: 2px dashed var(--fx-color-primary);
  opacity: 0.65;
}
</style>

局部引入

import { fxMsgBox } from "@fx/components"

// 三种快捷方式
fxMsgBox.alert(message, title?, options?)
fxMsgBox.confirm(message, title?, options?)
fxMsgBox.prompt(message, title?, options?)

// 通用入口
fxMsgBox(options)
// 关闭所有
fxMsgBox.close()

Options

名称	说明	类型	默认值
autofocus	打开时是否自动聚焦（确定按钮 / 输入框）	boolean	true
title	标题，传 null/undefined 不渲染标题栏	string	—
message	内容	string | VNode | ((h: ActionHandlers) => VNode)	—
type	状态类型（决定图标与配色）	'primary' | 'success' | 'warning' | 'info' | 'error'	—
icon	自定义状态图标。字符串为 IconString 类型（即 FxIcon 图标名，如 ep:edit、ant-design:home、svg:xxx），亦可传组件	string | Component	—
closeIcon	自定义关闭图标。字符串为 IconString 类型（即 FxIcon 图标名，如 ep:edit、ant-design:home、svg:xxx），亦可传组件	string | Component	ep:close
dangerouslyUseHTMLString	message 作为 HTML 字符串渲染	boolean	false
showClose	是否显示关闭按钮	boolean	true
showConfirmButton / showCancelButton	显示确定 / 取消按钮	boolean	true / false
confirmButtonText / cancelButtonText	按钮文字	string	确定 / 取消
confirmButtonType / cancelButtonType	按钮类型，传 'text' 渲染为文本按钮	ButtonType	primary / —
confirmButtonClass / cancelButtonClass	按钮自定义类名	string	—
confirmButtonDisabled	禁用确定按钮	boolean	false
confirmButtonLoading / cancelButtonLoading	按钮加载态	boolean	false
confirmButtonLoadingIcon / cancelButtonLoadingIcon	按钮加载图标	string | Component	ep:loading
buttonSize	按钮尺寸	'small' | 'default' | 'large'	—
roundButton	圆角按钮	boolean	false
center	内容居中	boolean	false
draggable / overflow	可拖拽 / 允许超出视口	boolean	false
modal / modalClass / lockScroll	遮罩 / 遮罩类名 / 锁定滚动	boolean | string	true / — / true
closeOnClickModal / closeOnPressEscape / closeOnHashChange	点击遮罩 / ESC / hash 变化时关闭	boolean	true / true / true
beforeClose	关闭前回调，调 done() 才真正关闭	(action, instance, done) => void	—
callback	不用 Promise 时的回调	(value, action) => any	—
distinguishCancelAndClose	区分取消与关闭	boolean	false
customClass / customStyle	自定义类名 / 行内样式	string | CSSProperties	—
appendTo	挂载容器	string | HTMLElement	body

prompt 专属

名称	说明	类型	默认值
showInput	是否显示输入框	boolean	false
inputPlaceholder	输入框占位	string	—
inputType	输入框类型，textarea 渲染为多行	string	text
inputValue	输入框初始值	string	—
inputPattern	输入正则校验	RegExp	—
inputValidator	输入校验函数，返回 false 用默认错误，返回字符串作为错误信息	(value) => boolean | string	—
inputErrorMessage	校验失败提示	string	输入不合法

Slots

名称	说明	参数
default	内容区默认插槽，覆盖 message	—

命令式调用时通过 message 传 VNode / 渲染函数等价于使用默认插槽。

Events

名称	说明	回调参数
action	触发某个动作时（confirm / cancel / close）	(action: Action)
vanish	关闭动画结束后（实例销毁）	—

Methods

名称	说明
fxMsgBox.close()	关闭所有命令式实例

返回值

• confirm / alert：resolve Action（'confirm'）；取消 / 关闭 reject 'cancel'（distinguishCancelAndClose 时关闭为 'close'）
• prompt：resolve { value: string, action: 'confirm' }；取消 / 关闭同上

全局属性

安装插件后可用：$fxMsgBox / $fxAlert / $fxConfirm / $fxPrompt。

实现说明

• UI 框架无关：遮罩用内置 fxOverlay、焦点陷阱用 fxFocusTrap，输入框使用原生 input / textarea（不依赖第三方表单组件），按钮使用 FxBtn，确保整组件可跨 UI 框架复用。
• 图标体系：状态图标与关闭图标统一走 @fx-core/icon。type 映射 success → ep:success-filled、warning → ep:warning-filled、info → ep:info-filled、error → ep:circle-close-filled，并按 --color-success / --color-warning / --color-info / --color-danger 着色。
• 图标参数双形态（fx 增强）：icon / closeIcon / loadingIcon 既可传图标名字符串（推荐，无需 markRaw），也可传组件对象；命令式入口对组件对象自动 markRaw，模板内字符串图标走 FxIcon、组件对象原样透传。
• 命令式实例管理：messageInstance 维护当前所有活跃实例，close() 遍历 doClose() 并清空；onVanish（动画 after-leave）负责卸载 vnode 与释放引用，避免内存泄漏。
• prompt 校验链：先 inputPattern 正则，再 inputValidator 函数；inputValidator 返回字符串时作为错误信息。inputValue 变化时自动重新校验。
• 关闭前拦截：beforeClose(action, instance, done) 不调 done() 则不关闭，配合 instance.confirmButtonLoading = true 可实现「异步提交完成后再关闭」。
• action 区分：distinguishCancelAndClose 决定遮罩 / ESC / 关闭按钮触发的是 'cancel' 还是 'close'，影响 Promise reject 的值。
• 无障碍：根节点 role="dialog"、aria-modal，按 showInput 切换 aria-describedby；prompt 下 message 渲染为 <label for=inputId>；输入框带 aria-invalid。focus trap 在 release-requested（ESC）时按 closeOnPressEscape 决定是否关闭。
• 样式 token：所有取值走 @fx/styles token（--color-* / --radius-* / --shadow-popup / --duration-*），盒体规格（宽 420px、圆角 4px、内边距 12px、标题 18px、内容 14px、错误 12px、行高 24px）与设计基线一致；遮罩层以伪元素垂直居中，进出动画 msgbox-fade。
• fx 增强（保留）：按钮区用 gap 排布；错误提示区预留 min-height 防抖动；输入框 textarea 支持 resize: vertical 与最小高度。