Dialog 对话
一般用于展示 复杂业务 ,例如数据列表、提交表单等。
TIP
该弹出层支持 Promise 风格 调用,具体可以查看 携带参数关闭对话框。
基础使用
Dialog 对话 更像是对最基础的 popup.render() 方法的二次封装,提供了更多开箱即用的对话框功能。
和 popup.render() 方法一样,调用 popup.dialog() 方法并传入 component 视图组件选项,即可弹出一个对话框,在屏幕居中显示。
携带组件参数
可以通过 componentProps 属性来为对话框内容组件传递参数,参数可以是组件的 属性 或 事件监听器。
事件监听器全都以 on 开头,例如 customEvent 事件,对应的事件监听器为 onCustomEvent。
关闭对话框 1.5.0+
通过调用 popup.dialogClose() 方法可以手动关闭最后一个打开的对话框。
如果不存在打开的对话框,调用 popup.dialogClose() 方法将不会有任何效果,debugMode 调试模式 开启的情况下,将会在控制台输出警告信息。
// 关闭对话框
function handleClose() {
popup.dialogClose()
}WARNING
在 1.5.x 版本,关闭对话框的使用方式是:
popup.dialog.close()
该方法使用的是静态方法,无法动态同步组件上下文,因此从 1.6.0 版本开始被废弃,因此请使用新的关闭对话框方法代替:
popup.dialogClose()
携带参数关闭对话框 1.5.0+
当调用 popup.dialogClose() 方法时,可以传入一个 payload 参数,该参数会作为关闭携带参数返回给打开对话框的 Promise 对象,因此可以通过 await 来获取关闭携带参数。
// 关闭对话框
function handleClose() {
popup.dialogClose('awesome !')
}// 这里 await 的返回值为关闭携带的参数 'awesome !'
const result = await popup.dialog({
component: () => import('./HelloDialog.vue'),
})如果你使用 Typescript ,popup.dialog() 方法的返回值类型为 Promise<any> ,这意味着你通过 await 获取到的 result 类型是 any ,大部分情况下没有问题,但为了类型安全,建议你在定义 result 时手动指定类型。
// void 不可缺少,因为无法保证对话框是否会携带参数
const result: string | void = await popup.dialog({
component: () => import('./HelloDialog.vue'),
})设置位置 1.5.0+
可以通过 placement 属性来设置对话框的位置,默认值为 center 。支持的位置有:
left-topleftleft-bottomtopcenterbottomright-toprightright-bottom
手动设置尺寸
默认情况下,对话框会自动根据内部所渲染的组件的实际宽高自适应,但也可以通过 width 和 height 属性来手动设置对话框的尺寸。
下面的示例中,HelloDialog 组件内部的跟层级元素定义了宽高为 400 * 300,而我们将手动设置其宽高为 600 * 600。
TIP
所有的尺寸选项都支持 string 和 number 类型,因此 所有的 css 有效值 和 纯数字 都是合法的。
设置最大最小尺寸
默认情况下,对话框的尺寸是没有最大最小限制的,但也可以通过 minWidth、maxWidth、minHeight、maxHeight 属性来手动设置对话框的最大最小尺寸,这在 没有手动设置尺寸 时非常有用。
隐藏标题栏
可以通过 header 属性来隐藏标题栏,只需要将其设置为 false 即可。
自定义标题文本
可以通过 title 选项来自定义对话框的标题文本。
禁用标题栏关闭按钮
可以通过 headerClose 选项来禁用标题栏的关闭按钮。
启用窗口拖拽功能
可以通过 draggable 选项来启用窗口的拖拽功能,开启后允许拖拽标题栏从而实现窗口的移动。
默认情况下,拖拽时无法超出屏幕范围,可通过 dragOverflow 选项来设置是否允许超出。
禁用遮罩层
可以通过 mask 选项来禁用遮罩层。
启用透明遮罩层 1.6.0+
如果希望在不显示遮罩层的同时,阻止用户对文档的操作,可以通过 maskTransparent 选项来启用透明遮罩层。
启用高斯模糊遮罩层 1.3.0+
如果需要提升用户对弹出层的关注度,可以通过 maskBlur 选项来启用遮罩层的高斯模糊效果。
WARNING
启用高斯模糊遮罩层,对浏览器的渲染性能有一定要求,具体取决于设备性能,请根据实际情况选择是否启用。
启用遮罩层点击关闭对话框
可以通过 maskClose 选项来启用遮罩层点击关闭对话框。
TIP
在 版本以前,请使用 maskClickClose 选项来启用遮罩层点击关闭对话框。
自定义遮罩层点击关闭逻辑 1.6.0+
maskClose 选项同时支持传入一个函数来自定义遮罩层点击关闭逻辑。
传入的函数将接收一个类型为 (payload?: any) => Promise<void> 的 close() 函数作为参数,执行 close() 函数即可关闭对话框。
close() 函数可以接收一个可选的参数 payload,该参数将作为关闭携带的参数。
close() 函数返回一个 Promise 对象,用于等待对话框关闭动画结束后执行后续操作。
渲染完成的回调函数
可以通过 onMounted 选项来指定对话框渲染完成后的回调函数。
详细配置
具体可以参考 预置插件 API - Dialog 对话框。