展示类 · Modal
模态对话框
模态对话框用于等待用户响应、告知用户重要信息或在不丢失上下文的情况下展示更多信息

代码演示

如何引入

基本

点击遮罩层不可关闭

修改 maskClosablefalse 则不可通过点击遮罩层来关闭对话框。

自定义按钮文字

通过设置 okTextcancelText 属性可自定义按钮显示的文字。
注意:命令式调用的 Modal 需要通过这两个属性来设置 i18 的文本,因为我们无法修改 React 组件树,命令式调用插入的 Component 无法消费到 Locale 相关的 Context

自定义按钮属性

通过设置 okButtonPropscancelButtonProps 属性可自定义按钮的属性。

自定义对话框头部和页脚

如果需要实现更丰富的个性化需求,可以通过 header 自定义头部,footer 自定义页脚的按钮。把 header 设为 null时则不展示头部区域;不需要显示任何按钮时,同样可以把 footer 设为 null

自定义对话框的样式

通过设置 style 可以自定义样式及位置如 style.top,也可以通过 centered 使对话框居中显示。也可以通过设置 maskStyle 自定义遮罩样式,及 bodyStyle 自定义对话框内容样式。

自定义的对话框

通过灵活使用使用 headerfooter等属性可以实现一个完全自定义的对话框。

全屏 Modal

使用 fullScreen={true} 可以开启全屏对话框

命令式调用

使用 confirm() 可以设置一个确认框。支持各种类型的信息提示。命令式调用也可以自定义 icon , 支持 string 和 ReactNode 类型。其他 Modal 支持的 props 都可以传入。

Hooks 用法

通过 Modal.useModal 创建支持读取 context 的 contextHolder。

API 参考

属性说明类型默认值
afterClose对话框完全关闭后的回调函数
v1.16.0 后提供
() => void
bodyStyle对话框内容的样式CSSProperties
cancelButtonProps取消按钮的 propsButtonProps
cancelText取消按钮的文字string
centered是否居中显示booleanfalse
className可用于设置样式类名string
closable是否显示右上角的关闭按钮booleantrue
closeIcon关闭按钮的 icon
v1.0.0 后提供
ReactNode<IconClose />
closeOnEsc允许通过键盘事件 Esc 触发关闭
v1.0.0 后提供
booleantrue
confirmLoading确认按钮 loadingbooleanfalse
content对话框内容ReactNode
footer对话框底部ReactNode
fullScreen对话是否是全屏(会覆盖 width height)
v1.18.0 后提供
booleanfalse
getPopupContainer指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relative
v0.33.0 后提供
() => HTMLElement() => document.body
hasCancel是否显示取消按钮booleantrue
header对话框头部ReactNode
height高度number
icon自定义 icon
v1.1.0 后提供
ReactNode-
keepDOM关闭对话框时是否销毁
v1.0.0 后提供
booleanfalse
lazyRender配合 keepDOM 使用,为 true 时挂载时不会渲染对话框组件
v1.0.0 后提供
booleantrue
mask是否显示遮罩booleantrue
maskClosable是否允许通过点击遮罩来关闭对话框booleantrue
maskStyle遮罩的样式CSSProperties
motion动画效果开关booleantrue
okButtonProps确认按钮的 propsButtonProps
okText确认按钮的文字string
okType确认按钮的类型, 可选: 'primary'、'secondary'、'tertiary'、'warning'、'danger'stringprimary
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法,不包含用户传入的组件boolean
size对话框宽度尺寸,支持 small(448px), medium(684px), large(920px),full-width(100vw - 64px)
v1.0.0 后提供
string'small'
style可用于设置样式CSSProperties
title对话框的标题ReactNode
visible对话框是否可见booleanfalse
width宽度number448
zIndex遮罩的 z-index 值number1000
onCancel取消对话框时的回调函数(e: any) => void | Promise<any>
onOk点击确认按钮时的回调函数(e: any) => void | Promise<any>
  • Modal.info
  • Modal.success
  • Modal.error
  • Modal.warning
  • Modal.confirm
属性说明类型默认值
bodyStyle对话框内容的样式CSSProperties
cancelButtonProps取消按钮的 propsButtonProps
cancelText取消按钮的文字string
centered是否居中显示booleanfalse
className可用于设置样式类名string
closable是否显示右上角的关闭按钮booleantrue
confirmLoading确认按钮 loadingbooleanfalse
content对话框内容ReactNode
footer对话框底部ReactNode
header对话框头部ReactNode
height高度number
icon自定义 iconReactNode-
mask是否显示遮罩booleantrue
maskClosable是否允许通过点击遮罩来关闭对话框booleantrue
maskStyle遮罩的样式CSSProperties
okButtonProps确认按钮的 propsButtonProps
okText确认按钮的文字string
okType确认按钮的类型stringprimary
style可用于设置样式CSSProperties
title对话框的标题ReactNode
width宽度number520
zIndex遮罩的 z-index 值number1000
onCancel取消回调,参数为关闭函数,返回 promise 时 resolve 后自动关闭(e: any) => void | Promise<any>
onOk点击确定回调,参数为关闭函数,返回 promise 时 resolve 后自动关闭(e: any) => void | Promise<any>
以上函数调用后,会返回一个引用,可以通过该引用更新和关闭弹窗。
  • Modal.destroyAll v>=0.37.0
使用 Modal.destroyAll() 可以销毁命令式及以上.info()等创建的弹窗。
  • Modal.useModal v>=1.2.0
    当你需要使用 Context 时,可以通过 Modal.useModal 创建一个 contextHolder 插入相应的节点中。此时通过 hooks 创建的 Modal 将会得到 contextHolder 所在位置的所有上下文。创建的 modal 对象拥有与 Modal.method 相同的创建通知方法。

Accessibility

ARIA

  • role 设置为 dialog
  • aria-modal 设置为 true
  • aria-labelledby 对应 Modal header
  • aria-describedby 对应 Modal body

键盘和焦点

  • Modal 在弹出时自动获得焦点,关闭时焦点自动回归到打开前元素。
  • 键盘用户可以使用 Tab 键和 Shift + Tab,将焦点在 Modal 内移动,包括 Modal 自带的关闭按钮和确定取消按钮,此时 Modal 背后元素不可被 tab 聚焦。
  • Modal 打开时默认聚焦到取消按钮, 可通过在 cancelButtonProps 或 okButtonProps 传入 autoFocus 来控制该行为。
  • 可通过在 Modal 内容中需要聚焦的表单元素上添加 autoFocus 来让 Modal 打开时自动聚焦到该元素 (需同时设置 cancelButtonProps 的 autoFocus 为 false)。
  • 修改 closeOnEsc 默认值为 true,允许用户通过键盘直接关闭 Modal 带来更好的体验

文案规范

  • 命令式 Modal 与 默认 Modal 两种模态对话框的标题使用 动词 + 名词 的格式,无论是陈述句还是问句
✅ 推荐用法❌ 不推荐用法
Edit ticketEdit
Delete form?Are you sure you want to delete form?
  • 两种模态对话框的操作按钮在保证标题描述清楚的前提下,只需要使用标题内的动词即可
✅ 推荐用法❌ 不推荐用法
EditEdit ticket
  • 命令式 Modal 的正文规范
    • 对标题进行具体的解释说明,不要重复标题的信息
    • 确保用户知道在必要时如何采取行动

设计变量

FAQ

  • 为什么使用 LocaleProvider 后, Modal.confirm 确认、取消按钮的文本没有国际化?

    Modal 使用 Portal 将浮层节点插入到 DOM 树中。但这个操作仅能改变节点在 DOM 树中的位置,无法改变节点在 React 节点树中的位置,LocalProvider是基于 Context 机制传递的,必须是从属的 React 子结点才可消费到 Local 相关 Context。因此命令式的 Modal 的内置文本无法自动适配国际化。 你可以通过 okTextcancelText 这两个属性来根据 Locale 重新设置 i18 的文本。
    在1.2版本之后,你也可以通过 Modal.useModal 方法来返回 modal 实体以及 contextHolder 节点。将 contextHolder 插入到你需要获取 context 位置,即可使 Modal 获取到对应的 Context,如 ConfigProvider 或者 LocaleProvider 的配置。
  • 为什么 title 和 content 的间距在命令式调用和非命令式调用下不同?

    命令式调用场景下,标题和内容的相关性更强,所以用更近的距离表达这种强相关性,符合预期。用户如果不想要这种效果,可以自己做样式覆盖。