HTML
动态标准 - 最后更新于 2024 年 9 月 12 日
动态标准 - 最后更新于 2024 年 9 月 12 日
details 元素所有当前引擎都支持。
所有当前引擎都支持。
summary 元素，后跟 流内容。name — 互斥的 details 元素组的名称open — 详细信息是否可见[Exposed =Window ]
interface HTMLDetailsElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString name ;
[CEReactions ] attribute boolean open ;
};details
与所有 HTML 元素一样，在尝试表示其他类型的控件时，使用 detailsdetails
details
该元素的第一个 summarysummary
元素的其余内容 表示 附加信息或控件。
name 内容属性给出元素所属的相关 details
在使用此功能之前，作者应该考虑将相关的 details
一个文档中不能包含多个 detailsopenopendetailsdetails
由一个共同的 namedetailsopen
一个文档中不能包含一个 detailsdetails
使用 namedetailssectionarticle
从视觉和程序上将相关的元素分组在一起对于可访问的用户体验非常重要。这可以帮助用户了解这些元素之间的关系。当相关的元素位于网页的不同部分而不是分组在一起时，这些元素彼此之间的关系可能不太容易发现或理解。
open 内容属性是一个 布尔属性。如果存在，则表示摘要和附加信息都应该显示给用户。如果该属性不存在，则只应该显示摘要。
当创建元素时，如果该属性不存在，则应隐藏附加信息；如果存在，则应显示该信息。随后，如果删除了该属性，则应隐藏信息；如果添加了该属性，则应显示信息。
用户代理应该允许用户请求显示或隐藏附加信息。为了响应显示详细信息的请求，用户代理必须 设置 元素的 openopen
这种请求显示或隐藏附加信息的能力可能仅仅是适当的 summary
包含 detailsdetails
每个 details
以下 属性更改步骤（给定 element、localName、oldValue、value 和 namespace）用于所有 details
如果 namespace 不为 null，则返回。
如果 localName 为 name
如果 localName 为 open
如果 oldValue 或 value 中的一个为 null，而另一个不为 null，则对该 details
当 open
如果 oldValue 为 null，则 排队一个 details 切换事件任务，给定 detailsclosed”和“open”。
否则，排队一个 details 切换事件任务，给定 details 元素、"open" 和 "closed"。
如果 oldValue 为 null 且 value 不为 null，则确保 details 独占性，如果需要，关闭其他元素，给定 element。
给定 insertedNode，details 的HTML 元素插入步骤 为
确保 details 独占性，如果需要，关闭给定的元素，给定 insertedNode。
明确地说，当通过解析器插入属性或元素时，这些属性更改和插入步骤也会运行。
给定一个 details 元素 element、一个字符串 oldState 和一个字符串 newState，要 排队一个 details 切换事件任务
如果 element 的 details 切换任务跟踪器 不为 null，则
将 oldState 设置为 element 的 details 切换任务跟踪器 的 旧状态。
从 element 的 details 切换任务跟踪器 的 任务 中将其从 任务队列 中删除。
将 element 的 details 切换任务跟踪器 设置为 null。
排队一个元素任务，给定 DOM 操作任务源 和 element，以运行以下步骤
触发 在 element 上名为 toggle 的事件，使用 ToggleEvent，其中 oldState 属性初始化为 oldState，newState 属性初始化为 newState。
将 element 的 details 切换任务跟踪器 设置为 null。
将 element 的 details 切换任务跟踪器 设置为一个结构体，其 任务 设置为刚刚排队的 任务，旧状态 设置为 oldState。
给定一个 details 元素 element，要 确保 details 独占性，如果需要，关闭其他元素
令 groupMembers 为一个元素列表，包含 element 的 details 名称组 中除 element 之外的所有元素，以 树序 组织。
对于 groupMembers 中的每个元素 otherElement
给定一个 details 元素 element，要 确保 details 独占性，如果需要，关闭给定的元素
如果 element 没有 open 属性，则返回。
令 groupMembers 为一个元素列表，包含 element 的 details 名称组 中除 element 之外的所有元素，以 树序 组织。
对于 groupMembers 中的每个元素 otherElement
所有当前引擎都支持。
name 和 open IDL 属性必须反映相同名称的相应内容属性。
对 currentNode 运行以下步骤以执行 祖先 details 显示算法
当 currentNode 在 扁平树 中具有父节点时
以下示例显示了在进度报告中使用 details 元素隐藏技术细节。
< section class = "progress window" >
< h1 > Copying "Really Achieving Your Childhood Dreams"</ h1 >
< details >
< summary > Copying... < progress max = "375505392" value = "97543282" ></ progress > 25%</ summary >
< dl >
< dt > Transfer rate:</ dt > < dd > 452KB/s</ dd >
< dt > Local filename:</ dt > < dd > /home/rpausch/raycd.m4v</ dd >
< dt > Remote filename:</ dt > < dd > /var/www/lectures/raycd.m4v</ dd >
< dt > Duration:</ dt > < dd > 01:16:27</ dd >
< dt > Color profile:</ dt > < dd > SD (6-1-6)</ dd >
< dt > Dimensions:</ dt > < dd > 320×240</ dd >
</ dl >
</ details >
</ section > 以下显示了如何使用 details 元素默认隐藏一些控件
< details >
< summary >< label for = fn > Name & Extension:</ label ></ summary >
< p >< input type = text id = fn name = fn value = "Pillar Magazine.pdf" >
< p >< label >< input type = checkbox name = ext checked > Hide extension</ label >
</ details > 可以将它与列表中的其他 details 元素结合使用，允许用户将一组字段折叠成一小部分标题，并能够打开每个标题。
在这些示例中，摘要实际上只总结了控件可以更改的内容，而不是实际的值，这不太理想。
以下示例显示了使用 details 元素的 name 属性创建排他性手风琴，一组 details 元素，其中用户打开一个 details 元素的操作会导致任何打开的 details 元素关闭。
< section class = "characteristics" >
< details name = "frame-characteristics" >
< summary > Material</ summary >
The picture frame is made of solid oak wood.
</ details >
< details name = "frame-characteristics" >
< summary > Size</ summary >
The picture frame fits a photo 40cm tall and 30cm wide.
The frame is 45cm tall, 35cm wide, and 2cm thick.
</ details >
< details name = "frame-characteristics" >
< summary > Color</ summary >
The picture frame is available in its natural wood
color, or with black stain.
</ details >
</ section > 以下示例显示了当在 details 元素上设置 open 属性时会发生什么，该元素属于一组使用 name 属性创建排他性手风琴的元素。
给定初始标记
< section class = "characteristics" >
< details name = "frame-characteristics" id = "d1" open > ...</ details >
< details name = "frame-characteristics" id = "d2" > ...</ details >
< details name = "frame-characteristics" id = "d3" > ...</ details >
</ section > 以及脚本
document. getElementById( "d2" ). setAttribute( "open" , "" ); 则脚本执行后生成的树将等效于标记
< section class = "characteristics" >
< details name = "frame-characteristics" id = "d1" > ...</ details >
< details name = "frame-characteristics" id = "d2" open > ...</ details >
< details name = "frame-characteristics" id = "d3" > ...</ details >
</ section > 因为在 d2 上设置 open 属性会将其从 d1 中移除。
当用户激活 d2 内部的 summary 元素时也会发生同样情况。
由于 open 属性在用户与控件交互时会自动添加和删除，因此可以在 CSS 中使用它根据元素的状态对元素进行不同的样式化。这里，样式表用于在元素打开或关闭时为摘要动画显示颜色
< style >
details > summary { transition : color 1 s ; color : black ; }
details [ open ] > summary { color : red ; }
</ style >
< details >
< summary > Automated Status: Operational</ summary >
< p > Velocity: 12m/s</ p >
< p > Direction: North</ p >
</ details > summary 元素所有当前引擎都支持。
details 元素的 第一个子节点。HTMLElement。summary 元素表示 summary 元素的父 details 元素（如果有）其余内容的摘要、标题或图例。
如果以下算法返回 true，则 summary 元素是 其父 details 元素的摘要
如果此 summary 元素不是其父级 details 的摘要，则返回。
让 parent 为此 summary 元素的父级。
如果 open 属性在 parent 上存在，则删除 它。否则，设置 parent 的 open 属性为空字符串。
然后将执行details 通知任务步骤。
一个 命令 是菜单项、按钮和链接背后的抽象。定义命令后，界面中的其他部分可以引用相同的命令，允许多个访问点共享同一功能的方面，例如禁用状态。
命令被定义为具有以下 方面
用户代理可以公开与以下条件匹配的 命令
用户代理鼓励这样做，尤其是对于具有 访问键 的命令，作为向用户宣传这些键的方法。
例如，这些命令可以在用户代理的菜单栏中列出。
a 元素定义命令命令的 如果元素具有 属性则为真（隐藏），否则为假。
命令的禁用状态 方面如果元素或其任何祖先 处于非活动状态，则为真，否则为假。
命令的操作 是在元素上触发 click 事件。
button 元素定义命令命令的标签、访问键、 和 操作 方面与 a 元素相同（参见上一节）。
命令的 禁用状态 如果元素或其任何祖先 处于非活动状态，或者元素的 禁用 状态被设置，则为真，否则为假。
input 元素定义命令一个 input 元素，其 type 属性处于 提交按钮、重置按钮、图像按钮、按钮、单选按钮 或 复选框 状态之一，则 定义一个命令。
命令的标签 确定如下
如果 type 属性处于 提交按钮、重置按钮、图像按钮 或 按钮 状态之一，则标签 是由 value 属性给出的字符串（如果有），如果属性不存在，则为用户代理使用的依赖于用户代理和语言环境的用于标记按钮本身的值。
否则，如果元素是 标记的控件，则 标签 是 后代文本内容 在 树状顺序 中的第一个 label 元素，其 标记的控件 是所讨论的元素。（用 JavaScript 术语来说，这是由 element.labels[0].textContent 给出的。）
否则，标签 为空字符串。
命令的 如果元素具有 属性则为真（隐藏），否则为假。
命令的 禁用状态 如果元素或其任何祖先 处于非活动状态，或者元素的 禁用 状态被设置，则为真，否则为假。
命令的操作 是在元素上触发 click 事件。
option 元素定义命令具有祖先 select 元素且没有 value 属性或 value 属性不是空字符串的 option 元素 定义一个命令。
命令的 标签 是 option 元素的 label 属性的值，如果存在，否则是 option 元素的 后代文本内容，并 剥离和折叠 ASCII 空白。
命令的 为真（隐藏），如果元素具有 属性，否则为假。
命令的 禁用状态 为真，如果元素 被禁用，或者其最近的祖先 select 元素 被禁用，或者它或其祖先之一 不活动，否则为假。
如果 option 的最近的祖先 select 元素具有 multiple 属性，则命令的 动作 是 切换 option 元素。否则，动作 是 选中 option 元素。
legend 元素的 accesskey 属性定义命令它具有 分配的访问键。
它是 fieldset 元素的子元素。
它的父元素有一个后代 定义命令，它既不是 label 元素也不是 legend 元素。如果存在，此元素为 legend 元素的 accesskey 代理。
命令的 、禁用状态 和 动作 面，与 legend 元素的 accesskey 代理 的相应面相同。
在此示例中，legend 元素指定一个 accesskey，当激活时，将委托给 input 元素，位于 legend 元素内部。
< fieldset >
< legend accesskey = p >
< label > I want < input name = pizza type = number step = 1 value = 1 min = 0 >
pizza(s) with these toppings</ label >
</ legend >
< label >< input name = pizza-cheese type = checkbox checked > Cheese</ label >
< label >< input name = pizza-ham type = checkbox checked > Ham</ label >
< label >< input name = pizza-pineapple type = checkbox > Pineapple</ label >
</ fieldset > accesskey 属性在其他元素上定义命令如果之前定义 定义命令 的元素的部分定义了此元素 定义命令，则该部分适用于此元素，本部分不适用。否则，本部分适用于该元素。
命令的 标签 取决于元素。如果元素是 标记控件，则 后代文本内容，位于第一个 label 元素，其 标记控件 是所讨论的元素，它是 标签（在 JavaScript 术语中，这由 element.labels[0].textContent 给出）。否则，标签 是元素的 后代文本内容。
命令的 为真（隐藏），如果元素具有 属性，否则为假。
命令的 禁用状态 为真，如果元素或其祖先之一 不活动，否则为假。
命令的 动作 是运行以下步骤
click 事件。dialog 元素所有当前引擎都支持。
所有当前引擎都支持。
open — 对话框是否正在显示[Exposed =Window ]
interface HTMLDialogElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute boolean open ;
attribute DOMString returnValue ;
[CEReactions ] undefined show ();
[CEReactions ] undefined showModal ();
[CEReactions ] undefined close (optional DOMString returnValue );
};dialog 元素表示应用程序的瞬态部分，采用小型窗口（“对话框”）的形式，用户与之交互以执行任务或收集信息。用户完成后，对话框可以由应用程序自动关闭，也可以由用户手动关闭。
特别是对于模式对话框，它们是在所有类型的应用程序中普遍存在的模式，作者应该努力确保其 Web 应用程序中的对话框以用户熟悉的方式运行，类似于非 Web 应用程序。
与所有 HTML 元素一样，在尝试表示另一种类型的控件时使用 dialog 元素不符合标准。例如，上下文菜单、工具提示和弹出列表框不是对话框，因此滥用 dialog 元素来实现这些模式是不正确的。
用户界面对话框行为的一个重要部分是初始焦点的放置。 对话框聚焦步骤 尝试为显示对话框时选择一个合适的初始焦点候选，但这可能不是作者仔细考虑正确选择的替代方案，以匹配用户对特定对话框的期望。因此，作者应该在对话框的后代元素上使用 autofocus 属性，用户预期在对话框打开后立即与之交互。如果没有这样的元素，则作者应该在 dialog 元素本身使用 autofocus 属性。
在下面的示例中，对话框用于编辑库存管理 Web 应用程序中产品的详细信息。
< dialog >
< label > Product Number < input type = "text" readonly ></ label >
< label > Product Name < input type = "text" autofocus ></ label >
</ dialog > 如果不存在 autofocus 属性，则产品编号字段将由对话框聚焦步骤聚焦。虽然这是合理的行为，但作者确定更相关的聚焦字段是产品名称字段，因为产品编号字段是只读的，并且不需要用户输入。因此，作者使用 autofocus 来覆盖默认设置。
即使作者希望默认情况下聚焦产品编号字段，他们最好还是通过在该 input 元素上使用 autofocus 来明确指定这一点。这使得代码的未来读者能够清楚地了解意图，并确保代码在面对未来的更新时保持健壮。（例如，如果另一个开发人员添加了一个关闭按钮，并将其放在产品编号字段之前的节点树中）。
用户行为的另一个重要方面是对话框是否可滚动。在某些情况下，无法避免溢出（以及可滚动性），例如，当用户的高文本缩放设置导致溢出时。但总的来说，用户并不期望可滚动的对话框。将大型文本节点直接添加到对话框元素特别糟糕，因为这可能会导致对话框元素本身溢出。作者最好避免它们。
以下服务条款对话框遵循上述建议。
< dialog style = "height: 80vh;" >
< div style = "overflow: auto; height: 60vh;" autofocus >
< p > By placing an order via this Web site on the first day of the fourth month of the year
2010 Anno Domini, you agree to grant Us a non-transferable option to claim, for now and for
ever more, your immortal soul.</ p >
< p > Should We wish to exercise this option, you agree to surrender your immortal soul,
and any claim you may have on it, within 5 (five) working days of receiving written
notification from this site or one of its duly authorized minions.</ p >
<!-- ... etc., with many more <p> elements ... -->
</ div >
< form method = "dialog" >
< button type = "submit" value = "agree" > Agree</ button >
< button type = "submit" value = "disagree" > Disagree</ button >
</ form >
</ dialog > 注意，对话框聚焦步骤 默认情况下会选择可滚动的 div 元素，但与之前的示例类似，我们在 div 上放置了 autofocus，以更加明确和健壮地应对未来的变化。
相反，如果表达服务条款的 p 元素没有这样的包装 div 元素，那么 dialog 本身将变得可滚动，违反了上述建议。此外，在没有 autofocus 属性的情况下，这种标记模式会违反上述建议，并使 对话框聚焦步骤 的默认行为失效，导致焦点跳转到“同意” button，这是不好的用户体验。
open 属性是一个 布尔属性。当指定时，它表示 dialog 元素处于活动状态，用户可以与之交互。
没有指定 open 属性的 dialog 元素不应显示给用户。此要求可以通过样式层间接实现。例如，支持 建议的默认渲染 的用户代理使用 渲染部分 中描述的 CSS 规则来实现此要求。
删除 open 属性通常会隐藏对话框。但是，这样做会带来一些奇怪的额外后果。
dialog.show()所有当前引擎都支持。
显示 dialog 元素。
dialog.showModal()所有当前引擎都支持。
显示 dialog 元素并将其设为最顶层的模态对话框。
此方法遵循 autofocus 属性。
dialog.close([ result ])所有当前引擎都支持。
关闭 dialog 元素。
如果提供了参数，则提供返回值。
dialog.returnValue [ = result ]所有当前引擎都支持。
返回 dialog 的返回值。
可以设置，以更新返回值。
show() 方法的步骤如下
如果 this 有 open 属性，则抛出 "InvalidStateError" DOMException。
运行给定 hideUntil、false 和 true 的 隐藏所有弹出窗口直到。
showModal() 方法的步骤如下
如果 this 有 open 属性，则抛出 "InvalidStateError" DOMException。
如果 this 没有 连接，则抛出 "InvalidStateError" DOMException。
如果 this 处于 弹出窗口显示状态，则抛出 "InvalidStateError" DOMException。
令 this 的 节点文档 被 模态对话框 this 阻塞。
这会导致 文档的聚焦区域 变得 不活动（除非当前聚焦区域是 subject 的 影子包含后代）。在这种情况下，文档的聚焦区域 将很快被 重置 为 视窗。在接下来的几步中，我们将尝试找到一个更好的焦点候选者。
将 this 的 关闭观察器 设置为 建立关闭观察器 给定 this 的 相关全局对象 的结果，其中
cancelAction 给定 canPreventClose 为返回 触发事件 的结果，该事件名为 cancel，在 this 上触发，cancelable 属性初始化为 canPreventClose。
closeAction 为 关闭对话框 给定 this 和 null。
运行 隐藏所有弹出框直到 给定的 hideUntil、false 和 true。
给定 对话框 元素 subject 的 对话框聚焦步骤 如下：
令 control 为 null。
如果 subject 具有 autofocus 属性，则将 control 设置为 subject。
如果 control 为 null，则将 control 设置为 subject 的 焦点代理。
如果 control 为 null，则将 control 设置为 subject。
运行 control 的 聚焦步骤。
如果 control 不是 可聚焦的，这将不执行任何操作。这只会发生在 subject 没有焦点代理，并且用户代理决定 对话框 元素通常不可聚焦的情况下。在这种情况下，对 文档的聚焦区域 的任何 先前修改 都将生效。
将 topDocument 的 自动聚焦处理标志 设置为 true。
给定 removedNode 和 oldParent 的 对话框 HTML 元素移除步骤 为
如果 removedNode 的 关闭观察者 不为 null，则
如果 removedNode 的 节点文档 的 顶层 包含 removedNode，则 立即从顶层移除元素，给定 removedNode。
将 removedNode 的 是否为模态 标志设置为 false。
close(returnValue) 方法的步骤如下：
当要 关闭 对话框 元素 subject 时，使用 null 或字符串 result，运行以下步骤：
如果 subject 没有 open 属性，则返回。
移除 subject 的 open 属性。
令 wasModal 为 subject 的 是否为模态 标志的值。
将 subject 的 是否为模态 标志设置为 false。
如果 result 不为 null，则将 returnValue 属性设置为 result。
如果 subject 的 先前聚焦元素 不为 null，则
在用户交互任务源上排队元素任务，给定 subject 元素，以 触发名为 close 的事件，在 subject 上。
如果 subject 的 关闭观察者 不为 null，则
returnValue IDL 属性，在获取时，必须返回上次设置的值。在设置时，必须设置为新值。当创建元素时，必须将其设置为空字符串。
我们使用 show/close 作为 对话框 元素的动词，而不是通常被认为是反义词的动词对，例如 show/hide 或 open/close，这是由于以下限制：
隐藏对话框与关闭对话框不同。关闭对话框会赋予其返回值，触发事件，为其他对话框释放页面等等。而隐藏对话框是一个纯粹的视觉属性，你可以使用 属性或移除 open 属性来实现。（另请参见关于移除 open 属性的上述说明，以及如何以这种方式隐藏对话框通常不被人所希望。）
显示对话框与打开对话框不同。打开对话框包括创建和显示该对话框（类似于 window.open() 同时创建和显示新窗口）。而显示对话框是指将 DOM 中已存在的 对话框 元素变得可交互，并使其对用户可见的过程。
如果我们即使在上面提到的情况下也要使用 dialog.open() 方法，它将与 dialog.open 属性冲突。
此外，对许多与 对话框 元素的原始设计同时代的 UI 框架的 调查 表明 show/close 动词对是相当常见的。
总之，事实证明，某些动词的含义及其在技术环境中的使用方式意味着，诸如显示和关闭对话框之类的成对动作并不总是可以表示为反义词。
每个 对话框 元素都具有一个 关闭观察者，它是一个 关闭观察者 或 null，最初为 null。
每个 对话框 元素都具有一个 是否为模态 标志。当创建 对话框 元素时，此标志必须设置为 false。
每个 HTML 元素 都有一个 先前聚焦元素，它可以是 null 或元素，最初为 null。当调用 showModal() 和 show() 时，在运行 对话框聚焦步骤 之前，此元素将设置为当前 聚焦 的元素。具有设置为 popover 属性的元素，在 显示弹出框算法 期间，会将此元素设置为当前 聚焦 的元素。
所有当前引擎都支持。
此对话框有一些细则。使用 strong 元素来吸引用户注意更重要的部分。
< dialog >
< h1 > Add to Wallet</ h1 >
< p >< strong >< label for = amt > How many gold coins do you want to add to your wallet?</ label ></ strong ></ p >
< p >< input id = amt name = amt type = number min = 0 step = 0.01 value = 100 ></ p >
< p >< small > You add coins at your own risk.</ small ></ p >
< p >< label >< input name = round type = checkbox > Only add perfectly round coins</ label ></ p >
< p >< input type = button onclick = "submit()" value = "Add Coins" ></ p >
</ dialog >