弹窗组件

弹窗组件提供了对话框功能，可以在表单中按需打开和使用。弹窗可用于展示额外信息、接受用户输入或进行其他交互操作。弹窗组件支持完整的表单功能，包括数据验证、提交处理和与其他组件的联动，有助于实现复杂业务场景的表单交互。

基础使用

打开弹窗

在组件的事件中调用 api.open 方法即可打开弹窗。例如，在按钮的点击事件中打开一个弹窗：

function onChange($inject) {
    $inject.api.open('ref_F2vulxvqc841dac');
}

上述代码会打开 ID 为 ref_F2vulxvqc841dac 的弹窗。弹窗会以默认的配置显示，如果弹窗内包含表单组件，表单将使用初始值或默认值。

关闭弹窗

在组件的事件中调用 api.close 方法即可关闭弹窗。例如：

function onChange($inject) {
    $inject.api.close('ref_F2vulxvqc841dac');
}

用户也可以通过点击弹窗的关闭按钮或确认按钮来关闭弹窗（取决于 autoClose 配置）。

数据交互

打开弹窗并设置表单默认值

api.open 方法的第二个参数可以设置弹窗表单的默认值。这对于编辑场景非常有用，可以让弹窗预填充已有的数据。例如：

function change($inject) {
    $inject.api.open('ref_F2vulxvqc841dac', {
        name: '默认名称',
        age: 18,
        email: 'example@email.com'
    });
}

传入的数据会覆盖弹窗表单中对应字段的默认值。如果某个字段在传入的数据中不存在，则会使用该字段的原始默认值。

监听弹窗表单的提交事件

api.open 方法的第三个参数可以设置表单提交回调函数。该回调函数在弹窗表单验证通过并成功提交后执行。例如：

function openDialog($inject) {
    $inject.api.open(
        'ref_F2vulxvqc841dac',
        {
            name: '初始值'
        },
        (formData, api) => {
            console.log('弹窗表单提交的数据:', formData);
            // 可以将数据保存到后台
            // saveToBackend(formData);
        }
    );
}

回调函数接收两个参数：formData 是提交的表单数据对象，api 是弹窗的表单API实例。您可以在回调函数中进行数据处理、保存或触发其他业务逻辑。

获取弹窗中表单数据

通过弹窗组件的 fapi 可以操作弹窗内的表单。例如，在弹窗打开后获取表单数据：

function getDialogFormData($inject) {
    // 获取弹窗组件实例
    const dialogComponent = $inject.api.top.el('ref_F2vulxvqc841dac');
    // 获取弹窗表单的API实例
    const dialogApi = dialogComponent.fapi;
    // 获取当前表单数据
    const formData = dialogApi.formData();
    console.log('当前表单数据:', formData);
}

注意：必须在弹窗渲染后才可以获取表单数据。 建议在 opened 事件触发后再获取表单数据。

程序化关闭弹窗

使用注入的 api.el 方法可以操作弹窗，直接调用 close 方法关闭弹窗：

function closeDialog($inject) {
    $inject.api.top.el('ref_F2vulxvqc841dac').close();
}

将 ref_F2vulxvqc841dac 替换为您的弹窗组件的ID。

获取弹窗表单API

弹窗内部的表单实例可以通过 fapi 属性获取，方便您进行数据操作或验证：

function getDialogFormData($inject) {
    // 获取弹窗组件实例
    const dialogComponent = $inject.api.top.el('ref_F2vulxvqc841dac');
    // 获取弹窗表单的API实例
    const dialogApi = dialogComponent.fapi;

    // 获取当前表单数据
    const formData = dialogApi.formData();
    console.log('当前表单数据:', formData);

    // 验证表单
    dialogApi.validate().then(() => {
        console.log('验证通过');
    }).catch(() => {
        console.log('验证失败');
    });
}

通过 fapi，您可以访问弹窗内的表单API，进行数据读取、字段验证、值设置等操作。

配置项

弹窗组件提供了丰富的配置选项，您可以通过在设计器中配置弹窗组件的属性来自定义弹窗的行为和外观。

属性名	类型	默认值	说明
title	`String`	-	弹窗标题
width	`String`	`50%`	弹窗宽度
fullscreen	`Boolean`	`false`	是否全屏显示
formData	`Object`	-	表单数据对象
options	`Object`	`{ submitBtn: false, resetBtn: false }`	表单配置选项
rule	`Array`	-	表单生成规则
autoClose	`Boolean`	`true`	是否自动关闭对话框
footer	`Boolean`	`true`	是否显示底部按钮
preview	`Boolean`	-	是否为预览模式
disabled	`Boolean`	-	是否禁用表单
modal	`Boolean`	`true`	是否显示遮罩层
modelValue	`Object`	-	双向绑定的表单数据
beforeClose	`Function`	-	关闭前的回调函数

事件

弹窗组件提供了丰富的事件，方便您监听弹窗的各种状态变化并执行相应的处理。

事件名	参数	说明
confirm	`fapi`	确认按钮点击事件，当用户点击确认按钮时触发
submit	`formData, fapi, close`	表单提交成功事件，当表单验证通过并提交成功时触发
validateFail	`e, fapi`	表单验证失败事件，当表单验证失败时触发
update:modelValue	`formData`	表单数据更新事件，当表单数据变化时触发
open	-	弹窗打开事件，在弹窗打开前触发
opened	-	弹窗已打开事件，在弹窗打开后触发
close	-	弹窗关闭事件，在弹窗关闭前触发
closed	-	弹窗已关闭事件，在弹窗关闭后触发

事件使用示例

监听表单提交：

function handleSubmit(formData, fapi, close) {
    console.log('弹窗表单提交的数据:', formData);
    // 可以将数据保存到后台
    // await saveToBackend(formData);
    // 关闭弹窗
    close();
}

监听表单验证失败：

function handleValidateFail(e, fapi) {
    console.log('表单验证失败:', e);
    // 显示错误提示
    // ElMessage.error('请检查表单数据');
}

监听表单数据变化：

function handleChange(formData) {
    console.log('当前表单数据:', formData);
    // 可以实时保存草稿
    // saveDraft(formData);
}

方法

弹窗组件提供了多种方法，方便您进行程序化控制。

方法名	参数	说明	返回值
formChange	-	表单数据变化处理（内部使用）	-
open	`formData, handleSubmit`	打开对话框	-
close	-	关闭对话框	-
handleConfirm	-	确认按钮点击处理（内部使用）	-

方法使用示例

程序化打开弹窗：

function openDialog($inject) {
    const dialogComponent = $inject.api.top.el('ref_F2vulxvqc841dac');
    dialogComponent.open(
        { name: '初始值' },
        (formData, fapi, close) => {
            console.log('提交数据:', formData);
            close();
        }
    );
}

程序化关闭弹窗：

function closeDialog($inject) {
    const dialogComponent = $inject.api.top.el('ref_F2vulxvqc841dac');
    dialogComponent.close();
}

验证并提交弹窗表单：

function submitDialog($inject) {
    const dialogComponent = $inject.api.top.el('ref_F2vulxvqc841dac');
    const dialogApi = dialogComponent.fapi;

    dialogApi.validate().then(() => {
        const formData = dialogApi.formData();
        console.log('提交数据:', formData);
        // 提交到后台
    }).catch(() => {
        console.log('验证失败，无法提交');
    });
}

Data

弹窗组件的内部数据属性如下：

数据名	初始值	说明
visible	`false`	对话框显示状态
max	`false`	是否最大化
fapi	`{}`	表单API实例
value	`{}`	表单数据值
formRule	`[]`	表单规则
handleSubmit	`undefined`	提交处理函数
Form	`markRaw(formCreateInject.form.$form())`	Form组件实例

数据说明：

visible：对话框的显示状态，控制弹窗的显示和隐藏
max：对话框是否最大化显示，支持全屏和窗口两种模式切换
fapi：弹窗内表单的API实例，提供了访问和操作表单的方法
value：表单的数据值对象，保存了表单中所有字段的值
formRule：表单的生成规则数组，定义了表单中字段的配置
handleSubmit：表单提交的处理函数，在提交成功时执行
Form：Form组件实例，用于渲染表单内容

Element UI版本

Ant Design Vue版本

弹窗组件

基础使用

打开弹窗

关闭弹窗

数据交互

打开弹窗并设置表单默认值

监听弹窗表单的提交事件

获取弹窗中表单数据

程序化关闭弹窗

获取弹窗表单API

配置项

事件

事件使用示例

方法

方法使用示例

Data

弹窗组件 ​

基础使用 ​

打开弹窗 ​

关闭弹窗 ​

数据交互 ​

打开弹窗并设置表单默认值 ​

监听弹窗表单的提交事件 ​

获取弹窗中表单数据 ​

程序化关闭弹窗 ​

获取弹窗表单API ​

配置项 ​

事件 ​

事件使用示例 ​

方法 ​

方法使用示例 ​

Data ​

弹窗组件

基础使用

打开弹窗

关闭弹窗

数据交互

打开弹窗并设置表单默认值

监听弹窗表单的提交事件

获取弹窗中表单数据

程序化关闭弹窗

获取弹窗表单API

配置项

事件

事件使用示例

方法

方法使用示例

Data