Dialog 对话框

旗舰级弹窗解决方案。在兼容业内主流交互规范的基础上，针对拖拽边界感、焦点捕获 (Focus Trap) 以及旗舰级亚克力视觉 (Glassmorphism) 进行了深度增强，为生产环境提供极致的视觉与操作连贯性。

基础用法

最简单的对话框展示。得益于内置的智能页脚 (Smart Footer) 系统，组件默认会自动渲染标准的操作按钮（取消/确定），无需额外编写插槽即可实现开箱即用的交互体验。

基础交互

居中展示

除了常规的顶部偏移，我们提供了更灵活的视口对齐策略。通过 align-center 与 center 属性，可以针对不同业务场景实现垂直居中或全场景的水平对齐。

居中对齐模式

全屏展示

底部对齐

你可以通过 footer-align 属性控制底部按钮的水平对齐方式。默认情况下，按钮组在右侧对齐。

底部对齐方式

标题对齐

内容主体对齐

功能增强 (Premium Features)

YH-UI 提供了丰富的增强配置，支持语义化类型映射、原子级加载状态反馈以及全透明的自定义渲染控制器。

语义化类型与图标

加载状态与异步控制

渲染函数支持

关闭销毁 (性能优化)

鼠标起源动画

高级交互特性

YH-UI 致力于打磨每一个像素级的交互反馈。这包括了基于视口物理安全边界的拖拽算法，以及旗舰级的玻璃态视觉渲染。

顶级交互增强

在 Nuxt 中使用

YH-UI 完美适配 Nuxt 3。你可以直接在 app.vue 或 any 页面中使用。

自动导入

如果你使用了 unplugin-vue-components/resolvers，YhDialog 将会被自动按需加载并包含完整的样式。

Nuxt 适配

按钮位置互换

函数式调用

在某些场景下，你可能希望跳过 v-model 的模板声明，直接通过代码发起弹窗。YH-UI 提供了基于 Promise 的函数式调用方案，支持 Hook 形式与静态方法形式。

函数式调用演示

异步反馈与回调

函数式按钮互换

调用方式

你可以根据业务复杂度选择最合适的调用方式。

组合式 API Hook (useDialog)

在 <script setup> 中，推荐使用 useDialog Hook 来发起函数式弹窗调用，它能自动继承当前的应用上下文：

vue

<script setup lang="ts">
import { useDialog } from '@yh-ui/yh-ui'

const { showDialog } = useDialog()

const handleOpen = async () => {
  const { action } = await showDialog({
    title: '提示',
    content: '这是一个函数式调用的对话框',
    confirmText: '确定',
    cancelText: '取消'
  })
  if (action === 'confirm') {
    // 确认后的逻辑
  }
}
</script>

声明式组件 (v-model)

通过 v-model 双向绑定在模板中声明组件，这是最符合 Vue 声明式设计心智的方式：

vue

<template>
  <yh-button @click="visible = true">打开对话框</yh-button>

  <yh-dialog v-model="visible" title="标准设计预览">
    <span>对话框内容</span>
  </yh-dialog>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const visible = ref(false)
</script>

静态方法直接调用 (YhDialogMethod)

通过导入 YhDialogMethod 静态对象直接发起弹窗，适合在非组件逻辑（例如路由守卫或 Pinia Store）中快速调用：

import { YhDialogMethod } from '@yh-ui/yh-ui'

YhDialogMethod.success({
  title: '指令式调用',
  content: '这是通过 YhDialogMethod.success 直接发起的弹窗，无需 v-model。'
})

API

Props

属性名	说明	类型	默认值
v-model	是否显示对话框	`boolean`	`false`
title	对话框标题，支持渲染函数	`string \| (() => VNode)`	-
type	对话框类型	`'success' \| 'warning' \| 'error' \| 'info' \| 'default'`	`'default'`
show-icon	是否显示语义化图标	`boolean`	`true`
loading	是否显示主体加载状态	`boolean`	`false`
content	对话框内容，支持渲染函数	`string \| (() => VNode)`	-
action	底部操作区域内容，支持渲染函数	`(() => VNode)`	-
transform-origin	动画起源位置	`'mouse' \| 'center'`	`'mouse'`
width	对话框宽度	`string \| number`	`'50%'`
top	距离顶部的距离（非居中模式有效）	`string`	`'15vh'`
fullscreen	是否全屏展示	`boolean`	`false`
align-center	是否在视口中垂直居中	`boolean`	`false`
center	全居中模式：Header, Body, Footer 内容全部水平居中	`boolean`	`false`
glass	开启旗舰级亚克力（玻璃）材质	`boolean`	`false`
draggable	是否开启物理拖拽功能	`boolean`	`false`
overflow	是否允许拖拽超出视口边界	`boolean`	`false`
modal	是否显示遮罩层	`boolean`	`true`
lock-scroll	出现时锁定视口滚动	`boolean`	`true`
close-on-click-modal	点击背景遮罩层是否关闭弹窗	`boolean`	`true`
close-on-press-escape	按下 ESC 键是否关闭弹窗	`boolean`	`true`
show-close	是否显示关闭按钮	`boolean`	`true`
close-icon	自定义关闭图标	`string`	`'close'`
destroy-on-close	关闭时是否销毁 Dialog 中的内容	`boolean`	`false`
show-footer	是否显示默认页脚按钮	`boolean`	`true`
cancel-text	取消按钮文案	`string`	`'取消'`
confirm-text	确定按钮文案	`string`	`'确定'`
before-close	关闭前的钩子，参数为 `(done: () => void)`	`Function`	-
teleport-to	挂载目标 DOM 节点	`string \| HTMLElement`	`'body'`
header-align-center	对话框标题是否水平居中	`boolean`	`false`
footer-align-center	对话框底部按钮是否水平居中	`boolean`	`false`
style	整体自定义样式	`string \| CSSProperties`	-
title-class	标题自定义类名	`string`	-
title-style	标题自定义样式	`string \| CSSProperties`	-
content-class	主体自定义类名	`string`	-
content-style	主体自定义样式	`string \| CSSProperties`	-
action-class	底部自定义类名	`string`	-
action-style	底部自定义样式	`string \| CSSProperties`	-
modal-class	遮罩层自定义类名	`string`	-
custom-class	根容器自定义类名	`string`	-
z-index	基础层级起点	`number`	`2000`
auto-focus	是否自动聚焦第一个可聚焦元素	`boolean`	`true`
swap-footer-buttons	是否交换底部“确认”与“取消”按钮的位置	`boolean`	`false`
footer-align	底部按钮对齐方式	`'left' \| 'center' \| 'right'`	`'right'`
header-align	标题对齐方式	`'left' \| 'center' \| 'right'`	`'left'`
content-align	内容对齐方式	`'left' \| 'center' \| 'right'`	`'left'`

Slots

插槽名	说明
default	对话框主体内容区域
header	自定义头部区域。若使用该插槽，`title` 属性将失效
footer	自定义底部操作按钮区域。若使用该插槽，内置按钮将失效

Events

事件名	说明	回调参数
update:modelValue	显隐状态变更时触发	`(value: boolean)`
open	对话框显隐状态变为 true 时触发	-
opened	对话框打开动画播放完成时触发	-
close	对话框显隐状态变为 false 时触发	-
closed	对话框关闭动画播放完成且销毁后触发	-
confirm	点击默认页脚的“确定”按钮时触发	-
cancel	点击默认页脚的“取消”按钮时触发	-
dragStart	点击 header 开始拖移时触发	`(e: MouseEvent)`
dragMove	拖移过程中持续触发	`(e: MouseEvent)`
dragEnd	拖移结束时触发	`(e: MouseEvent)`

Expose

方法名	说明	类型
visible	响应式显隐状态	`Ref<boolean>`
dialogRef	对话框 DOM 引用	`Ref<HTMLElement>`
handleClose	执行关闭逻辑（会触发 before-close）	`() => void`
handleCancel	执行取消逻辑（触发 cancel 事件并关闭）	`() => void`
handleConfirm	执行确定逻辑（触发 confirm 事件并关闭）	`() => void`

useDialog Hook API

useDialog Hook 提供了组件上下文自适应的函数式弹窗调用工具。

const { showDialog } = useDialog()

showDialog 参数 (UseDialogOptions)

UseDialogOptions 继承了 YhDialog 的所有 Props（除了 modelValue），并额外支持以下属性：

属性名	说明	类型	默认值
`content`	弹窗主体内容，支持字符串、渲染函数或组件对象	`string \| (() => VNode \| string) \| Component`	-
`title`	弹窗标题，支持字符串、渲染函数	`string \| (() => VNode \| string)`	-
`action`	底部操作区域内容，支持渲染函数	`() => VNode`	-
`appContext`	可手动传入特定的 Vue 应用上下文	`AppContext`	`null`
`onConfirm`	点击确认按钮时的回调	`() => void`	-
`onCancel`	点击取消按钮时的回调	`() => void`	-
`onClose`	弹窗关闭时的回调	`() => void`	-
`onClosed`	弹窗关闭动画结束后的回调	`() => void`	-

showDialog 返回值

调用 showDialog 将返回一个 Promise，resolve 的结果包含用户的交互动作 action：

Promise<{ action: 'confirm' | 'cancel' | 'close' }>

主题变量

你通过重写以下 CSS 变量来定制 Dialog 的全局视觉。

变量名	默认值	说明
`--yh-dialog-margin-top`	`15vh`	对话框顶部边距
`--yh-bg-color-overlay`	`#ffffff`	对话框背景颜色
`--yh-radius-lg`	`16px`	对话框圆角大小
`--yh-text-color-primary`	`#1a1a1a`	标题颜色
`--yh-color-success`	`#67c23a`	成功态图标/按钮颜色
`--yh-color-warning`	`#e6a23c`	警告态图标/按钮颜色
`--yh-color-danger`	`#f56c6c`	错误态图标/按钮颜色
`--yh-color-info`	`#909399`	信息态图标/按钮颜色
`--yh-text-color-secondary`	`#909399`	关闭按钮颜色
`--yh-text-color-regular`	`#4a4a4a`	正文内容颜色
`--yh-border-color-light`	`rgba(0,0,0,0.05)`	关闭按钮悬浮背景

类型导出

名称	说明
`YhDialogProps`	`YhDialog` props 类型
`YhDialogEmits`	`YhDialog` emits 类型
`YhDialogSlots`	`YhDialog` slots 类型
`YhDialogExpose`	`YhDialog` expose 类型
`YhDialogMethod`	函数式调用类型
`YhDialogInstance`	`YhDialog` 实例类型

Dialog 对话框 ​

基础用法 ​

居中展示 ​

底部对齐 ​

功能增强 (Premium Features) ​

高级交互特性 ​

在 Nuxt 中使用 ​

函数式调用 ​

调用方式 ​

组合式 API Hook (useDialog) ​

声明式组件 (v-model) ​

静态方法直接调用 (YhDialogMethod) ​

API ​

Props ​

Slots ​

Events ​

Expose ​

useDialog Hook API ​

showDialog 参数 (UseDialogOptions) ​

showDialog 返回值 ​

主题变量 ​

类型导出 ​