模态框向用户提供与其试图完成的任务相关的信息和选择。它们可以包含关键信息、要求做出决策，或涉及多个任务。
设计指南
用法
模态框是一种浮动窗口类型，它出现在内容前方以提供关键信息或请求决策。模态框出现时会禁用所有其他功能。模态框会保留在屏幕上，直到用户确认、关闭或采取所需的操作。
虽然模态框可以是披露额外控件或信息的有效方式，但它们也可能成为用户的干扰源。因此，务必质疑模态框是否有必要，并努力避免需要它们的情况。
原则
- 聚焦。模态框将用户的注意力从屏幕其余部分拉开，以集中他们的注意力，确保处理模态框的内容。
- 直接。模态框文本应传达重要信息，并专门帮助用户恰当地完成任务。
- 有帮助。模态框应在响应用户任务或操作时出现，以提供相关且上下文相关的信息。
使用场景
模态框用于：
- 阻止正常运行的错误。
- 需要特定用户任务、决策或确认的关键信息。
- 在响应用户任务或操作时出现的上下文信息。
结构
- 容器
- 标题
- 辅助文本
- 按钮
- 遮罩层（Scrim）
- 关闭按钮（可选）
模态框和遮罩层
模态框是一种窗口类型。在解决模态框之前，对 UI 其余部分的访问将被禁用。所有模态框在设计上都是中断性的——其目的是让用户专注于内容，因此模态框表面会显示在所有其他表面之上。
为了澄清屏幕其余部分不可访问并将注意力集中在模态框上，模态框后面的表面会被遮罩覆盖——它们获得一个临时叠加层以隐藏其内容并使其不那么突出。
标题
模态框的目的通过其标题和按钮文本来传达。
出于无障碍原因，所有模态框都应具有标题（可以使用 contentLabel 属性来设置不可见的标题）。
标题应：
- 包含简短、清晰的陈述或问题
- 避免道歉（“抱歉打扰”）、警报（“警告！”）或歧义（“你确定吗？”）。
应该这样做
此模态框标题提出了一个具体的问题，简洁地解释了请求的目的，并提供了清晰的操作。
不应该这样做
此模态框造成了歧义，从而引起不安——它让用户不确定如何回应，或者导致他们对自己的答案产生怀疑。
按钮
并排按钮（推荐）
并排按钮将两个文本按钮并排显示。
堆叠或全宽按钮
当您需要容纳更长的按钮文本时，请使用堆叠按钮。始终将确认操作放置在取消操作之上。
行为
模态框会在没有警告的情况下出现，要求用户停止当前任务。应谨慎使用模态框——并非每个选择或设置都需要这种突然的中断。
位置
模态框保持焦点，直到被取消或用户完成某项操作（如选择设置）。它们不应被其他元素遮挡，也不应只显示在屏幕的一部分。
滚动
大多数模态框内容应避免滚动。如果模态框内容超出模态框的高度（例如，具有许多行的列表组件），则允许滚动。当模态框滚动时，模态框标题固定在顶部，按钮固定在底部。这确保了即使在滚动时，内容也能与标题和按钮一起可见。
模态框不会随着模态框外的元素（如背景）一起滚动。
查看可滚动的选项列表时，模态框标题和按钮保持固定。
关闭模态框
模态框可以通过三种方式关闭：
- 点击模态框外部
- 点击“取消”按钮
- 点击“关闭”图标按钮，或按
esc键
如果禁用了用户关闭模态框的能力，则必须选择一个模态框操作才能继续。
开发指南
该模态框用于在应用程序上方创建无障碍模态框。
注意：此模态框的 API 已被模仿以 resemble react-modal。
用法
以下示例向您展示如何正确实现模态框。为了使模态框正常工作，正确地实现模态框的关闭逻辑非常重要。
import { useState } from 'react';
import { Button, Modal } from '@wordpress/components';
const MyModal = () => {
const [ isOpen, setOpen ] = useState( false );
const openModal = () => setOpen( true );
const closeModal = () => setOpen( false );
return (
<>
<Button variant="secondary" onClick={ openModal }>
Open Modal
</Button>
{ isOpen && (
<Modal title="This is my modal" onRequestClose={ closeModal }>
<Button variant="secondary" onClick={ closeModal }>
My custom close button
</Button>
</Modal>
) }
</>
);
};
属性
组件接受的属性集将在下面指定。
未包含在此集中的属性将应用于输入元素。
aria.describedby: string
如果添加此属性，它将作为 aria-describedby 添加到模态框内容 div 中。
- 必需：否
aria.labelledby: string
如果添加此属性，它将作为 aria-labelledby 添加到模态框内容 div 中。
当您自己在模态框的内容区域内渲染标题而不是使用 title 属性时使用此方法。这确保标题可供辅助技术使用。
出于无障碍原因，标题是必需的，有关提供标题的其他方法，请参阅 contentLabel 和 title。
- 必需：否
- 默认值：如果提供了
title属性，则默认为渲染title的元素 ID
bodyOpenClassName: string
模态框打开时添加到 body 元素的类名。
如果使用自定义类名，其样式必须设置 overflow: hidden 以保持模态框的滚动锁定。
- 必需：否
- 默认值：
modal-open
className: string
如果添加此属性，它将作为额外的类名添加到模态框内容 div 中。
- 必需：否
contentLabel: string
如果添加此属性，它将作为 aria-label 添加到模态框内容 div 中。
出于无障碍原因，标题是必需的，有关提供标题的其他方法，请参阅 aria.labelledby 和 title。
- 必需：否
focusOnMount: boolean | ‘firstElement’ | ‘firstContentElement’
如果此属性为 true，它将聚焦于模态框中呈现的第一个可导航元素。
如果此属性为 false，焦点将不会转移，确保无障碍焦点管理是消费者的责任。
如果设置为 firstElement，焦点将放置在模态框内的任何第一个可导航元素上。
如果设置为 firstContentElement，焦点将放置在模态框内容（即子元素）内的第一个可导航元素上。请注意，确保子元素内至少有一个可导航元素是消费者的责任，否则焦点将会丢失。
- 必需：否
- 默认值：
true
headerActions
一个可选的 React 节点，旨在包含与模态框相关的其他操作或其他元素，例如按钮。内容渲染在模态框的右上角，并且在关闭按钮（如果可见）的左侧。
- 必需：否
- 默认值：
null
isDismissible: boolean
如果将此属性设置为 false，模态框将不显示关闭图标且无法关闭。
- 必需：否
- 默认值：
true
isFullScreen: boolean
当此属性设置为 true 时，将渲染全屏模态框。
- 必需：否
- 默认值：
false
size: ‘small’ | ‘medium’ | ‘large’ | ‘fill’
如果添加了此属性，它将使模态框以预设宽度渲染，或扩展以填充屏幕。如果 isFullScreen 设置为 true，则此 prop 将被忽略。
- 必填：否
注意：Modal 的宽度也可以通过 CSS 调整模态内容的宽度来控制。
onRequestClose: “
调用此函数以指示应关闭模态框。
- 必填：是
overlayClassName: string
如果添加了此属性，它将为模态覆盖层 div 添加一个额外的类名。
- 必填：否
role: AriaRole
如果添加了此属性，它将覆盖模态框的默认角色。
- 必填：否
- 默认值：
dialog
shouldCloseOnClickOutside: boolean
如果添加了此属性，它将确定是否在模态内容外部发生鼠标点击时请求关闭模态框。
- 必填：否
- 默认值：
true
shouldCloseOnEsc: boolean
如果添加了此属性，它将确定是否在按下 Escape 键时请求关闭模态框。
- 必填：否
- 默认值：
true
style: CSSProperties
如果添加了此属性，它将被添加到模态框架 div 中。
- 必填：否
title: string
此属性用作模态标题的标题。
出于无障碍原因，标题是必需的，有关提供标题的其他方法，请参阅 aria.labelledby 和 contentLabel。
- 必填：否
__experimentalHideHeader: boolean
当设置为 true 时，将不渲染 Modal 的标题（包括图标、标题和关闭按钮）。
警告：此属性仍处于实验阶段。“Experimental”意味着这是早期实现，可能会发生剧烈且破坏性的更改。
- 必填：否
- 默认值：
false
相关组件
- 要以中等重要性的消息通知用户，请使用
Notice。