HTML：活的标准
面向 Web 开发人员的版本 — 最后更新于 2024 年 9 月 12 日
面向 Web 开发人员的版本 — 最后更新于 2024 年 9 月 12 日
details 元素所有当前引擎都支持。
summary 元素，后跟 流内容。name — 互斥 details 元素组的名称open — 是否显示详细信息HTMLDetailsElement。details 元素 代表 一个信息披露小部件，用户可以从中获取更多信息或控件。
与所有 HTML 元素一样，在尝试表示其他类型的控件时，使用 details 元素是不符合规范的。例如，标签小部件和菜单小部件不是信息披露小部件，因此滥用 details 元素来实现这些模式是不正确的。
details 元素不适合脚注。有关如何标记脚注的详细信息，请参阅 脚注部分。
元素的子元素 summary（如果有）代表 详细信息的摘要或图例。
元素其余内容 代表 附加信息或控件。
name 内容属性指定元素所属的关联 details 元素组的名称。打开此组中的一个成员会导致组的其他成员关闭。如果指定了属性，则其值不能是空字符串。
在使用此功能之前，作者应考虑将关联的 details 元素分组到一个排他性手风琴中，对于用户来说是否有帮助或有害。虽然使用排他性手风琴可以减少一组内容可以占据的最大空间量，但它也可能让用户感到沮丧，他们必须打开很多项目才能找到他们想要的东西，或者用户想要同时查看多个项目的内容。
文档中不应包含多个具有 open 属性存在的 details 元素，这些元素位于同一个 details name group 中。作者不应使用脚本以会导致 details name group 具有多个具有 open 属性存在的 details 元素的方式将 details 元素添加到文档中。
由公共 name 属性创建的元素组是排他的，这意味着一次最多只有一个 details 元素可以打开。虽然这种排他性由用户代理强制执行，但由此产生的强制执行会立即更改标记中的 open 属性。对作者的这一要求禁止这种误导性标记。
文档中不应包含 details 元素，该元素是位于同一个 details name group 中的另一个 details 元素的后代。
使用 name 属性对多个相关 details 元素进行分组的文档应将这些相关元素放在一个包含元素中（例如，一个 section 元素或 article 元素）。当组应该以标题开头时，作者应将该标题放在包含元素开头的 标题 元素中。
在视觉上和编程上将相关元素分组在一起对于可访问的用户体验可能很重要。这可以帮助用户理解这些元素之间的关系。当相关元素位于网页的不同部分而不是分组在一起时，这些元素彼此之间的关系可能难以发现或理解。
open 内容属性是一个 布尔属性。如果存在，则表示要向用户显示摘要和附加信息。如果属性不存在，则仅显示摘要。
祖先详细信息揭示算法 应在 currentNode 上执行以下步骤
当 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 元素结合使用，允许用户将一组字段折叠成一组小的标题，并能够打开每个标题。
在这些示例中，摘要实际上只总结了控件可以更改的内容，而不是实际值，这并不理想。
以下示例显示了 name 属性的 details 元素用于创建排他性手风琴，这是一组 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 > 以下示例显示了在 open 属性设置为使用 name 属性创建排他性手风琴的一组元素的一部分的 details 元素上时会发生什么。
给定初始标记
< 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 元素的其余内容的摘要、标题或图例。
命令 是菜单项、按钮和链接背后的抽象。定义命令后，接口的其他部分可以引用同一个命令，从而允许多个访问点共享单个功能，例如 禁用状态 等面。
命令被定义为具有以下 面
用户代理可能会公开与以下标准匹配的命令
用户代理鼓励这样做，特别是对于具有访问键的命令，作为向用户宣传这些键的一种方式。
例如，这些命令可以列在用户代理的菜单栏中。
dialog 元素所有当前引擎都支持。
open — 对话框是否正在显示HTMLDialogElement。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 属性通常会隐藏对话框。但是，这样做会导致许多奇怪的额外后果
close 事件不会被触发。
如果对话框是使用其 showModal() 方法显示的，则 Document 仍然会被阻塞。
dialog.show()显示 dialog 元素。
dialog.showModal()显示 dialog 元素，并使其成为最顶层的模态对话框。
此方法遵守 autofocus 属性。
dialog.close([ result ])关闭 dialog 元素。
如果提供，参数将提供一个返回值。
dialog.returnValue [ = result ]返回 dialog 的返回值。
可以设置，以更新返回值。
我们使用 show/close 作为 dialog 元素的动词，而不是通常被认为是反义词的动词对，例如 show/hide 或 open/close，因为存在以下约束条件
隐藏对话框与关闭对话框不同。关闭对话框会给它一个返回值，触发一个事件，为其他对话框解阻塞页面等等。而隐藏对话框纯粹是一个视觉属性，你可以使用 属性或删除 open 属性来实现。（另请参阅关于删除 open 属性的上面的说明，以及如何隐藏对话框通常不理想）。
显示对话框与打开对话框不同。打开对话框包括创建并显示该对话框（类似于 window.open() 既创建又显示新窗口）。而显示对话框是指将已经存在于 DOM 中的 dialog 元素变为可交互的，并对用户可见。
如果我们想要一个 dialog.open() 方法，尽管有上述情况，它会与 dialog.open 属性冲突。
此外，对 dialog 元素的原始设计的许多其他与之同时期的 UI 框架的调查 表明 show/close 动词对在合理范围内很常见。
总之，事实证明，某些动词的含义以及它们在技术环境中的使用方式意味着，显示和关闭对话框等配对操作并不总是可以用反义词来表达。
此对话框包含一些小字。 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 >