Modal 对话框

模态对话框。

何时使用

需要用户处理事务，又不希望跳转页面以致打断工作流程时，可以使用 Modal 在当前页面正中打开一个浮层，承载相应的操作。

另外当需要一个简洁的确认框询问用户时，可以使用 Modal.confirm() 等语法糖方法。

代码演示

基本用法

第一个对话框。

<template>
  <div>
    <a-button type="primary" @click="showModal">Open Modal</a-button>
    <a-modal v-model:visible="visible" title="Basic Modal" @ok="handleOk">
      <p>Some contents...</p>
      <p>Some contents...</p>
      <p>Some contents...</p>
    </a-modal>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const visible = ref<boolean>(false);
    const showModal = () => {
      visible.value = true;
    };
    const handleOk = (e: MouseEvent) => {
      console.log(e);
      visible.value = false;
    };
    return {
      visible,
      showModal,
      handleOk,
    };
  },
});
</script>
信息提示

各种类型的信息提示，只提供一个按钮用于关闭。

<template>
  <div>
    <a-button @click="info">Info</a-button>
    <a-button @click="success">Success</a-button>
    <a-button @click="error">Error</a-button>
    <a-button @click="warning">Warning</a-button>
  </div>
</template>
<script lang="ts">
import { Modal } from 'ant-design-vue';
import { defineComponent, h } from 'vue';
export default defineComponent({
  setup() {
    const info = () => {
      Modal.info({
        title: () => 'This is a notification message',
        content: () => h('div', {}, [
          h('p', 'some messages...some messages...'),
          h('p', 'some messages...some messages...'),
        ]),
        onOk() {
          console.log('ok');
        },
      });
    };
    const success = () => {
      Modal.success({
        title: () => 'This is a success message',
        content: () => h('div', {}, [
          h('p', 'some messages...some messages...'),
          h('p', 'some messages...some messages...'),
        ]),
      });
    };
    const error = () => {
      Modal.error({
        title: () => 'This is an error message',
        content: () => 'some messages...some messages...',
      });
    };
    const warning = () => {
      Modal.warning({
        title: () => 'This is a warning message',
        content: () => 'some messages...some messages...',
      });
    };
    return {
      info,
      success,
      error,
      warning,
    };
  },
});
</script>
手动更新和移除

手动更新和关闭 Modal.method 方式创建的对话框。

<template>
  <a-button @click="countDown">Open modal to close in 5s</a-button>
</template>
<script lang="ts">
import { Modal } from 'ant-design-vue';
import { defineComponent } from 'vue';
export default defineComponent({
  setup() {
    const countDown = () => {
      let secondsToGo = 5;
      const modal = Modal.success({
        title: 'This is a notification message',
        content: `This modal will be destroyed after ${secondsToGo} second.`,
      });
      const interval = setInterval(() => {
        secondsToGo -= 1;
        modal.update({
          content: `This modal will be destroyed after ${secondsToGo} second.`,
        });
      }, 1000);
      setTimeout(() => {
        clearInterval(interval);
        modal.destroy();
      }, secondsToGo * 1000);
    };
    return {
      countDown,
    };
  },
});
</script>
销毁确认对话框

使用 Modal.destroyAll() 可以销毁弹出的确认窗。通常用于路由监听当中，处理路由前进、后退不能销毁确认对话框的问题。

<template>
  <a-button @click="showConfirm">Confirm</a-button>
</template>
<script lang="ts">
import { ExclamationCircleOutlined } from '@ant-design/icons-vue';
import { createVNode, defineComponent } from 'vue';
import { Modal } from 'ant-design-vue';
export default defineComponent({
  setup() {
    const showConfirm = () => {
      for (let i = 0; i < 3; i += 1) {
        setTimeout(() => {
          Modal.confirm({
            content: () => 'destroy all',
            icon: () => createVNode(ExclamationCircleOutlined),
            onOk() {
              return new Promise((resolve, reject) => {
                setTimeout(Math.random() > 0.5 ? resolve : reject, 1000);
              }).catch(() => console.log('Oops errors!'));
            },
            cancelText: () => 'Click to destroy all',
            onCancel() {
              Modal.destroyAll();
            },
          });
        }, i * 500);
      }
    };
    return {
      showConfirm,
    };
  },
});
</script>
自定义模态的宽度

使用width来设置模态对话框的宽度

<template>
  <div>
    <a-button type="primary" @click="showModal">Open Modal of 1000px width</a-button>
    <a-modal v-model:visible="visible" width="1000px" title="Basic Modal" @ok="handleOk">
      <p>Some contents...</p>
      <p>Some contents...</p>
      <p>Some contents...</p>
    </a-modal>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const visible = ref<boolean>(false);
    const showModal = () => {
      visible.value = true;
    };
    const handleOk = (e: MouseEvent) => {
      console.log(e);
      visible.value = false;
    };
    return {
      visible,
      showModal,
      handleOk,
    };
  },
});
</script>
全屏

使用样式定义一个全屏弹窗

<template>
  <div>
    <a-button type="primary" @click="showModal">Open Modal</a-button>
    <a-modal
      v-model:visible="visible"
      title="Basic Modal"
      @ok="handleOk"
      width="100%"
      wrapClassName="full-modal"
    >
      <p>Some contents...</p>
      <p>Some contents...</p>
      <p>Some contents...</p>
    </a-modal>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const visible = ref<boolean>(false);
    const showModal = () => {
      visible.value = true;
    };
    const handleOk = (e: MouseEvent) => {
      console.log(e);
      visible.value = false;
    };
    return {
      visible,
      showModal,
      handleOk,
    };
  },
});
</script>
<style lang="less">
.full-modal {
  .ant-modal {
    max-width: 100%;
    top: 0;
    padding-bottom: 0;
    margin: 0;
  }
  .ant-modal-content {
    display: flex;
    flex-direction: column;
    height: calc(100vh);
  }
  .ant-modal-body {
    flex: 1;
  }
}
</style>
异步关闭

点击确定后异步关闭对话框，例如提交表单。

<template>
  <div>
    <a-button type="primary" @click="showModal">Open Modal with async logic</a-button>
    <a-modal
      title="Title"
      v-model:visible="visible"
      :confirm-loading="confirmLoading"
      @ok="handleOk"
    >
      <p>{{ modalText }}</p>
    </a-modal>
  </div>
</template>
<script lang="ts">
import { ref, defineComponent } from 'vue';
export default defineComponent({
  setup() {
    const modalText = ref<string>('Content of the modal');
    const visible = ref<boolean>(false);
    const confirmLoading = ref<boolean>(false);
    const showModal = () => {
      visible.value = true;
    };
    const handleOk = () => {
      modalText.value = 'The modal will be closed after two seconds';
      confirmLoading.value = true;
      setTimeout(() => {
        visible.value = false;
        confirmLoading.value = false;
      }, 2000);
    };
    return {
      modalText,
      visible,
      confirmLoading,
      showModal,
      handleOk,
    };
  },
});
</script>
确认对话框

使用 confirm() 可以快捷地弹出确认框。

<template>
  <div>
    <a-button @click="showConfirm">Confirm</a-button>
    <a-button type="dashed" @click="showDeleteConfirm">Delete</a-button>
    <a-button type="dashed" @click="showPropsConfirm">With extra props</a-button>
  </div>
</template>
<script lang="ts">
import { ExclamationCircleOutlined } from '@ant-design/icons-vue';
import { createVNode, defineComponent } from 'vue';
import { Modal } from 'ant-design-vue';
export default defineComponent({
  setup() {
    const showConfirm = () => {
      Modal.confirm({
        title: () => 'Do you Want to delete these items?',
        icon: () => createVNode(ExclamationCircleOutlined),
        content: () => createVNode('div', { style: 'color:red;' }, 'Some descriptions'),
        onOk() {
          console.log('OK');
        },
        onCancel() {
          console.log('Cancel');
        },
        class: 'test',
      });
    };
    const showDeleteConfirm = () => {
      Modal.confirm({
        title: () => 'Are you sure delete this task?',
        icon: () => createVNode(ExclamationCircleOutlined),
        content: () => 'Some descriptions',
        okText: () => 'Yes',
        okType: 'danger',
        cancelText: () => 'No',
        onOk() {
          console.log('OK');
        },
        onCancel() {
          console.log('Cancel');
        },
      });
    };
    const showPropsConfirm = () => {
      Modal.confirm({
        title: () => 'Are you sure delete this task?',
        icon: () => createVNode(ExclamationCircleOutlined),
        content: () => 'Some descriptions',
        okText: () => 'Yes',
        okType: 'danger',
        okButtonProps: {
          disabled: true,
        },
        cancelText: () => 'No',
        onOk() {
          console.log('OK');
        },
        onCancel() {
          console.log('Cancel');
        },
      });
    };
    return {
      showConfirm,
      showDeleteConfirm,
      showPropsConfirm,
    };
  },
});
</script>
国际化

设置 okText 与 cancelText 以自定义按钮文字。

<template>
  <div>
    <a-button type="primary" @click="showModal">Modal</a-button>
    <a-button @click="confirm">Confirm</a-button>
    <a-modal
      v-model:visible="visible"
      title="Modal"
      ok-text="确认"
      cancel-text="取消"
      @ok="hideModal"
    >
      <p>Bla bla ...</p>
      <p>Bla bla ...</p>
      <p>Bla bla ...</p>
    </a-modal>
  </div>
</template>
<script lang="ts">
import { ExclamationCircleOutlined } from '@ant-design/icons-vue';
import { defineComponent, ref, createVNode } from 'vue';
import { Modal } from 'ant-design-vue';
export default defineComponent({
  setup() {
    const visible = ref<boolean>(false);
    const showModal = () => {
      visible.value = true;
    };
    const hideModal = () => {
      visible.value = false;
    };
    const confirm = () => {
      Modal.confirm({
        title: 'Confirm',
        icon: createVNode(ExclamationCircleOutlined),
        content: 'Bla bla ...',
        okText: '确认',
        cancelText: '取消',
      });
    };
    return {
      visible,
      showModal,
      hideModal,
      confirm,
    };
  },
});
</script>


自定义位置

使用 centered 或类似 style.top 的样式来设置对话框位置。

<template>
  <div id="components-modal-demo-position">
    <a-button type="primary" @click="setModal1Visible(true)">
      Display a modal dialog at 20px to Top
    </a-button>
    <a-modal
      title="20px to Top"
      style="top: 20px"
      v-model:visible="modal1Visible"
      @ok="setModal1Visible(false)"
    >
      <p>some contents...</p>
      <p>some contents...</p>
      <p>some contents...</p>
    </a-modal>
    <br />
    <br />
    <a-button type="primary" @click="modal2Visible = true">
      Vertically centered modal dialog
    </a-button>
    <a-modal
      v-model:visible="modal2Visible"
      title="Vertically centered modal dialog"
      centered
      @ok="modal2Visible = false"
    >
      <p>some contents...</p>
      <p>some contents...</p>
      <p>some contents...</p>
    </a-modal>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const modal1Visible = ref<boolean>(false);
    const modal2Visible = ref<boolean>(false);
    const setModal1Visible = (visible: boolean) => {
      modal1Visible.value = visible;
    };
    return {
      modal1Visible,
      modal2Visible,
      setModal1Visible,
    };
  },
});
</script>
确认对话框(promise)

使用 confirm() 可以快捷地弹出确认框。onCancel/onOk 返回 promise 可以延迟关闭

<template>
  <a-button @click="showConfirm">Confirm</a-button>
</template>
<script lang="ts">
import { ExclamationCircleOutlined } from '@ant-design/icons-vue';
import { createVNode, defineComponent } from 'vue';
import { Modal } from 'ant-design-vue';
export default defineComponent({
  setup() {
    const showConfirm = () => {
      Modal.confirm({
        title: () => 'Do you want to delete these items?',
        icon: () => createVNode(ExclamationCircleOutlined),
        content: () => 'When clicked the OK button, this dialog will be closed after 1 second',
        onOk() {
          return new Promise((resolve, reject) => {
            setTimeout(Math.random() > 0.5 ? resolve : reject, 1000);
          }).catch(() => console.log('Oops errors!'));
        },
        // eslint-disable-next-line @typescript-eslint/no-empty-function
        onCancel() {},
      });
    };
    return {
      showConfirm,
    };
  },
});
</script>
自定义页脚按钮属性

传入 okButtonProps 和 cancelButtonProps 可分别自定义确定按钮和取消按钮的 props。

<template>
  <div>
    <a-button type="primary" @click="showModal">Open Modal with customized button props</a-button>
    <a-modal
      v-model:visible="visible"
      title="Basic Modal"
      :ok-button-props="{ disabled: true }"
      :cancel-button-props="{ disabled: true }"
      @ok="handleOk"
    >
      <p>Some contents...</p>
      <p>Some contents...</p>
      <p>Some contents...</p>
    </a-modal>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const visible = ref<boolean>(false);
    const showModal = () => {
      visible.value = true;
    };
    const handleOk = (e: MouseEvent) => {
      console.log(e);
      visible.value = false;
    };
    const handleCancel = (e: MouseEvent) => {
      console.log(e);
      visible.value = false;
    };
    return {
      visible,
      showModal,
      handleOk,
      handleCancel,
    };
  },
});
</script>

API#

参数 说明 类型 默认值 版本
afterClose Modal 完全关闭后的回调 function 无
bodyStyle Modal body 样式 object {}
cancelText 取消按钮文字 string| slot 取消
centered 垂直居中展示 Modal Boolean false
closable 是否显示右上角的关闭按钮 boolean true
closeIcon 自定义关闭图标 VNode | slot -
confirmLoading 确定按钮 loading boolean 无
destroyOnClose 关闭时销毁 Modal 里的子元素 boolean false
footer 底部内容，当不需要默认底部按钮时，可以设为 :footer="null" string|slot 确定取消按钮
forceRender 强制渲染 Modal boolean false
getContainer 指定 Modal 挂载的 HTML 节点 (instance): HTMLElement () => document.body
keyboard 是否支持键盘 esc 关闭 boolean true
mask 是否展示遮罩 Boolean true
maskClosable 点击蒙层是否允许关闭 boolean true
maskStyle 遮罩样式 object {}
okText 确认按钮文字 string|slot 确定
okType 确认按钮类型 string primary
okButtonProps ok 按钮 props ButtonProps -
cancelButtonProps cancel 按钮 props ButtonProps -
title 标题 string|slot 无
visible(v-model) 对话框是否可见 boolean 无
width 宽度 string|number 520
wrapClassName 对话框外层容器的类名 string -
zIndex 设置 Modal 的 z-index Number 1000
dialogStyle 可用于设置浮层的样式，调整浮层位置等 object -
dialogClass 可用于设置浮层的类名 string -

事件

事件名称 说明 回调参数
cancel 点击遮罩层或右上角叉或取消按钮的回调 function(e)
ok 点击确定回调 function(e)

注意

<Modal /> 默认关闭后状态不会自动清空, 如果希望每次打开都是新内容，请设置 destroyOnClose。

包括：

以上均为一个函数，参数为 object，具体属性如下：

参数 说明 类型 默认值 版本
autoFocusButton 指定自动获得焦点的按钮 null|string: ok cancel ok
cancelText 取消按钮文字 () => VNode 取消
centered 垂直居中展示 Modal Boolean false
closable 是否显示右上角的关闭按钮 boolean false
class 容器类名 string -
content 内容 () => VNode 无
icon 自定义图标（1.14.0 新增） VNode | ()=>VNode -
mask 是否展示遮罩 Boolean true
maskClosable 点击蒙层是否允许关闭 Boolean false
keyboard 是否支持键盘 esc 关闭 boolean true
okText 确认按钮文字 () => VNode 确定
okType 确认按钮类型 string primary
okButtonProps ok 按钮 props ButtonProps -
cancelButtonProps cancel 按钮 props ButtonProps -
title 标题 () => VNode 无
width 宽度 string|number 416
zIndex 设置 Modal 的 z-index Number 1000
onCancel 取消回调，参数为关闭函数，返回 promise 时 resolve 后自动关闭 function 无
onOk 点击确定回调，参数为关闭函数，返回 promise 时 resolve 后自动关闭 function 无
appContext 弹窗的父级上下文，一般用于获取父级 provider， 如获取 ConfigProvider 的配置 vue instance -

以上函数调用后，会返回一个引用，可以通过该引用更新和关闭弹窗。

const modal = Modal.info();
modal.update({
  title: '修改的标题',
  content: '修改的内容',
});
modal.destroy();

使用 Modal.destroyAll() 可以销毁弹出的确认窗（即上述的 Modal.info、Modal.success、Modal.error、Modal.warning、Modal.confirm）。通常用于路由监听当中，处理路由前进、后退不能销毁确认对话框的问题，而不用各处去使用实例的返回值进行关闭（modal.destroy() 适用于主动关闭，而不是路由这样被动关闭） 

const router = new VueRouter({ ... })
// router change
router.beforeEach((to, from, next) => {
  Modal.destroyAll();
})