# 对话框 Modal

- 页面: https://jiguang132.com/zh/resources/arco-design/docs/modal
- 资源: Arco Design (https://jiguang132.com/zh/resources/arco-design.md)
- 全部指南: https://jiguang132.com/zh/resources/arco-design/docs.md

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

## 安装

```bash
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

### Modal

|参数名|描述|类型|默认值|版本|
|---|---|---|---|---|
|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)`

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

```js
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` 获取上下文配置。

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

### Modal.destroyAll 方法

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

```js
Modal.destroyAll();
```

### Modal.useModal 方法

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

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

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

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt