---
title: Modal - 对话框
path: /modal
nav:
  order: 1
  title: 桌面组件
  path: /design
group:
  order: 6
  title: 反馈组件
  path: /feedback
---

对话框是一种临时窗口，通常在不想中断整体任务流程，但又需要为用户展示信息或获得用户响应时，在页面中打开一个对话框承载相应的信息及操作。

## 确认类对话框

指带有取消及主要操作，指导用户进行二次确认的对话框。常用于反馈或容错的场景。

<code src="./demos/base.tsx" height="400px" />

## 反馈类对话框

指显示某操作结果的对话框，标题区域有图标，仅有一个确认按钮。常用于操作后结果的展示，或危险、警告等信息的展示。

<code src="./demos/confirm.tsx" height="400px" />

## 异步关闭类对话框

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

<code src="./demos/async.tsx" height="400px" />

## 自定义类对话框

可自定义对话框内容和底部按钮。

<code src="./demos/custom.tsx" height="400px" />

## 操作按钮自定义

<code src="./demos/button.tsx" height="400px" />

## 自定义位置

使用 alignCenter 结合 style 来设置对话框位置。

<code src="./demos/position.tsx" height="400px" />

## 最大宽度的弹窗

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

<code src="./demos/biggest.tsx" height="400px" />

## API

| 参数                   | 说明                                                            | 类型                                                   | 默认值                           | 版本  |
| ---------------------- | --------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------- | ----- |
| afterClose             | Modal 完全关闭后的回调                                          | function                                               | -                                |       |
| bodyStyle              | Modal body 样式                                                 | CSSProperties                                          |                                  |       |
| cancelButtonProps      | cancel 按钮 props                                               | ButtonProps                                            | -                                |       |
| cancelText             | 取消按钮文字                                                    | ReactNode                                              | 取消                             |       |
| centered               | 垂直居中展示 Modal                                              | boolean                                                | false                            |       |
| closable               | 是否显示右上角的关闭按钮                                        | boolean                                                | true                             |       |
| closeIcon              | 自定义关闭图标                                                  | ReactNode                                              | `<Icon iconName="CloseSmall" />` |       |
| confirmLoading         | 确定按钮 loading                                                | boolean                                                | false                            |       |
| destroyOnClose         | 关闭时销毁 Modal 里的子元素                                     | boolean                                                | false                            |       |
| focusTriggerAfterClose | 对话框关闭后是否需要聚焦触发元素                                | boolean                                                | true                             | 4.9.0 |
| forceRender            | 强制渲染 Modal                                                  | boolean                                                | false                            |       |
| getContainer           | 指定 Modal 挂载的节点，但依旧为全局展示，false 为挂载在当前位置 | HTMLElement \| () => HTMLElement \| Selectors \| false | document.body                    |       |
| keyboard               | 是否支持键盘 esc 关闭                                           | booelan                                                | true                             |
| mask                   | 是否展示遮罩                                                    | booelan                                                | true                             |
| maskClosable           | 点击蒙层是否允许关闭                                            | booelan                                                | true                             |
| maskStyle              | 遮罩样式                                                        | CSSProperties                                          |                                  |
| modalRender            | 自定义渲染对话框                                                | `(node: ReactNode) => ReactNode`                       |                                  |
| okButtonProps          | ok 按钮 props                                                   | ButtonProps                                            |                                  |
| okText                 | 确认按钮文字                                                    | ReactNode                                              | `确定`                           |
| okType                 | 确认按钮类型                                                    | string                                                 | `primary`                        |
| style                  | 可用于设置浮层的样式，调整浮层位置等                            | CSSProperties                                          | -                                |
| title                  | 标题                                                            | ReactNode                                              | -                                |
| visible                | 对话框是否可见                                                  | boolean                                                | -                                |
| width                  | 宽度                                                            | string\|number                                         | 400                              |
| wrapClassName          | 对话框外层容器的类名                                            | string                                                 | -                                |
| zIndex                 | 设置 Modal 的 z-index                                           | number                                                 | 1000                             |
| onOk                   | 点击确定回调                                                    | function(e)                                            |                                  |
| onCancel               | 点击取消回调                                                    | function(e)                                            |                                  |

## 注意

- Modal 默认关闭后状态不会自动清空, 如果希望每次打开都是新内容，请设置 destroyOnClose。
- Modal 和 Form 一起配合使用时，设置 destroyOnClose 也不会在 Modal 关闭时销毁表单字段数据，需要设置 `<Form preserve={false} >`。
- Modal.method() RTL 模式仅支持 hooks 用法。

## Modal.method()

包括：

- Modal.info
- Modal.success
- Modal.error
- Modal.warning
- Modal.confirm

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

| 参数              | 说明                                                            | 类型                                                   | 默认值                           | 版本 |
| ----------------- | --------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------- | ---- |
| afterClose        | Modal 完全关闭后的回调                                          | function                                               | -                                |      |
| bodyStyle         | Modal body 样式                                                 | CSSProperties                                          |                                  |      |
| cancelButtonProps | cancel 按钮 props                                               | ButtonProps                                            | -                                |      |
| cancelText        | 取消按钮文字                                                    | ReactNode                                              | 取消                             |      |
| centered          | 垂直居中展示 Modal                                              | boolean                                                | false                            |      |
| closable          | 是否显示右上角的关闭按钮                                        | boolean                                                | true                             |      |
| closeIcon         | 自定义关闭图标                                                  | ReactNode                                              | `<Icon iconName="CloseSmall" />` |      |
| autoFocusButton   | 指定自动获得焦点的按钮                                          | null \| ok \| cancel                                   | ok                               |      |
| className         | 容器类名                                                        | string                                                 | -                                |      |
| content           | 内容                                                            | ReactNode                                              | -                                |      |
| getContainer      | 指定 Modal 挂载的节点，但依旧为全局展示，false 为挂载在当前位置 | HTMLElement \| () => HTMLElement \| Selectors \| false | document.body                    |      |
| icon              | 自定义图标                                                      | ReactNode                                              |                                  |      |
| zIndex            | 设置 Modal 的 z-index                                           | number                                                 | 1000                             |
| onOk              | 点击确定回调                                                    | function(e)                                            |                                  |
| onCancel          | 点击取消回调                                                    | function(e)                                            |                                  |
| keyboard          | 是否支持键盘 esc 关闭                                           | booelan                                                | true                             |
| mask              | 是否展示遮罩                                                    | booelan                                                | true                             |
| maskClosable      | 点击蒙层是否允许关闭                                            | booelan                                                | true                             |
| maskStyle         | 遮罩样式                                                        | CSSProperties                                          |                                  |
| modalRender       | 自定义渲染对话框                                                | `(node: ReactNode) => ReactNode`                       |                                  |
| okButtonProps     | ok 按钮 props                                                   | ButtonProps                                            |                                  |
| okText            | 确认按钮文字                                                    | ReactNode                                              | `确定`                           |
| okType            | 确认按钮类型                                                    | string                                                 | `primary`                        |
| style             | 可用于设置浮层的样式，调整浮层位置等                            | CSSProperties                                          | -                                |
| title             | 标题                                                            | ReactNode                                              | -                                |
| visible           | 对话框是否可见                                                  | boolean                                                | -                                |
| width             | 宽度                                                            | string\|number                                         | 400                              |
| wrapClassName     | 对话框外层容器的类名                                            | string                                                 | -                                |
| zIndex            | 设置 Modal 的 z-index                                           | number                                                 | 1000                             |
| onOk              | 点击确定回调                                                    | function(e)                                            |                                  |
| onCancel          | 点击取消回调                                                    | function(e)                                            |                                  |
| type              | 默认的宽度样式还是超大宽度样式                                  | default \| biggest                                     | `default`                        |
| noContent         | 是否不显示内容                                                  | boolean                                                | false                            |

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

```javascript
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()` 适用于主动关闭，而不是路由这样被动关闭）

```javascript
import { browserHistory } from 'react-router';

// router change
browserHistory.listen(() => {
  Modal.destroyAll();
});
```

## Modal.useModal()

当你需要使用 Context 时，可以通过 `Modal.useModal` 创建一个 `contextHolder` 插入子节点中。通过 hooks 创建的临时 Modal 将会得到 `contextHolder` 所在位置的所有上下文。创建的 `modal` 对象拥有与 `Modal.method` 相同的创建通知方法。

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

React.useEffect(() => {
  modal.confirm({
    // ...
  });
}, []);

return <div>{contextHolder}</div>;
```