<dialog>: The Dialog element
Baseline 2022
Newly available
Since March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.
<dialog>
HTML 元素表示模式或非模式对话框或其他交互式组件,例如可忽略的警报、检查器或子窗口。
¥The <dialog>
HTML element represents a modal or non-modal dialog box or other interactive component, such as a dismissible alert, inspector, or subwindow.
HTML <dialog>
元素用于创建模式和非模式对话框。模式对话框会中断与页面其余部分的交互,而非模式对话框则允许与页面其余部分的交互。
¥The HTML <dialog>
element is used to create both modal and non-modal dialog boxes. Modal dialog boxes interrupt interaction with the rest of the page being inert, while non-modal dialog boxes allow interaction with the rest of the page.
应使用 JavaScript 来显示 <dialog>
元素。使用 .showModal()
方法显示模式对话框,使用 .show()
方法显示非模式对话框。当提交嵌套在 <dialog>
元素中的 <form>
时,可以使用 .close()
方法或使用 dialog
方法关闭对话框。也可以通过按 Esc 键关闭模态对话框。
¥JavaScript should be used to display the <dialog>
element. Use the .showModal()
method to display a modal dialog and the .show()
method to display a non-modal dialog. The dialog box can be closed using the .close()
method or using the dialog
method when submitting a <form>
that is nested within the <dialog>
element. Modal dialogs can also be closed by pressing the Esc key.
属性
¥Attributes
该元素包括 全局属性。
¥This element includes the global attributes.
警告:
tabindex
属性不得用于<dialog>
元素。参见 使用说明。¥Warning: The
tabindex
attribute must not be used on the<dialog>
element. See usage notes.
open
-
指示对话框处于活动状态并且可以进行交互。如果未设置
open
属性,则用户将看不到该对话框。建议使用.show()
或.showModal()
方法来渲染对话框,而不是使用open
属性。如果使用open
属性打开<dialog>
,则它是非模态的。注意:虽然你可以通过切换
open
属性的存在来切换非模式对话框的打开和关闭状态,但不建议使用此方法。¥Note: While you can toggle between the open and closed states of non-modal dialog boxes by toggling the presence of the
open
attribute, this approach is not recommended.
使用说明
¥Usage notes
- 如果 HTML
<form>
元素具有method="dialog"
属性或用于提交表单的按钮设置了formmethod="dialog"
,则可使用 HTML<form>
元素关闭对话框。当通过dialog
方法提交<dialog>
中的<form>
时,对话框将关闭,表单控件的状态将被保存但不会提交,并且returnValue
属性将设置为已激活按钮的值。 - CSS
::backdrop
伪元素可用于设置模式对话框的背景样式,当使用HTMLDialogElement.showModal()
方法显示对话框时,该背景显示在<dialog>
元素后面。例如,此伪元素可用于模糊、变暗或以其他方式混淆模式对话框后面的惰性内容。 - 应将
autofocus
属性添加到用户希望在打开模式对话框后立即与之交互的元素。如果没有其他元素涉及更直接的交互,建议将autofocus
添加到对话框内的关闭按钮,或者如果用户希望用户单击/激活它来关闭对话框本身。 - 不要将
tabindex
属性添加到<dialog>
元素,因为它不具有交互性并且不接收焦点。对话框的内容(包括对话框中包含的关闭按钮)可以接收焦点并进行交互。
无障碍
¥Accessibility
实现对话框时,重要的是要考虑设置用户焦点的最合适位置。当使用 HTMLDialogElement.showModal()
打开 <dialog>
时,焦点设置在第一个嵌套可聚焦元素上。使用 autofocus
属性显式指示初始焦点放置将有助于确保将初始焦点设置在被视为任何特定对话框的最佳初始焦点放置的元素上。当有疑问时,由于可能并不总是知道可以在对话框中的何处设置初始焦点,特别是对于在调用时动态呈现对话框内容的情况,<dialog>
元素本身可以提供最佳的初始焦点放置。
¥When implementing a dialog, it is important to consider the most appropriate place to set user focus. When using HTMLDialogElement.showModal()
to open a <dialog>
, focus is set on the first nested focusable element. Explicitly indicating the initial focus placement by using the autofocus
attribute will help ensure initial focus is set on the element deemed the best initial focus placement for any particular dialog. When in doubt, as it may not always be known where initial focus could be set within a dialog, particularly for instances where a dialog's content is dynamically rendered when invoked, the <dialog>
element itself may provide the best initial focus placement.
确保提供一种机制来允许用户关闭对话框。确保所有用户都可以关闭对话框的最可靠方法是包含一个明确的按钮来执行此操作,例如确认、取消或关闭按钮。
¥Ensure a mechanism is provided to allow users to close the dialog. The most robust way to ensure that all users can close the dialog is to include an explicit button to do so, such as a confirmation, cancellation, or close button.
默认情况下,可以通过按 Esc 键来关闭由 showModal()
方法调用的对话框。默认情况下,非模式对话框不会通过 Esc 键关闭,并且根据非模式对话框所代表的内容,可能不需要这种行为。键盘用户期望 Esc 键关闭模式对话框;确保这种行为得到实现和维持。如果打开了多个模式对话框,则按 Esc 键应仅关闭最后显示的对话框。使用 <dialog>
时,此行为由浏览器提供。
¥By default, a dialog invoked by the showModal()
method can be dismissed by pressing the Esc key. A non-modal dialog does not dismiss via the Esc key by default, and depending on what the non-modal dialog represents, it may not be desired for this behavior. Keyboard users expect the Esc key to close modal dialogs; ensure that this behavior is implemented and maintained. If multiple modal dialogs are open, pressing the Esc key should close only the last shown dialog. When using <dialog>
, this behavior is provided by the browser.
虽然可以使用其他元素创建对话框,但原生 <dialog>
元素提供了可用性和可访问性功能,如果你将其他元素用于类似目的,则必须复制这些功能。如果你要创建自定义对话框实现,请确保支持所有预期的默认行为并遵循正确的标签建议。
¥While dialogs can be created using other elements, the native <dialog>
element provides usability and accessibility features that must be replicated if you use other elements for a similar purpose. If you're creating a custom dialog implementation, ensure that all expected default behaviors are supported and proper labeling recommendations are followed.
浏览器以类似于使用 ARIA 角色="dialog" 属性的自定义对话框的方式公开 <dialog>
元素。showModal()
方法调用的 <dialog>
元素隐式具有 咏叹调模态="true",而 show()
方法调用的 <dialog>
元素或使用 open
属性显示或通过更改 <dialog>
的默认 display
公开为 [aria-modal="false"]
。实现模式对话框时,除 <dialog>
及其内容之外的所有内容都应使用 inert
属性呈现为惰性。当将 <dialog>
与 HTMLDialogElement.showModal()
方法一起使用时,此行为由浏览器提供。
¥The <dialog>
element is exposed by browsers in a manner similar to custom dialogs that use the ARIA role="dialog" attribute. <dialog>
elements invoked by the showModal()
method implicitly have aria-modal="true", whereas <dialog>
elements invoked by the show()
method or displayed using the open
attribute or by changing the default display
of a <dialog>
are exposed as [aria-modal="false"]
. When implementing modal dialogs, everything other than the <dialog>
and its contents should be rendered inert using the inert
attribute. When using <dialog>
along with the HTMLDialogElement.showModal()
method, this behavior is provided by the browser.
示例
纯 HTML 对话框
¥HTML-only dialog
此示例演示如何仅使用 HTML 创建非模式对话框。由于 <dialog>
元素中的布尔值 open
属性,该对话框在页面加载时显示为打开状态。单击 "OK" 按钮可以关闭该对话框,因为 <form>
元素中的 method
属性设置为 "dialog"
。在这种情况下,不需要 JavaScript 来关闭表单。
¥This example demonstrates the create a non-modal dialog by using only HTML. Because of the boolean open
attribute in the <dialog>
element, the dialog appears open when the page loads. The dialog can be closed by clicking the "OK" button because the method
attribute in the <form>
element is set to "dialog"
. In this case, no JavaScript is needed to close the form.
<dialog open>
<p>Greetings, one and all!</p>
<form method="dialog">
<button>OK</button>
</form>
</dialog>
结果
¥Result
注意:重新加载页面以重置输出。
¥Note: Reload the page to reset the output.
由于存在 open
属性,该对话框最初打开。使用 open
属性显示的对话框是非模式的。单击 "OK" 后,对话框将关闭,结果框架为空。当对话框关闭时,没有提供重新打开它的方法。因此,显示非模式对话框的首选方法是使用 HTMLDialogElement.show()
方法。可以通过添加或删除布尔值 open
属性来切换对话框的显示,但这不是推荐的做法。
¥This dialog is initially open because of the presence of the open
attribute. Dialogs that are displayed using the open
attribute are non-modal. After clicking "OK", the dialog gets dismissed, leaving the Result frame empty. When the dialog is dismissed, there is no method provided to reopen it. For this reason, the preferred method to display non-modal dialogs is by using the HTMLDialogElement.show()
method. It is possible to toggle the display of the dialog by adding or removing the boolean open
attribute, but it is not the recommended practice.
创建模式对话框
¥Creating a modal dialog
此示例演示了具有 gradient 背景的模式对话框。当激活 "显示对话框" 按钮时,.showModal()
方法打开模式对话框。可以通过按 Esc 键或激活对话框中的 "关闭" 按钮时通过 close()
方法关闭该对话框。
¥This example demonstrates a modal dialog with a gradient backdrop. The .showModal()
method opens the modal dialog when the "Show the dialog" button is activated. The dialog can be closed by pressing the Esc key or via the close()
method when the "Close" button within the dialog is activated.
当对话框打开时,浏览器默认将焦点授予对话框中可以聚焦的第一个元素。在此示例中,autofocus
属性应用于 "关闭" 按钮,在对话框打开时为其提供焦点,因为这是我们期望用户在对话框打开后立即与之交互的元素。
¥When a dialog opens, the browser, by default, gives focus to the first element that can be focused within the dialog. In this example, the autofocus
attribute is applied to the "Close" button, giving it focus when the dialog opens, as this is the element we expect the user will interact with immediately after the dialog opens.
HTML
<dialog>
<button autofocus>Close</button>
<p>This modal dialog has a groovy backdrop!</p>
</dialog>
<button>Show the dialog</button>
CSS
我们可以使用 ::backdrop
伪元素来设置对话框背景的样式。
¥We can style the backdrop of the dialog by using the ::backdrop
pseudo-element.
::backdrop {
background-image: linear-gradient(
45deg,
magenta,
rebeccapurple,
dodgerblue,
green
);
opacity: 0.75;
}
JavaScript
该对话框使用 .showModal()
方法以模态方式打开,并使用 .close()
方法以模态方式关闭。
¥The dialog is opened modally using the .showModal()
method and closed using the .close()
method.
const dialog = document.querySelector("dialog");
const showButton = document.querySelector("dialog + button");
const closeButton = document.querySelector("dialog button");
// "Show the dialog" button opens the dialog modally
showButton.addEventListener("click", () => {
dialog.showModal();
});
// "Close" button closes the dialog
closeButton.addEventListener("click", () => {
dialog.close();
});
结果
¥Result
当显示模式对话框时,它出现在可能存在的任何其他对话框之上。模式对话框之外的所有内容都是惰性的,对话框之外的交互都会被阻止。请注意,当对话框打开时,除了对话框本身之外,无法与文档进行交互;"显示对话框" 按钮大部分被几乎不透明的对话框背景所混淆,并且是惰性的。
¥When the modal dialog is displayed, it appears above any other dialogs that might be present. Everything outside the modal dialog is inert and interactions outside the dialog are blocked. Notice that when the dialog is open, with the exception of the dialog itself, interaction with the document is not possible; the "Show the dialog" button is mostly obfuscated by the almost opaque backdrop of the dialog and is inert.
处理对话框的返回值
¥Handling the return value from the dialog
此示例演示了 <dialog>
元素的 returnValue
以及如何使用表单关闭模式对话框。默认情况下,returnValue
是空字符串,或者是 <dialog>
元素内提交表单的按钮的值(如果有)。
¥This example demonstrates the returnValue
of the <dialog>
element and how to close a modal dialog by using a form. By default, the returnValue
is the empty string or the value of the button that submits the form within the <dialog>
element, if there is one.
此示例在激活 "显示对话框" 按钮时打开模式对话框。该对话框包含一个带有 <select>
和两个 <button>
元素的表单,默认为 type="submit"
。当选择选项更改时,事件监听器会更新 "确认" 按钮的值。如果激活 "确认" 按钮来关闭对话框,则该按钮的当前值就是返回值。如果通过按 "取消" 按钮关闭对话框,则 returnValue
为 cancel
。
¥This example opens a modal dialog when the "Show the dialog" button is activated. The dialog contains a form with a <select>
and two <button>
elements, which default to type="submit"
. An event listener updates the value of the "Confirm" button when the select option changes. If the "Confirm" button is activated to close the dialog, the current value of the button is the return value. If the dialog is closed by pressing the "Cancel" button, the returnValue
is cancel
.
当对话框关闭时,返回值显示在 "显示对话框" 按钮下。如果通过按 Esc 键关闭对话框,则 returnValue
不会更新,并且 close
事件也不会发生,因此 <output>
中的文本不会更新。
¥When the dialog is closed, the return value is displayed under the "Show the dialog" button. If the dialog is closed by pressing the Esc key, the returnValue
is not updated, and the close
event doesn't occur, so the text in the <output>
is not updated.
HTML
<!-- A modal dialog containing a form -->
<dialog id="favDialog">
<form>
<p>
<label>
Favorite animal:
<select>
<option value="default">Choose…</option>
<option>Brine shrimp</option>
<option>Red panda</option>
<option>Spider monkey</option>
</select>
</label>
</p>
<div>
<button value="cancel" formmethod="dialog">Cancel</button>
<button id="confirmBtn" value="default">Confirm</button>
</div>
</form>
</dialog>
<p>
<button id="showDialog">Show the dialog</button>
</p>
<output></output>
JavaScript
const showButton = document.getElementById("showDialog");
const favDialog = document.getElementById("favDialog");
const outputBox = document.querySelector("output");
const selectEl = favDialog.querySelector("select");
const confirmBtn = favDialog.querySelector("#confirmBtn");
// "Show the dialog" button opens the <dialog> modally
showButton.addEventListener("click", () => {
favDialog.showModal();
});
// "Cancel" button closes the dialog without submitting because of [formmethod="dialog"], triggering a close event.
favDialog.addEventListener("close", (e) => {
outputBox.value =
favDialog.returnValue === "default"
? "No return value."
: `ReturnValue: ${favDialog.returnValue}.`; // Have to check for "default" rather than empty string
});
// Prevent the "confirm" button from the default behavior of submitting the form, and close the dialog with the `close()` method, which triggers the "close" event.
confirmBtn.addEventListener("click", (event) => {
event.preventDefault(); // We don't want to submit this fake form
favDialog.close(selectEl.value); // Have to send the select box value here.
});
结果
¥Result
上面的例子演示了以下三种关闭模式对话框的方法:
¥The above examples demonstrate the following three methods of closing modal dialogs:
- 通过使用
dialog
方法在对话框表单内提交表单(如 仅 HTML 示例 中所示)。 - 按 Esc 键。
- 通过调用
HTMLDialogElement.close()
方法(如 模态例子 中所示)。在此示例中,"取消" 按钮通过dialog
表单方法关闭对话框,"确认" 按钮通过HTMLDialogElement.close()
方法关闭对话框。
"取消" 按钮包含 formmethod="dialog"
属性,该属性覆盖 <form>
的默认 GET
方法。当表单的方法为 dialog
时,表单的状态被保存但不提交,并且对话框被关闭。
¥The "Cancel" button includes the formmethod="dialog"
attribute, which overrides the <form>
's default GET
method. When a form's method is dialog
, the state of the form is saved but not submitted, and the dialog gets closed.
如果没有 action
,通过默认 GET
方法提交表单会导致页面重新加载。我们使用 JavaScript 分别使用 event.preventDefault()
和 HTMLDialogElement.close()
方法来阻止提交并关闭对话框。
¥Without an action
, submitting the form via the default GET
method causes a page to reload. We use JavaScript to prevent the submission and close the dialog with the event.preventDefault()
and HTMLDialogElement.close()
methods, respectively.
在每个 dialog
元素中提供关闭机制非常重要。默认情况下,Esc 键不会关闭非模式对话框,也不能假设用户甚至可以访问物理键盘(例如,使用触摸屏设备但无法访问键盘的人)。
¥It is important to provide a closing mechanism within every dialog
element. The Esc key does not close non-modal dialogs by default, nor can one assume that a user will even have access to a physical keyboard (e.g., someone using a touch screen device without access to a keyboard).
关闭带有所需表单输入的对话框
¥Closing a dialog with a required form input
当对话框内的表单具有所需输入时,只有在为所需输入提供值后,用户代理才会允许你关闭对话框。要关闭此类对话框,请使用关闭按钮上的 formnovalidate
属性,或者在单击关闭按钮时调用对话框对象上的 close()
方法。
¥When a form inside a dialog has a required input, the user agent will only let you close the dialog once you provide a value for the required input. To close such dialog, either use the formnovalidate
attribute on the close button or call the close()
method on the dialog object when the close button is clicked.
<dialog id="dialog">
<form method="dialog">
<p>
<label>
Favorite animal:
<input type="text" required />
</label>
</p>
<div>
<input type="submit" id="normal-close" value="Normal close" />
<input
type="submit"
id="novalidate-close"
value="Novalidate close"
formnovalidate />
<input type="submit" id="js-close" value="JS close" />
</div>
</form>
</dialog>
<p>
<button id="show-dialog">Show the dialog</button>
</p>
<output></output>
[type="submit"] {
margin-right: 1rem;
}
JavaScript
const showBtn = document.getElementById("show-dialog");
const dialog = document.getElementById("dialog");
const jsCloseBtn = dialog.querySelector("#js-close");
showBtn.addEventListener("click", () => {
dialog.showModal();
});
jsCloseBtn.addEventListener("click", (e) => {
e.preventDefault();
dialog.close();
});
结果
¥Result
从输出中,我们看到不可能使用“正常关闭”按钮关闭对话框。但是,如果我们使用“取消”按钮上的 formnovalidate
属性绕过表单验证,则可以关闭该对话框。通过编程,dialog.close()
也会关闭此类对话框。
¥From the output, we see it is impossible to close the dialog using the Normal close button. But the dialog can be closed if we bypass the form validation using the formnovalidate
attribute on the Cancel button. Programmatically, dialog.close()
will also close such dialog.
动画对话框
¥Animating dialogs
<dialog>
在隐藏时设置为 display: none;
,在显示时设置为 display: block;
,以及从 top layer 和 可达性树 中删除/添加到 top layer 和 可达性树。因此,要使 <dialog>
元素具有动画效果,display
属性需要具有动画效果。支持浏览器 将 display
动画化,并在 离散动画类型 上进行了变体。具体来说,浏览器将在 none
和另一个值 display
之间翻转,以便在整个动画持续时间内显示动画内容。
¥<dialog>
s are set to display: none;
when hidden and display: block;
when shown, as well as being removed from / added to the top layer and the accessibility tree. Therefore, for <dialog>
elements to be animated the display
property needs to be animatable. Supporting browsers animate display
with a variation on the discrete animation type. Specifically, the browser will flip between none
and another value of display
so that the animated content is shown for the entire animation duration.
例如:
¥So for example:
- 当将
display
从none
动画到block
(或另一个可见的display
值)时,该值将在动画持续时间的0%
处翻转到block
,因此它始终可见。 - 当将
display
从block
(或另一个可见的display
值)动画到none
时,该值将在动画持续时间的100%
处翻转到none
,因此它始终可见。
注意:使用 CSS 过渡 制作动画时,需要设置
transition-behavior: allow-discrete
才能启用上述行为。当使用 CSS 动画 制作动画时,此行为默认可用;不需要等效步骤。¥Note: When animating using CSS transitions,
transition-behavior: allow-discrete
needs to be set to enable the above behavior. This behavior is available by default when animating with CSS animations; an equivalent step is not required.
转换对话框元素
¥Transitioning dialog elements
使用 CSS 过渡制作 <dialog>
动画时,需要以下功能:
¥When animating <dialog>
s with CSS transitions, the following features are required:
@starting-style
规则-
为
<dialog>
上设置的属性提供一组起始值,你希望在每次打开<dialog>
时从该值进行转换。这是为了避免意外行为所必需的。默认情况下,CSS 转换仅在可见元素上的属性从一个值更改为另一个值时发生;它们不会在元素的第一次样式更新时或当display
类型从none
更改为另一种类型时触发。 display
属性-
将
display
添加到转换列表中,以便<dialog>
在转换期间保持为display: block
(或在对话框的打开状态上设置的另一个可见display
值),确保其他转换可见。 overlay
属性-
将
overlay
包含在转换列表中,以确保推迟从顶层删除<dialog>
,直到转换完成,再次确保转换可见。 transition-behavior
属性-
在
display
和overlay
过渡(或transition
简写)上设置transition-behavior: allow-discrete
,以在这两个默认情况下不可设置动画的属性上启用离散过渡。
这是一个简单的示例来展示这可能是什么样子。
¥Here is a quick example to show what this might look like.
HTML
HTML 包含一个 <dialog>
元素,以及一个用于显示对话框的按钮。此外,<dialog>
元素包含另一个用于自行关闭的按钮。
¥The HTML contains a <dialog>
element, plus a button to show the dialog. Additionally, the <dialog>
element contains another button to close itself.
<dialog id="dialog">
Content here
<button class="close">close</button>
</dialog>
<button class="show">Show Modal</button>
CSS
在 CSS 中,我们包含一个 @starting-style
块,它定义 opacity
和 transform
属性的过渡起始样式、dialog[open]
状态的过渡结束样式以及默认 dialog
状态的默认样式,以在 <dialog>
出现后过渡回该样式。请注意 <dialog>
的 transition
列表不仅包含这些属性,还包含 display
和 overlay
属性,每个属性都设置了 allow-discrete
。
¥In the CSS, we include a @starting-style
block that defines the transition starting styles for the opacity
and transform
properties, transition end styles on the dialog[open]
state, and default styles on the default dialog
state to transition back to once the <dialog>
has appeared. Note how the <dialog>
's transition
list includes not only these properties, but also the display
and overlay
properties, each with allow-discrete
set on them.
我们还为 ::backdrop
上的 background-color
属性设置了一个起始样式值,该值在打开时出现在 <dialog>
后面,以提供漂亮的变暗动画。当对话框打开时,dialog[open]::backdrop
选择器仅选择 <dialog>
元素的背景。
¥We also set a starting style value for the background-color
property on the ::backdrop
that appears behind the <dialog>
when it opens, to provide a nice darkening animation. The dialog[open]::backdrop
selector selects only the backdrops of <dialog>
elements when the dialog is open.
/* Open state of the dialog */
dialog[open] {
opacity: 1;
transform: scaleY(1);
}
/* Closed state of the dialog */
dialog {
opacity: 0;
transform: scaleY(0);
transition:
opacity 0.7s ease-out,
transform 0.7s ease-out,
overlay 0.7s ease-out allow-discrete,
display 0.7s ease-out allow-discrete;
/* Equivalent to
transition: all 0.7s allow-discrete; */
}
/* Before-open state */
/* Needs to be after the previous dialog[open] rule to take effect,
as the specificity is the same */
@starting-style {
dialog[open] {
opacity: 0;
transform: scaleY(0);
}
}
/* Transition the :backdrop when the dialog modal is promoted to the top layer */
dialog::backdrop {
background-color: rgb(0 0 0 / 0%);
transition:
display 0.7s allow-discrete,
overlay 0.7s allow-discrete,
background-color 0.7s;
/* Equivalent to
transition: all 0.7s allow-discrete; */
}
dialog[open]::backdrop {
background-color: rgb(0 0 0 / 25%);
}
/* This starting-style rule cannot be nested inside the above selector
because the nesting selector cannot represent pseudo-elements. */
@starting-style {
dialog[open]::backdrop {
background-color: rgb(0 0 0 / 0%);
}
}
JavaScript
JavaScript 将事件处理程序添加到显示和关闭按钮,使它们在单击时显示和关闭 <dialog>
:
¥The JavaScript adds event handlers to the show and close buttons causing them to show and close the <dialog>
when they are clicked:
const dialogElem = document.getElementById("dialog");
const showBtn = document.querySelector(".show");
const closeBtn = document.querySelector(".close");
showBtn.addEventListener("click", () => {
dialogElem.showModal();
});
closeBtn.addEventListener("click", () => {
dialogElem.close();
});
结果
¥Result
代码呈现如下:
¥The code renders as follows:
注意:由于
<dialog>
每次显示时都会从display: none
更改为display: block
,因此每次出现条目转换时,<dialog>
都会从@starting-style
样式转换为其dialog[open]
样式。当<dialog>
关闭时,它会从dialog[open]
状态转换到默认的dialog
状态。¥Note: Because
<dialog>
s change fromdisplay: none
todisplay: block
each time they are shown, the<dialog>
transitions from its@starting-style
styles to itsdialog[open]
styles every time the entry transition occurs. When the<dialog>
closes, it transitions from itsdialog[open]
state to the defaultdialog
state.在这种情况下,进入和退出时的样式转换可能会有所不同。请参阅我们的 演示何时使用起始样式 示例来证明这一点。
¥It is possible for the style transition on entry and exit to be different in such cases. See our Demonstration of when starting styles are used example for a proof of this.
对话框关键帧动画
¥dialog keyframe animations
当使用 CSS 关键帧动画制作 <dialog>
动画时,需要注意与过渡的一些差异:
¥When animating a <dialog>
with CSS keyframe animations, there are some differences to note from transitions:
- 你没有提供
@starting-style
。 - 你将
display
值包含在关键帧中;这将是整个动画的display
值,或者直到遇到另一个非none
显示值。 - 你不需要显式启用离散动画;关键帧内没有与
allow-discrete
等效的值。 - 你也不需要在关键帧内设置
overlay
;display
动画处理<dialog>
从显示到隐藏的动画。
让我们看一个示例,以便你了解它的样子。
¥Let's have a look at an example so you can see what this looks like.
HTML
首先,HTML 包含一个 <dialog>
元素,以及一个用于显示对话框的按钮。此外,<dialog>
元素包含另一个用于自行关闭的按钮。
¥First, the HTML contains a <dialog>
element, plus a button to show the dialog. Additionally, the <dialog>
element contains another button to close itself.
<dialog id="dialog">
Content here
<button class="close">close</button>
</dialog>
<button class="show">Show Modal</button>
CSS
CSS 定义了在 <dialog>
的关闭状态和显示状态之间进行动画处理的关键帧,以及 <dialog>
背景的淡入动画。<dialog>
动画包括动画 display
,以确保实际可见的动画效果在整个持续时间内保持可见。请注意,无法对背景淡出进行动画处理 - 当 <dialog>
关闭时,背景会立即从 DOM 中删除,因此无需进行动画处理。
¥The CSS defines keyframes to animate between the closed and shown states of the <dialog>
, plus the fade-in animation for the <dialog>
's backdrop. The <dialog>
animations include animating display
to make sure the actual visible animation effects remain visible for the whole duration. Note that it wasn't possible to animate the backdrop fade out — the backdrop is immediately removed from the DOM when the <dialog>
is closed, so there is nothing to animate.
dialog {
animation: fade-out 0.7s ease-out;
}
dialog[open] {
animation: fade-in 0.7s ease-out;
}
dialog[open]::backdrop {
animation: backdrop-fade-in 0.7s ease-out forwards;
}
/* Animation keyframes */
@keyframes fade-in {
0% {
opacity: 0;
transform: scaleY(0);
display: none;
}
100% {
opacity: 1;
transform: scaleY(1);
display: block;
}
}
@keyframes fade-out {
0% {
opacity: 1;
transform: scaleY(1);
display: block;
}
100% {
opacity: 0;
transform: scaleY(0);
display: none;
}
}
@keyframes backdrop-fade-in {
0% {
background-color: rgb(0 0 0 / 0%);
}
100% {
background-color: rgb(0 0 0 / 25%);
}
}
body,
button {
font-family: system-ui;
}
JavaScript
最后,JavaScript 将事件处理程序添加到按钮以启用显示和关闭 <dialog>
:
¥Finally, the JavaScript adds event handlers to the buttons to enable showing and closing the <dialog>
:
const dialogElem = document.getElementById("dialog");
const showBtn = document.querySelector(".show");
const closeBtn = document.querySelector(".close");
showBtn.addEventListener("click", () => {
dialogElem.showModal();
});
closeBtn.addEventListener("click", () => {
dialogElem.close();
});
结果
¥Result
代码呈现如下:
¥The code renders as follows:
技术总结
¥Technical summary
内容类别 | 流量内容, 切根 |
---|---|
允许的内容 | 流量内容 |
标签遗漏 | 无,开始和结束标记都是强制性的。 |
允许的父级 | 任何接受 流动内容 的元素 |
隐式 ARIA 角色 | dialog |
允许的 ARIA 角色 | alertdialog |
DOM 接口 | HTMLDialogElement |
规范
Specification |
---|
HTML Standard # the-dialog-element |
浏览器兼容性
BCD tables only load in the browser
也可以看看
¥See also
HTMLDialogElement
接口close
事件cancel
事件HTMLDialogElement
接口的open
属性- HTML 元素的
inert
全局属性 ::backdrop
CSS 伪元素- 学习区域中的 网页表格