FxDialog 对话框

在当前页面正中弹出浮层，承载表单、确认、详情等内容。不依赖任何 UI 框架，扩展「全屏切换按钮」与 header-extra 插槽。

基础用法

通过 v-model 双向绑定控制显隐，title 设置标题，footer 插槽放置操作按钮。before-close 可拦截关闭。

<template>
  <FxBtn type="primary" @click="visible = true">打开</FxBtn>
  <FxDialog v-model="visible" title="提示" :before-close="handleBeforeClose">
    <span>这是一段内容</span>
    <template #footer>
      <FxBtn @click="visible = false">取消</FxBtn>
      <FxBtn type="primary" @click="visible = false">确认</FxBtn>
    </template>
  </FxDialog>
</template>

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

const visible = ref(false)

// 点击蒙版 / ESC / 关闭按钮时弹出命令式确认框（底部按钮关闭不走此回调）
const handleBeforeClose = (done: (cancel?: boolean) => void) => {
  fxMsgBox
    .confirm("确认关闭此对话框吗？", "提示")
    .then(() => done())
    .catch(() => done(true))
}
</script>

自定义内容

Dialog 的内容可以是任意内容，包括表单、表格等。

<template>
  <FxBtn type="primary" @click="visible = true">打开</FxBtn>
  <FxDialog v-model="visible" title="个人信息" width="500">
    <div class="flex flex-col gap-3">
      <FxInput v-model="form.name" placeholder="请输入姓名" />
      <FxInput v-model="form.address" placeholder="请输入地址" />
    </div>
    <template #footer>
      <FxBtn @click="visible = false">取消</FxBtn>
      <FxBtn type="primary" @click="visible = false">提交</FxBtn>
    </template>
  </FxDialog>
</template>

<script setup lang="ts">
import { reactive, ref } from "vue"

const visible = ref(false)
const form = reactive({ name: "", address: "" })
</script>

自定义标题

header 插槽可自定义标题区。为保持无障碍，请配合 title 属性，或用 titleId 作用域参数指定标题元素。

<template>
  <FxBtn type="primary" @click="visible = true">打开</FxBtn>
  <FxDialog v-model="visible">
    <template #header="{ close, titleId, titleClass }">
      <span :id="titleId" :class="titleClass">自定义标题</span>
      <FxIcon name="ep:star-filled" style="color: var(--fx-color-warning)" />
      <FxBtn text size="small" style="margin-left: auto" @click="close">
        自定义按钮
      </FxBtn>
    </template>
    <span>通过 header 插槽自定义标题区，header-extra、全屏按钮、关闭按钮仍保留。</span>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const visible = ref(false)
</script>

嵌套对话框

Dialog 嵌套时，内层需设置 append-to-body，以正确层叠渲染。

<template>
  <FxBtn type="primary" @click="outer = true">打开外层</FxBtn>

  <FxDialog v-model="outer" title="外层对话框" width="800">
    <span>这是外层对话框的内容</span>
    <FxDialog
      v-model="inner"
      width="500"
      title="内层对话框"
      append-to-body
    >
      <span>这是内层对话框的内容</span>
    </FxDialog>
    <template #footer>
      <FxBtn @click="outer = false">取消</FxBtn>
      <FxBtn type="primary" @click="inner = true">打开内层</FxBtn>
    </template>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const outer = ref(false)
const inner = ref(false)
</script>

内容居中

设置 center 后，header 与 footer 水平居中（不影响 body）。

<template>
  <FxBtn type="primary" @click="visible = true">打开</FxBtn>
  <FxDialog v-model="visible" title="内容居中" center>
    <span>设置 center 后，header 与 footer 水平居中（不影响 body）。</span>
    <template #footer>
      <FxBtn type="primary" @click="visible = false">确认</FxBtn>
    </template>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const visible = ref(false)
</script>

水平垂直居中

设置 align-center 使弹窗水平 + 垂直居中，此时 top 不生效。

<template>
  <FxBtn type="primary" @click="visible = true">打开</FxBtn>
  <FxDialog v-model="visible" title="水平垂直居中" align-center>
    <span>设置 align-center 后，弹窗水平 + 垂直居中（此时 top 不生效）。</span>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const visible = ref(false)
</script>

关闭时销毁

开启 destroy-on-close 后，关闭时销毁默认插槽内容，再次打开重新挂载。

<template>
  <FxBtn type="primary" @click="visible = true">打开</FxBtn>
  <FxDialog v-model="visible" title="关闭时销毁" destroy-on-close>
    <span>开启 destroy-on-close 后，关闭时会销毁默认插槽内容，再次打开重新挂载（触发子组件 mounted）。</span>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const visible = ref(false)
</script>

可拖拽

设置 draggable 开启拖拽，overflow 允许拖出可视区。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn @click="open('draggable')">可拖拽</FxBtn>
    <FxBtn @click="open('overflow')">可拖出视口</FxBtn>
    <FxBtn @click="open('custom')">自定义拖拽样式</FxBtn>
  </div>

  <FxDialog
    v-model="visible"
    title="提示"
    width="500"
    draggable
    :overflow="overflow"
    :class="{ 'custom-dragging-style': custom }"
  >
    <span>{{ message }}</span>
    <template #footer>
      <FxBtn @click="visible = false">取消</FxBtn>
      <FxBtn type="primary" @click="visible = false">确认</FxBtn>
    </template>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const visible = ref(false)
const overflow = ref(false)
const custom = ref(false)
const message = ref("")

function open(type: "draggable" | "overflow" | "custom") {
  overflow.value = type === "overflow"
  custom.value = type === "custom"
  message.value =
    type === "overflow"
      ? "可拖出视口的拖拽对话框，允许拖动到屏幕边缘之外。"
      : type === "custom"
        ? "自定义拖拽样式的对话框，拖动时显示虚线边框。"
        : "这是一个可拖拽的对话框，按住标题栏即可移动。"
  visible.value = true
}
</script>

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

全屏

fullscreen 控制是否全屏。FxDialog 额外提供：fullscreen-button（默认开启，显示标题栏全屏切换按钮）、default-fullscreen（打开时默认全屏）、v-model:fullscreen（受控双向）。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn @click="staticVisible = true">静态全屏 (fullscreen)</FxBtn>
    <FxBtn type="primary" @click="open(false)">打开弹窗</FxBtn>
    <FxBtn @click="open(true)">默认全屏打开</FxBtn>
  </div>

  <!-- 静态全屏：fullscreen 属性直接置为 true -->
  <FxDialog v-model="staticVisible" fullscreen title="静态全屏">
    <span>设置 fullscreen 属性为 true，弹窗始终全屏显示。</span>
    <template #footer>
      <FxBtn @click="staticVisible = false">取消</FxBtn>
      <FxBtn type="primary" @click="staticVisible = false">确认</FxBtn>
    </template>
  </FxDialog>

  <!-- 全屏切换（扩展）：标题栏全屏按钮 + 受控 v-model:fullscreen -->
  <FxDialog
    v-model="visible"
    v-model:fullscreen="fullscreen"
    title="全屏切换"
  >
    <p>点击标题栏右侧的「全屏 / 取消全屏」按钮切换。</p>
    <p>当前状态：{{ fullscreen ? "全屏" : "普通" }}</p>
    <template #footer>
      <FxBtn @click="visible = false">取消</FxBtn>
    </template>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const staticVisible = ref(false)
const visible = ref(false)
const fullscreen = ref(false)

function open(defaultFullscreen: boolean) {
  fullscreen.value = defaultFullscreen
  visible.value = true
}
</script>

标题栏额外按钮（扩展）

header-extra 插槽位于全屏按钮左侧，用于放置刷新、导出、设置等自定义按钮。

<template>
  <FxBtn type="primary" @click="visible = true">打开</FxBtn>
  <FxDialog v-model="visible" title="自定义工具">
    <template #header-extra>
      <FxBtn text size="small">刷新</FxBtn>
      <FxBtn text size="small">导出</FxBtn>
      <FxBtn text size="small">设置</FxBtn>
    </template>
    <span>header-extra 插槽位于全屏按钮左侧，用于放置自定义操作按钮。</span>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const visible = ref(false)
</script>

遮罩

modal 为 false 时隐藏遮罩；modal-class 自定义遮罩样式；modal-penetrable 使遮罩可点击穿透（需 modal=false）。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn @click="open('hidden')">隐藏遮罩 (modal=false)</FxBtn>
    <FxBtn @click="open('custom')">自定义遮罩 (modal-class)</FxBtn>
    <FxBtn @click="open('penetrable')">遮罩可穿透 (modal-penetrable)</FxBtn>
  </div>

  <FxDialog
    v-model="visible"
    title="遮罩"
    :modal="modal"
    :modal-penetrable="penetrable"
    :modal-class="customMask ? 'demo-dialog-mask' : ''"
    :append-to-body="!modal"
  >
    <span>modal 控制遮罩显隐；modal-class 自定义遮罩样式；modal-penetrable 使遮罩可点击穿透（需 modal=false）。</span>
    <template #footer>
      <FxBtn @click="visible = false">取消</FxBtn>
      <FxBtn type="primary" @click="visible = false">确认</FxBtn>
    </template>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const visible = ref(false)
const modal = ref(true)
const penetrable = ref(false)
const customMask = ref(false)

function open(type: "hidden" | "custom" | "penetrable") {
  customMask.value = type === "custom"
  penetrable.value = type === "penetrable"
  // 隐藏遮罩 / 可穿透时关闭遮罩；自定义遮罩时仍保留遮罩以便看到样式
  modal.value = type !== "hidden"
  visible.value = true
}
</script>

<style>
.demo-dialog-mask {
  background-color: var(--fx-color-mask) !important;
}
</style>

自定义动画

transition 接受动画名字符串或 Vue Transition 配置对象。Dialog 通过 Teleport 渲染到 body，动画类需用全局样式定义。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn @click="open('fade')">默认</FxBtn>
    <FxBtn @click="open('scale')">缩放</FxBtn>
    <FxBtn @click="open('slide')">滑动</FxBtn>
    <FxBtn @click="open('bounce')">弹跳</FxBtn>
    <FxBtn @click="openWithObject">对象配置</FxBtn>
  </div>

  <FxDialog
    v-model="visible"
    :title="`${currentLabel} 动画对话框`"
    width="30%"
    :transition="transitionConfig"
  >
    <div>
      <p>当前动画：<strong>{{ currentLabel }}</strong></p>
      <p>本示例演示 {{ currentLabel }} 动画效果。</p>
      <p v-if="isObjectConfig">
        <strong>使用对象配置：</strong>
        <code class="config-code">{{ JSON.stringify(transitionConfig, null, 2) }}</code>
      </p>
    </div>
    <template #footer>
      <FxBtn @click="visible = false">取消</FxBtn>
      <FxBtn type="primary" @click="visible = false">确认</FxBtn>
    </template>
  </FxDialog>
</template>

<script setup lang="ts">
import { computed, ref } from "vue"
import type { DialogTransition } from "@fx/components"

const visible = ref(false)
const currentLabel = ref("默认")
const currentType = ref("fade")
const isObjectConfig = ref(false)

const transitionConfig = computed<DialogTransition>(() => {
  if (isObjectConfig.value) {
    return {
      name: "dialog-custom-object",
      appear: true,
      mode: "out-in",
      duration: 500,
    }
  }
  return `dialog-${currentType.value}`
})

const labelMap: Record<string, string> = {
  fade: "默认",
  scale: "缩放",
  slide: "滑动",
  bounce: "弹跳",
}

const open = (type: string) => {
  currentType.value = type
  currentLabel.value = labelMap[type] ?? type
  isObjectConfig.value = false
  visible.value = true
}

const openWithObject = () => {
  currentLabel.value = "对象配置"
  isObjectConfig.value = true
  visible.value = true
}
</script>

<style>
.config-code {
  display: block;
  margin-top: 8px;
  padding: 4px 8px;
  border-radius: var(--fx-border-radius-base);
  background: var(--fx-color-surface-muted);
  font-size: 12px;
}

/* 缩放 */
.dialog-scale-enter-active,
.dialog-scale-leave-active,
.dialog-scale-enter-active .fx-dialog,
.dialog-scale-leave-active .fx-dialog {
  transition: all 0.2s cubic-bezier(0.645, 0.045, 0.355, 1);
}
.dialog-scale-enter-from,
.dialog-scale-leave-to {
  opacity: 0;
}
.dialog-scale-enter-from .fx-dialog,
.dialog-scale-leave-to .fx-dialog {
  transform: scale(0.5);
  opacity: 0;
}

/* 滑动 */
.dialog-slide-enter-active,
.dialog-slide-leave-active,
.dialog-slide-enter-active .fx-dialog,
.dialog-slide-leave-active .fx-dialog {
  transition: all 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);
}
.dialog-slide-enter-from,
.dialog-slide-leave-to {
  opacity: 0;
}
.dialog-slide-enter-from .fx-dialog,
.dialog-slide-leave-to .fx-dialog {
  transform: translateY(-100px);
  opacity: 0;
}

/* 弹跳 */
.dialog-bounce-enter-active,
.dialog-bounce-leave-active,
.dialog-bounce-enter-active .fx-dialog,
.dialog-bounce-leave-active .fx-dialog {
  transition: all 0.5s cubic-bezier(0.175, 0.885, 0.32, 1.275);
}
.dialog-bounce-enter-from,
.dialog-bounce-leave-to {
  opacity: 0;
}
.dialog-bounce-enter-from .fx-dialog,
.dialog-bounce-leave-to .fx-dialog {
  transform: scale(0.3) translateY(-50px);
  opacity: 0;
}

/* 对象配置 */
.dialog-custom-object-enter-active,
.dialog-custom-object-leave-active,
.dialog-custom-object-enter-active .fx-dialog,
.dialog-custom-object-leave-active .fx-dialog {
  transition: all 0.5s cubic-bezier(0.25, 0.8, 0.25, 1);
}
.dialog-custom-object-enter-from,
.dialog-custom-object-leave-to {
  opacity: 0;
}
.dialog-custom-object-enter-from .fx-dialog,
.dialog-custom-object-leave-to .fx-dialog {
  transform: rotate(180deg) scale(0.5);
  opacity: 0;
}
</style>

事件

打开浏览器控制台，观察事件触发顺序：open → opened → close → closed。

<template>
  <FxBtn type="primary" @click="visible = true">打开</FxBtn>
  <FxDialog
    v-model="visible"
    modal-class="events-demo"
    :before-close="(done) => { log('before-close'); done() }"
    @open="log('open')"
    @open-auto-focus="log('open-auto-focus')"
    @opened="log('opened')"
    @close="log('close')"
    @close-auto-focus="log('close-auto-focus')"
    @closed="log('closed')"
  >
    <span>打开浏览器控制台，观察事件顺序：open → open-auto-focus → opened → close → close-auto-focus → closed</span>
    <template #footer>
      <FxBtn @click="visible = false">取消</FxBtn>
      <FxBtn type="primary" @click="visible = false">确认</FxBtn>
    </template>
  </FxDialog>
</template>

<script setup lang="ts">
import { ref } from "vue"

const visible = ref(false)

function log(name: string) {
  // eslint-disable-next-line no-console
  console.log(`[FxDialog] ${name}`)
}
</script>

实现说明

架构分层

FxDialog 拆为两层，与 fxOverlay / fxFocusTrap 协作：

• FxDialog（dialog.vue）：负责挂载位置（Teleport）、遮罩、焦点陷阱、显隐动画生命周期、全屏状态管理，向内容层 provide(dialogInjectionKey)。
• FxDialogContent（dialog-content.vue）：负责 header / body / footer 三段式结构、关闭按钮、全屏切换按钮、拖拽（基于 _shared/use-draggable），通过 inject 拿到容器注入的 ref 与状态。

显隐与动画

• 由 use-dialog.ts 集中管理 visible / rendered / closing 状态：openDelay / closeDelay 控制延时，destroy-on-close 控制关闭后是否销毁（懒渲染）。
• 动画名默认 dialog-fade（遮罩淡入淡出 + 弹窗位移淡入），样式定义在 dialog.vue 的全局 <style> 块（.dialog-fade-enter-active / .dialog-fade-leave-active + @keyframes）。因弹窗 Teleport 到 body，自定义动画类需写在全局（非 scoped）样式中。
• transition 支持字符串（动画名）或 Vue Transition 配置对象；传对象时若无 name，自动回退到 dialog-fade 并触发警告。

全屏能力（fx 增强）

• 受控全屏：v-model:fullscreen 双向绑定，内部以 isFullscreen 维护真实状态，打开时取 fullscreen ?? defaultFullscreen 初始化。
• 全屏切换按钮：fullscreen-button（默认开启），位于标题栏，点击触发 update:fullscreen / fullscreen-change 事件。
• 全屏时禁用拖拽与遮罩穿透，并保留 / 恢复拖拽产生的 transform 偏移。

关闭流程

关闭可被 before-close 拦截：回调收到 done(cancel?)，调用 done(true) 取消关闭，done() 或 done(false) 继续关闭。触发关闭的入口（关闭按钮 / 遮罩点击 / ESC）统一走 handleClose。

样式与 token

• 类名走 useNamespace('dialog') 生成 fx- BEM（脚本内），<style> 内手写字面量但遵循同一 BEM 结构。
• 视觉规格映射到 @fx/styles token：背景 --color-surface、阴影 --shadow-card、圆角 --radius-sm、标题色 --color-text-primary、正文色 --color-text-secondary、过渡时长 --duration-slow；不引用任何第三方 UI 库的 CSS 变量。
• 局部 CSS 变量（--fx-dialog-*）承担尺寸 / 字号 / 间距的可定制入口，消费方可通过覆盖这些变量微调。

局部引入

import { FxDialog } from "@fx/components"

API

Attributes

名称	说明	类型	默认值
model-value (v-model)	是否显示	boolean	false
title	标题（也可用 header 插槽）	string	''
width	宽度	string | number	50%
fullscreen	是否全屏（支持 v-model:fullscreen）	boolean	false
fullscreen-button	是否显示全屏切换按钮（扩展）	boolean	true
default-fullscreen	打开时是否默认全屏（扩展）	boolean	false
top	margin-top 值	string	15vh
modal	是否显示遮罩	boolean	true
modal-penetrable	遮罩是否可穿透（需 modal=false）	boolean	false
modal-class	遮罩自定义类名	string	—
header-class / body-class / footer-class	各区域自定义类名	string	—
append-to-body	是否挂载到 body（嵌套 Dialog 需置 true）	boolean	false
append-to	挂载目标（覆盖 append-to-body）	string | HTMLElement	body
lock-scroll	是否锁定 body 滚动	boolean	true
open-delay / close-delay	打开 / 关闭延时（ms）	number	0
close-on-click-modal	点击遮罩是否关闭	boolean	true
close-on-press-escape	按 ESC 是否关闭	boolean	true
show-close	是否显示关闭按钮	boolean	true
close-icon	自定义关闭图标。字符串为 IconString 类型（即 FxIcon 图标名，如 ep:edit、ant-design:home、svg:xxx）	string	ep:close
before-close	关闭前回调	(done: (cancel?: boolean) => void) => void	—
draggable	是否可拖拽	boolean	false
overflow	可拖拽时是否允许超出可视区	boolean	false
center	是否居中显示 header 与 footer	boolean	false
align-center	是否水平 + 垂直居中	boolean	false
destroy-on-close	关闭时销毁内容	boolean	false
z-index	层级	number	自增
header-aria-level	header 的 aria-level	string	2
transition	自定义动画配置	string | TransitionProps	dialog-fade
trap-focus	是否在弹窗内捕获焦点（历史兼容字段，弹窗默认即做焦点陷阱，传值不影响行为）	boolean	false

Events

名称	说明	类型
update:modelValue	显隐变化	(value: boolean)
update:fullscreen	全屏状态变化（扩展）	(value: boolean)
fullscreen-change	全屏状态变化（扩展）	(value: boolean)
open	打开瞬间	() => void
opened	打开动画结束	() => void
close	关闭瞬间	() => void
closed	关闭动画结束	() => void
open-auto-focus	打开并聚焦后	() => void
close-auto-focus	关闭并聚焦后	() => void

Slots

名称	说明	作用域参数
default	正文内容	—
header	标题区（覆盖默认标题，不覆盖关闭按钮）	close titleId titleClass
header-extra	标题栏额外按钮区（全屏按钮左侧，扩展）	fullscreen toggleFullscreen
footer	底部区	—
title	标题（已废弃，用 header）	—

Exposes

名称	说明	类型
resetPosition	重置拖拽位置	() => void
handleClose	触发关闭	() => void