对话框 Modal — Arco Design v2.66.18 文档

在当前页面打开一个浮层，承载相关操作。

安装

npm install @arco-design/web-react@2.66.18

在入口引入 @arco-design/web-react/dist/css/arco.css，用 ConfigProvider 设置语言。React 19 项目还需在入口最先引入 @arco-design/web-react/es/_util/react-19-adapter，否则 Message、Modal 等命令式 API 无法渲染。

示例

基础用法：文本信息对话框。
异步关闭：在对话框中使用表单时，如提交表单，点击确定后异步关闭对话框。
自定义页脚：传入 okButtonProps 和 cancelButtonProps 可分别自定义确定按钮和取消按钮的 props。如果 okButtonProps 、 cancelButtonProps 仍然不能满足需要的话，可以直接传入footer来自定义页脚内容。
自定义标题：title 支持传入文字或者 react 节点，支持各种场景的标题栏展示。
确认对话框：使用Modal.confirm()，可以快速弹出对话框。
消息提示：有 info, success, warning, error 四种类型的消息提示，仅提供一个确认按钮用于关闭消息提示对话框。
定制按钮文字：设置 okText 与 cancelText 以自定义按钮文字。
手动更新和移除：手动更新和关闭通过 Modal的方法创建的对话框。
自定义位置：使用 alignCenter 结合 style 来设置对话框位置。
数据请求加载：对话框中显示 loading 效果。
带有通知对话框：对话框中显示 Alert.
带有步骤条对话框：带有横向步骤条的对话框。
自定义渲染对话框：可以通过 modalRender 来自定义渲染对话框，实现拖拽功能。
Hooks 用法：可以通过 useModal 去创建可以读取 context 的对话框。

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

API

参数名	描述	类型	默认值	版本
alignCenter	弹出框垂直水平居中	boolean	`true`	-
autoFocus	是否默认聚焦第一个可聚焦元素，只在 `focusLock` 开启时生效。	boolean	`true`	-
closable	是否显示右上角的关闭按钮	boolean	`-`	-
confirmLoading	确认按钮加载中	boolean	`-`	-
escToExit	按 `ESC` 键关闭	boolean	`true`	-
focusLock	是否将焦点锁定在弹出框内	boolean	`true`	-
mask	是否显示遮罩	boolean	`true`	-
maskClosable	点击蒙层是否可以关闭	boolean	`true`	-
mountOnEnter	是否在初次打开对话框时才渲染 dom	boolean	`true`	-
simple	简洁模式的样式，没有分割线，底部按钮居中显示。默认通过方法调用的提示类型的弹窗会展示`simple`样式。设置为true时，默认不显示右上角关闭图标	boolean	`-`	-
unmountOnExit	是否在隐藏之后销毁DOM结构	boolean	`-`	-
visible	弹出框是否可见	boolean	`-`	-
cancelText	取消按钮文案	ReactNode	`-`	-
closeIcon	自定义右上角的关闭按钮节点	ReactNode	`-`	2.21.0
okText	确认按钮文案	ReactNode	`-`	-
title	弹出框的标题	string \| ReactNode	`-`	-
cancelButtonProps	取消按钮的 props	ButtonProps	`-`	-
className	节点类名	string \| string[]	`-`	-
maskStyle	蒙层的样式	CSSProperties	`-`	2.6.0
okButtonProps	确认按钮的 props	ButtonProps	`-`	-
onOk	点击确认按钮的回调	(e?: MouseEvent) => Promise<any> \| void	`-`	-
style	节点样式	CSSProperties	`-`	-
wrapClassName	弹出框外层 dom 类名	string \| string[]	`-`	-
wrapStyle	弹出框外层样式	CSSProperties	`-`	2.16.0
afterClose	弹框关闭之后的回调	() => void	`-`	-
afterOpen	弹框打开之后的回调	() => void	`-`	-
footer	自定义页脚，传入 null 则不显示	ReactNode \| ((cancelButtonNode: ReactNode, okButtonNode: ReactNode) => ReactNode)	`-`	2.12.0
getChildrenPopupContainer	对话框里的弹出框 `Select` `Tooltip` 等挂载的容器，默认挂载在对话框内。	(node: HTMLElement) => Element	`-`	-
getPopupContainer	指定弹出框挂载的父节点	() => Element	`() => document.body`	-
modalRender	自定义渲染对话框	(modalNode: ReactNode) => ReactNode	`-`	2.2.0
onCancel	关闭弹出框的回调	() => void	`-`	-

Modal.method(config)

包括以下几种：

Modal.confirm(config)
Modal.info(config)
Modal.success(config)
Modal.warning(config)
Modal.error(config)

以上函数都会返回一个对象，可用来更新或者关闭对话框。如：

const info = Modal.info({ title: 'Info' });
info.update({ title: 'Updated Title' });
info.close();

config 的具体参数如下所示（继承所有 Modal 的参数）：

参数名	描述	类型	默认值
content	对话框的内容	`ReactNode`	`-`
icon	自定义图标	`ReactNode \| null`	`-`

Modal.config 方法

全局设置 Modal.confirm|success|info|error|warning 的属性，类似 Message.config 方法，<Modal /> 的使用方式会从 ConfigProvider 获取上下文配置。

Modal.config({
  // 自定义前缀
  prefixCls: 'arco',
  // 是否静态方法以简洁样式展示信息
  simple: true
});

Modal.destroyAll 方法

调用 Modal.destroyAll，会关闭所有弹出的确认框（包括 Modal.confirm Modal.info Modal.success Modal.error Modal.warning），一般用于路由改动时，关闭所有弹出。

Modal.destroyAll();

Modal.useModal 方法

通过方法去使用对话框，像是 Modal.confirm Modal.warning，因为是通过 ReactDOM.render 直接渲染，所以不在上下文中，因此拿不到 context。如果希望获取上下文 context，那么可以通过 useModal 去通过 hook 的方法调用，将 contextHolder 放到上下文中。

const [modal, contextHolder] = Modal.useModal();

<Context.Provider>
  {contextHolder}
  <Button onClick={() => modal.warning({ title: 'Title', content: 'content' })}>Open</Button>
</Context.Provider>