模态对话框。
需要用户处理事务，又不希望跳转页面以致打断工作流程时，可以使用 Modal 在当前页面正中打开一个浮层，承载相应的操作。
另外当需要一个简洁的确认框询问用户时，可以使用 App.useApp 封装的语法糖方法。
第一个对话框。
import React, { useState } from 'react';
import { Button, Modal } from 'antd';
const App: React.FC = () => {
const [isModalOpen, setIsModalOpen] = useState(false);
const showModal = () => {
setIsModalOpen(true);
};
const handleOk = () => {
setIsModalOpen(false);
};
const handleCancel = () => {
setIsModalOpen(false);
};
return (
<>
<Button type="primary" onClick={showModal}>
Open Modal
</Button>
<Modal title="Basic Modal" open={isModalOpen} onOk={handleOk} onCancel={handleCancel}>
<p>Some contents...</p>
<p>Some contents...</p>
<p>Some contents...</p>
</Modal>
</>
);
};
export default App;
更复杂的例子，自定义了页脚的按钮，点击提交后进入 loading 状态，完成后关闭。
不需要默认确定取消按钮时，你可以把 footer 设为 null。
import React, { useState } from 'react';
import { Button, Modal } from 'antd';
const App: React.FC = () => {
const [loading, setLoading] = useState(false);
const [open, setOpen] = useState(false);
const showModal = () => {
setOpen(true);
};
const handleOk = () => {
setLoading(true);
setTimeout(() => {
setLoading(false);
setOpen(false);
}, 3000);
};
const handleCancel = () => {
setOpen(false);
};
return (
<>
<Button type="primary" onClick={showModal}>
Open Modal with customized footer
</Button>
<Modal
open={open}
title="Title"
onOk={handleOk}
onCancel={handleCancel}
footer={[
<Button key="back" onClick={handleCancel}>
Return
</Button>,
<Button key="submit" type="primary" loading={loading} onClick={handleOk}>
Submit
</Button>,
<Button
key="link"
href="https://google.com"
type="primary"
loading={loading}
onClick={handleOk}
>
Search on Google
</Button>,
]}
>
<p>Some contents...</p>
<p>Some contents...</p>
<p>Some contents...</p>
<p>Some contents...</p>
<p>Some contents...</p>
</Modal>
</>
);
};
export default App;
设置 okText 与 cancelText 以自定义按钮文字。
import { ExclamationCircleOutlined } from '@ant-design/icons';
import { Button, Modal, Space } from 'antd';
import React, { useState } from 'react';
const LocalizedModal = () => {
const [open, setOpen] = useState(false);
const showModal = () => {
setOpen(true);
};
const hideModal = () => {
setOpen(false);
};
return (
<>
<Button type="primary" onClick={showModal}>
Modal
</Button>
<Modal
title="Modal"
open={open}
onOk={hideModal}
onCancel={hideModal}
okText="确认"
cancelText="取消"
>
<p>Bla bla ...</p>
<p>Bla bla ...</p>
<p>Bla bla ...</p>
</Modal>
</>
);
};
const App: React.FC = () => {
const [modal, contextHolder] = Modal.useModal();
const confirm = () => {
modal.confirm({
title: 'Confirm',
icon: <ExclamationCircleOutlined />,
content: 'Bla bla ...',
okText: '确认',
cancelText: '取消',
});
};
return (
<>
<Space>
<LocalizedModal />
<Button onClick={confirm}>Confirm</Button>
</Space>
{contextHolder}
</>
);
};
export default App;
使用 centered 或类似 style.top 的样式来设置对话框位置。
import React, { useState } from 'react';
import { Button, Modal } from 'antd';
const App: React.FC = () => {
const [modal1Open, setModal1Open] = useState(false);
const [modal2Open, setModal2Open] = useState(false);
return (
<>
<Button type="primary" onClick={() => setModal1Open(true)}>
Display a modal dialog at 20px to Top
</Button>
<Modal
title="20px to Top"
style={{ top: 20 }}
open={modal1Open}
onOk={() => setModal1Open(false)}
onCancel={() => setModal1Open(false)}
>
<p>some contents...</p>
<p>some contents...</p>
<p>some contents...</p>
</Modal>
<br />
<br />
<Button type="primary" onClick={() => setModal2Open(true)}>
Vertically centered modal dialog
</Button>
<Modal
title="Vertically centered modal dialog"
centered
open={modal2Open}
onOk={() => setModal2Open(false)}
onCancel={() => setModal2Open(false)}
>
<p>some contents...</p>
<p>some contents...</p>
<p>some contents...</p>
</Modal>
</>
);
};
export default App;
通过 Modal.useModal 创建支持读取 context 的 contextHolder。
import React, { createContext } from 'react';
import { Button, Modal, Space } from 'antd';
const ReachableContext = createContext<string | null>(null);
const UnreachableContext = createContext<string | null>(null);
const config = {
title: 'Use Hook!',
content: (
<>
<ReachableContext.Consumer>{(name) => `Reachable: ${name}!`}</ReachableContext.Consumer>
<br />
<UnreachableContext.Consumer>{(name) => `Unreachable: ${name}!`}</UnreachableContext.Consumer>
</>
),
};
const App: React.FC = () => {
const [modal, contextHolder] = Modal.useModal();
return (
<ReachableContext.Provider value="Light">
<Space>
<Button
onClick={() => {
modal.confirm(config);
}}
>
Confirm
</Button>
<Button
onClick={() => {
modal.warning(config);
}}
>
Warning
</Button>
<Button
onClick={() => {
modal.info(config);
}}
>
Info
</Button>
<Button
onClick={() => {
modal.error(config);
}}
>
Error
</Button>
</Space>
{/* `contextHolder` should always be placed under the context you want to access */}
{contextHolder}
{/* Can not access this context since `contextHolder` is not in it */}
<UnreachableContext.Provider value="Bamboo" />
</ReachableContext.Provider>
);
};
export default App;
使用 width 来设置模态对话框的宽度。
import React, { useState } from 'react';
import { Button, Modal } from 'antd';
const App: React.FC = () => {
const [open, setOpen] = useState(false);
return (
<>
<Button type="primary" onClick={() => setOpen(true)}>
Open Modal of 1000px width
</Button>
<Modal
title="Modal 1000px width"
centered
open={open}
onOk={() => setOpen(false)}
onCancel={() => setOpen(false)}
width={1000}
>
<p>some contents...</p>
<p>some contents...</p>
<p>some contents...</p>
</Modal>
</>
);
};
export default App;
使用 Modal.destroyAll() 可以销毁弹出的确认窗。通常用于路由监听当中，处理路由前进、后退不能销毁确认对话框的问题。
import React from 'react';
import { ExclamationCircleOutlined } from '@ant-design/icons';
import { Button, Modal } from 'antd';
const { confirm } = Modal;
const destroyAll = () => {
Modal.destroyAll();
};
const showConfirm = () => {
for (let i = 0; i < 3; i += 1) {
setTimeout(() => {
confirm({
icon: <ExclamationCircleOutlined />,
content: <Button onClick={destroyAll}>Click to destroy all</Button>,
onOk() {
console.log('OK');
},
onCancel() {
console.log('Cancel');
},
});
}, i * 500);
}
};
const App: React.FC = () => <Button onClick={showConfirm}>Confirm</Button>;
export default App;
点击确定后异步关闭对话框，例如提交表单。
import React, { useState } from 'react';
import { Button, Modal } from 'antd';
const App: React.FC = () => {
const [open, setOpen] = useState(false);
const [confirmLoading, setConfirmLoading] = useState(false);
const [modalText, setModalText] = useState('Content of the modal');
const showModal = () => {
setOpen(true);
};
const handleOk = () => {
setModalText('The modal will be closed after two seconds');
setConfirmLoading(true);
setTimeout(() => {
setOpen(false);
setConfirmLoading(false);
}, 2000);
};
const handleCancel = () => {
console.log('Clicked cancel button');
setOpen(false);
};
return (
<>
<Button type="primary" onClick={showModal}>
Open Modal with async logic
</Button>
<Modal
title="Title"
open={open}
onOk={handleOk}
confirmLoading={confirmLoading}
onCancel={handleCancel}
>
<p>{modalText}</p>
</Modal>
</>
);
};
export default App;
使用 confirm() 可以快捷地弹出确认框。onCancel/onOk 返回 promise 可以延迟关闭。
import React from 'react';
import { ExclamationCircleFilled } from '@ant-design/icons';
import { Button, Modal, Space } from 'antd';
const { confirm } = Modal;
const showConfirm = () => {
confirm({
title: 'Do you Want to delete these items?',
icon: <ExclamationCircleFilled />,
content: 'Some descriptions',
onOk() {
console.log('OK');
},
onCancel() {
console.log('Cancel');
},
});
};
const showPromiseConfirm = () => {
confirm({
title: 'Do you want to delete these items?',
icon: <ExclamationCircleFilled />,
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!'));
},
onCancel() {},
});
};
const showDeleteConfirm = () => {
confirm({
title: 'Are you sure delete this task?',
icon: <ExclamationCircleFilled />,
content: 'Some descriptions',
okText: 'Yes',
okType: 'danger',
cancelText: 'No',
onOk() {
console.log('OK');
},
onCancel() {
console.log('Cancel');
},
});
};
const showPropsConfirm = () => {
confirm({
title: 'Are you sure delete this task?',
icon: <ExclamationCircleFilled />,
content: 'Some descriptions',
okText: 'Yes',
okType: 'danger',
okButtonProps: {
disabled: true,
},
cancelText: 'No',
onOk() {
console.log('OK');
},
onCancel() {
console.log('Cancel');
},
});
};
const App: React.FC = () => (
<Space wrap>
<Button onClick={showConfirm}>Confirm</Button>
<Button onClick={showPromiseConfirm}>With promise</Button>
<Button onClick={showDeleteConfirm} type="dashed">
Delete
</Button>
<Button onClick={showPropsConfirm} type="dashed">
With extra props
</Button>
</Space>
);
export default App;
通过返回的 instance 手动更新和关闭对话框。
import { Button, Modal } from 'antd';
import React from 'react';
const App: React.FC = () => {
const [modal, contextHolder] = Modal.useModal();
const countDown = () => {
let secondsToGo = 5;
const instance = modal.success({
title: 'This is a notification message',
content: `This modal will be destroyed after ${secondsToGo} second.`,
});
const timer = setInterval(() => {
secondsToGo -= 1;
instance.update({
content: `This modal will be destroyed after ${secondsToGo} second.`,
});
}, 1000);
setTimeout(() => {
clearInterval(timer);
instance.destroy();
}, secondsToGo * 1000);
};
return (
<>
<Button onClick={countDown}>Open modal to close in 5s</Button>
{contextHolder}
</>
);
};
export default App;
传入 okButtonProps 和 cancelButtonProps 可分别自定义确定按钮和取消按钮的 props。
import React, { useState } from 'react';
import { Button, Modal } from 'antd';
const App: React.FC = () => {
const [open, setOpen] = useState(false);
const showModal = () => {
setOpen(true);
};
const handleOk = (e: React.MouseEvent<HTMLElement>) => {
console.log(e);
setOpen(false);
};
const handleCancel = (e: React.MouseEvent<HTMLElement>) => {
console.log(e);
setOpen(false);
};
return (
<>
<Button type="primary" onClick={showModal}>
Open Modal with customized button props
</Button>
<Modal
title="Basic Modal"
open={open}
onOk={handleOk}
onCancel={handleCancel}
okButtonProps={{ disabled: true }}
cancelButtonProps={{ disabled: true }}
>
<p>Some contents...</p>
<p>Some contents...</p>
<p>Some contents...</p>
</Modal>
</>
);
};
export default App;
自定义渲染对话框, 可通过 react-draggable 来实现拖拽。
import React, { useRef, useState } from 'react';
import { Button, Modal } from 'antd';
import type { DraggableData, DraggableEvent } from 'react-draggable';
import Draggable from 'react-draggable';
const App: React.FC = () => {
const [open, setOpen] = useState(false);
const [disabled, setDisabled] = useState(true);
const [bounds, setBounds] = useState({ left: 0, top: 0, bottom: 0, right: 0 });
const draggleRef = useRef<HTMLDivElement>(null);
const showModal = () => {
setOpen(true);
};
const handleOk = (e: React.MouseEvent<HTMLElement>) => {
console.log(e);
setOpen(false);
};
const handleCancel = (e: React.MouseEvent<HTMLElement>) => {
console.log(e);
setOpen(false);
};
const onStart = (_event: DraggableEvent, uiData: DraggableData) => {
const { clientWidth, clientHeight } = window.document.documentElement;
const targetRect = draggleRef.current?.getBoundingClientRect();
if (!targetRect) {
return;
}
setBounds({
left: -targetRect.left + uiData.x,
right: clientWidth - (targetRect.right - uiData.x),
top: -targetRect.top + uiData.y,
bottom: clientHeight - (targetRect.bottom - uiData.y),
});
};
return (
<>
<Button onClick={showModal}>Open Draggable Modal</Button>
<Modal
title={
<div
style={{
width: '100%',
cursor: 'move',
}}
onMouseOver={() => {
if (disabled) {
setDisabled(false);
}
}}
onMouseOut={() => {
setDisabled(true);
}}
// fix eslintjsx-a11y/mouse-events-have-key-events
// https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/mouse-events-have-key-events.md
onFocus={() => {}}
onBlur={() => {}}
// end
>
Draggable Modal
</div>
}
open={open}
onOk={handleOk}
onCancel={handleCancel}
modalRender={(modal) => (
<Draggable
disabled={disabled}
bounds={bounds}
onStart={(event, uiData) => onStart(event, uiData)}
>
<div ref={draggleRef}>{modal}</div>
</Draggable>
)}
>
<p>
Just don't learn physics at school and your life will be full of magic and miracles.
</p>
<br />
<p>Day before yesterday I saw a rabbit, and yesterday a deer, and today, you.</p>
</Modal>
</>
);
};
export default App;
在绝大多数场景，都不需要静态方法。它无法消费 context，例如无法响应动态主题。请优先使用 hooks 版本或者 App 组件提供的 Modal 实例。
import React from 'react';
import { Button, Modal, Space } from 'antd';
const info = () => {
Modal.info({
title: 'This is a notification message',
content: (
<div>
<p>some messages...some messages...</p>
<p>some messages...some messages...</p>
</div>
),
onOk() {},
});
};
const success = () => {
Modal.success({
content: '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...',
});
};
const App: React.FC = () => (
<Space wrap>
<Button onClick={info}>Info</Button>
<Button onClick={success}>Success</Button>
<Button onClick={error}>Error</Button>
<Button onClick={warning}>Warning</Button>
</Space>
);
export default App;
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| afterClose | Modal 完全关闭后的回调 | function | - | |
| bodyStyle | Modal body 样式 | CSSProperties | ||
| cancelButtonProps | cancel 按钮 props | ButtonProps | - | |
| cancelText | 取消按钮文字 | ReactNode | 取消 | |
| centered | 垂直居中展示 Modal | boolean | false | |
| closable | 是否显示右上角的关闭按钮 | boolean | true | |
| closeIcon | 自定义关闭图标 | ReactNode | <CloseOutlined /> | |
| confirmLoading | 确定按钮 loading | boolean | false | |
| destroyOnClose | 关闭时销毁 Modal 里的子元素 | boolean | false | |
| focusTriggerAfterClose | 对话框关闭后是否需要聚焦触发元素 | boolean | true | 4.9.0 |
| footer | 底部内容，当不需要默认底部按钮时，可以设为 footer={null} | ReactNode | (确定取消按钮) | |
| forceRender | 强制渲染 Modal | boolean | false | |
| getContainer | 指定 Modal 挂载的节点，但依旧为全局展示，false 为挂载在当前位置 | HTMLElement | () => HTMLElement | Selectors | false | document.body | |
| keyboard | 是否支持键盘 esc 关闭 | boolean | true | |
| mask | 是否展示遮罩 | boolean | true | |
| maskClosable | 点击蒙层是否允许关闭 | boolean | true | |
| maskStyle | 遮罩样式 | CSSProperties | ||
| modalRender | 自定义渲染对话框 | (node: ReactNode) => ReactNode | - | 4.7.0 |
| okButtonProps | ok 按钮 props | ButtonProps | - | |
| okText | 确认按钮文字 | ReactNode | 确定 | |
| okType | 确认按钮类型 | string | primary | |
| style | 可用于设置浮层的样式，调整浮层位置等 | CSSProperties | - | |
| title | 标题 | ReactNode | - | |
| open | 对话框是否可见 | boolean | - | |
| width | 宽度 | string | number | 520 | |
| wrapClassName | 对话框外层容器的类名 | string | - | |
| zIndex | 设置 Modal 的 z-index | number | 1000 | |
| onCancel | 点击遮罩层或右上角叉或取消按钮的回调 | function(e) | - | |
| onOk | 点击确定回调 | function(e) | - | |
| afterOpenChange | 打开和关闭 Modal 时动画结束后的回调 | (open: boolean) => void | - | 5.4.0 |
<Modal /> 默认关闭后状态不会自动清空, 如果希望每次打开都是新内容，请设置 destroyOnClose。<Modal /> 和 Form 一起配合使用时，设置 destroyOnClose 也不会在 Modal 关闭时销毁表单字段数据，需要设置 <Form preserve={false} />。Modal.method() RTL 模式仅支持 hooks 用法。包括：
Modal.infoModal.successModal.errorModal.warningModal.confirm以上均为一个函数，参数为 object，具体属性如下：
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| afterClose | Modal 完全关闭后的回调 | function | - | 4.9.0 |
| autoFocusButton | 指定自动获得焦点的按钮 | null | ok | cancel | ok | |
| bodyStyle | Modal body 样式 | CSSProperties | 4.8.0 | |
| cancelButtonProps | cancel 按钮 props | ButtonProps | - | |
| cancelText | 设置 Modal.confirm 取消按钮文字 | string | 取消 | |
| centered | 垂直居中展示 Modal | boolean | false | |
| className | 容器类名 | string | - | |
| closable | 是否显示右上角的关闭按钮 | boolean | false | 4.9.0 |
| closeIcon | 自定义关闭图标 | ReactNode | undefined | 4.9.0 |
| content | 内容 | ReactNode | - | |
| footer | 底部内容，当不需要默认底部按钮时，可以设为 footer: null | ReactNode | - | 5.1.0 |
| getContainer | 指定 Modal 挂载的 HTML 节点, false 为挂载在当前 dom | HTMLElement | () => HTMLElement | Selectors | false | document.body | |
| icon | 自定义图标 | ReactNode | <ExclamationCircleFilled /> | |
| keyboard | 是否支持键盘 esc 关闭 | boolean | true | |
| mask | 是否展示遮罩 | boolean | true | |
| maskClosable | 点击蒙层是否允许关闭 | boolean | false | |
| maskStyle | 遮罩样式 | object | {} | |
| okButtonProps | ok 按钮 props | ButtonProps | - | |
| okText | 确认按钮文字 | string | 确定 | |
| okType | 确认按钮类型 | string | primary | |
| style | 可用于设置浮层的样式，调整浮层位置等 | CSSProperties | - | |
| title | 标题 | ReactNode | - | |
| width | 宽度 | string | number | 416 | |
| wrapClassName | 对话框外层容器的类名 | string | - | 4.18.0 |
| zIndex | 设置 Modal 的 z-index | number | 1000 | |
| onCancel | 取消回调，参数为关闭函数，返回 promise 时 resolve 后自动关闭 | function(close) | - | |
| onOk | 点击确定回调，参数为关闭函数，返回 promise 时 resolve 后自动关闭 | function(close) | - |
以上函数调用后，会返回一个引用，可以通过该引用更新和关闭弹窗。
const modal = Modal.info();modal.update({title: '修改的标题',content: '修改的内容',});// 在 4.8.0 或更高版本中，可以通过传入函数的方式更新弹窗modal.update((prevConfig) => ({...prevConfig,title: `${prevConfig.title}（新）`,}));modal.destroy();
Modal.destroyAll使用 Modal.destroyAll() 可以销毁弹出的确认窗（即上述的 Modal.info、Modal.success、Modal.error、Modal.warning、Modal.confirm）。通常用于路由监听当中，处理路由前进、后退不能销毁确认对话框的问题，而不用各处去使用实例的返回值进行关闭（modal.destroy() 适用于主动关闭，而不是路由这样被动关闭）
import { browserHistory } from 'react-router';// router changebrowserHistory.listen(() => {Modal.destroyAll();});
当你需要使用 Context 时，可以通过 Modal.useModal 创建一个 contextHolder 插入子节点中。通过 hooks 创建的临时 Modal 将会得到 contextHolder 所在位置的所有上下文。创建的 modal 对象拥有与 Modal.method 相同的创建通知方法。
const [modal, contextHolder] = Modal.useModal();React.useEffect(() => {modal.confirm({// ...});}, []);return <div>{contextHolder}</div>;
Modal 在关闭时会将内容进行 memo 从而避免关闭过程中的内容跳跃。也因此如果你在配合使用 Form 有关闭时重置 initialValues 的操作，请通过在 effect 中调用 resetFields 来重置。
locale/prefixCls/theme 等配置？直接调用 Modal 方法，antd 会通过 ReactDOM.render 动态创建新的 React 实体。其 context 与当前代码所在 context 并不相同，因而无法获取 context 信息。
当你需要 context 信息（例如 ConfigProvider 配置的内容）时，可以通过 Modal.useModal 方法会返回 modal 实体以及 contextHolder 节点。将其插入到你需要获取 context 位置即可：
const [modal, contextHolder] = Modal.useModal();return (<Context1.Provider value="Ant">{/* contextHolder 在 Context1 内，它可以获得 Context1 的 context */}{contextHolder}<Context2.Provider value="Design">{/* contextHolder 在 Context2 外，因而不会获得 Context2 的 context */}</Context2.Provider></Context1.Provider>);
异同：通过 hooks 创建的 contextHolder 必须插入到子元素节点中才会生效，当你不需要上下文信息时请直接调用。
可通过 App 包裹组件 简化
useModal等方法需要手动植入 contextHolder 的问题。
你可以通过 ConfigProvider.config 进行设置。