展示类 · 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 带来更好的体验

设计变量

FAQ

  • 为什么使用 LocaleProvider 后, Modal.confirm 确认、取消按钮的文本没有国际化? 在1.2版本之后,当你需要获取 context 信息,如 ConfigProvider 或者 LocaleProvider 的配置时,可以通过 Modal.useModal 方法来返回 modal 实体以及 contextHolder 节点。将 contextHolder 插入到你需要获取 context 位置即可。
    如果是1.2版本之前,或者不想使用 Hooks 的写法,也可以通过 okTextcancelText 这两个属性来设置 i18 的文本。

© 2021 Semi Design. All rights reserved.

京ICP备19058139号-13浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED