ant-design-vue/components/modal/index.en-US.md
Cherry7 69640c0af8
feat(modal): add useModal (#6517)
* feat(modal): add useModal hook

* feat(modal): add HookModal demo

* test(modal): update HookModal demo snap

* feat(modal): update modal docs

* chore(modal): update modal type
2023-05-03 14:15:34 +08:00

7.9 KiB

category type title cover coverDark
Components Feedback Modal https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*wM3qQ5XrhlcAAAAAAAAAAAAADrJ8AQ/original https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*fBrgSJBmavgAAAAAAAAAAAAADrJ8AQ/original

Modal dialogs.

When To Use

When requiring users to interact with the application, but without jumping to a new page and interrupting the user's workflow, you can use Modal to create a new floating layer over the current page to get user feedback or display information. Additionally, if you need show a simple confirmation dialog, you can use antd.Modal.confirm(), and so on.

API

Property Description Type Default Version
afterClose Specify a function that will be called when modal is closed completely. function -
bodyStyle Body style for modal body element. Such as height, padding etc. object {}
cancelButtonProps The cancel button props ButtonProps -
cancelText Text of the Cancel button string|slot Cancel
centered Centered Modal boolean false
closable Whether a close (x) button is visible on top right of the modal dialog or not boolean true
closeIcon custom close icon VNode | slot -
confirmLoading Whether to apply loading visual effect for OK button or not boolean false
destroyOnClose Whether to unmount child components on onClose boolean false
dialogClass className of floating layer. string -
dialogStyle Style of floating layer, typically used at least for adjusting the position. object -
footer Footer content, set as :footer="null" when you don't need default buttons string|slot OK and Cancel buttons
forceRender Force render Modal boolean false
getContainer Return the mount node for Modal (instance): HTMLElement () => document.body
mask Whether show mask or not. boolean true
maskClosable Whether to close the modal dialog when the mask (area outside the modal) is clicked boolean true
maskStyle Style for modal's mask element. object {}
okButtonProps The ok button props ButtonProps -
okText Text of the OK button string|slot OK
okType Button type of the OK button string primary
title The modal dialog's title string|slot -
open(v-model) Whether the modal dialog is visible or not boolean false
width Width of the modal dialog string|number 520
wrapClassName The class name of the container of the modal dialog string -
zIndex The z-index of the Modal number 1000

events

Events Name Description Arguments
cancel Specify a function that will be called when a user clicks mask, close button on top right or Cancel button function(e)
ok Specify a function that will be called when a user clicks the OK button function(e)

Note

The state of Modal will be preserved at it's component lifecycle by default, if you wish to open it with a brand new state everytime, set destroyOnClose on it.

Modal.method()

There are five ways to display the information based on the content's nature:

  • Modal.info
  • Modal.success
  • Modal.error
  • Modal.warning
  • Modal.confirm

The items listed above are all functions, expecting a settings object as parameter. The properties of the object are follows:

Property Description Type Default Version
appContext The context of the pop-up window is generally used to obtain content such as global registered components, vuex, etc. - -
autoFocusButton Specify which button to autofocus null | ok | cancel ok
cancelButtonProps The cancel button props ButtonProps -
cancelText Text of the Cancel button string Cancel
centered Centered Modal boolean false
class class of container string -
closable Whether a close (x) button is visible on top right of the modal dialog or not boolean false
content Content string|VNode |function(h) -
footer Footer content, set as footer: null when you don't need default buttons string|VNode |function(h) - 4.0.0
icon custom icon (Added in 1.14.0) VNode |()=>VNode -
keyboard Whether support press esc to close boolean true
mask Whether show mask or not. boolean true
maskClosable Whether to close the modal dialog when the mask (area outside the modal) is clicked boolean false
okButtonProps The ok button props ButtonProps -
okText Text of the OK button string OK
okType Button type of the OK button string primary
title Title string|VNode |function(h) -
width Width of the modal dialog string|number 416
wrapClassName The class name of the container of the modal dialog string - 3.2.3
zIndex The z-index of the Modal number 1000
onCancel Specify a function that will be called when the user clicks the Cancel button. The parameter of this function is a function whose execution should include closing the dialog. You can also just return a promise and when the promise is resolved, the modal dialog will also be closed function -
onOk Specify a function that will be called when the user clicks the OK button. The parameter of this function is a function whose execution should include closing the dialog. You can also just return a promise and when the promise is resolved, the modal dialog will also be closed function -

All the Modal.methods will return a reference, and then we can update and close the modal dialog by the reference.

const modal = Modal.info();

modal.update({
  title: 'Updated title',
  content: 'Updated content',
});

modal.destroy();
  • Modal.destroyAll

Modal.destroyAll() could destroy all confirmation modal dialogs(Modal.info/Modal.success/Modal.error/Modal.warning/Modal.confirm). Usually, you can use it in router change event to destroy confirm modal dialog automatically without use modal reference to close( it's too complex to use for all modal dialogs)

const router = new VueRouter({ ... })

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

Modal.useModal()

When you need using Context, you can use contextHolder which created by Modal.useModal to insert into children. Modal created by hooks will get all the context where contextHolder are. Created modal has the same creating function with Modal.method.

<template>
  <contextHolder />
  <!-- <component :is='contextHolder'/> -->
</template>
<script setup>
  import { Modal } from 'ant-design-vue';
  const [modal, contextHolder] = Modal.useModal();

  modal.confirm({
    // ...
  });
</script>

FAQ

Why can't the Modal method obtain global registered components, context, vuex, etc. and ConfigProvider locale/prefixCls/theme configuration, and can't update data responsively?

Call the Modal method directly, and the component will dynamically create a new Vue entity through Vue.render. Its context is not the same as the context where the current code is located, so the context information cannot be obtained.

When you need context information (for example, using a globally registered component), you can use Modal.useModal to get modal instance and contextHolder node. And put it in your children:

<template>
  <contextHolder />
  <!-- <component :is='contextHolder'/> -->
</template>
<script setup>
  import { Modal } from 'ant-design-vue';
  const [modal, contextHolder] = Modal.useModal();

  modal.confirm({
    // ...
  });
</script>