详情和摘要

探索非常有用的详细信息和摘要元素的运作方式,以及在何处 使用它们。

披露声明微件是一种用于隐藏和显示内容的界面控件。如果您正在 web.dev 上阅读此内容, 视口宽度小于 106em,点击“在此页面上”此段落上方会显示 部分。如果看不到该菜单,请缩小浏览器,以便以浏览方式查看本页中的目录导航 披露声明微件。

手风琴式折叠图形界面是一系列垂直堆叠的 披露声明微件。手风琴用户界面的一个常见用例是许多网站上的常见问题解答 (FAQ) 页面。 手风琴式常见问题解答包含一系列可见问题;点击相应问题即可展开(即“揭示”)该问题的答案。

至少从 2009 年开始,jQuery 就添加了手风琴式界面模式。原始版本,无 JavaScript 手风琴式解决方案解决方案包括:将每个常见问题解答问题设为 <label>,后跟标记的对勾标记,然后显示 <div> 回答。CSS 如下所示:

#FAQ [type="checkbox"] + div.answer {
  /* all the answer styles */
  display: none;
}
#FAQ [type="checkbox"]:checked + div.answer {
  display: block;
}

为什么会见到历史?不含 JavaScript 或表单控制黑客行为的披露微件(例如手风琴)是相对较新的 添加;<details><summary> 自 2020 年 1 月起,才在所有现代浏览器中才获得完全支持。现在,您可以创建正常运行了, 而不只是使用语义 HTML 的醒目披露声明 widget。您只需要 <details><summary> 元素即可:它们是用于处理 展开和收起内容当用户点击或点按 <summary>,或在以下情况下释放 Enter 键时 <summary> 获得焦点,父级 <details> 切换开关的内容可见!

与所有语义内容一样,您可以逐步增强默认功能和外观。在此示例中,有一点 已添加 CSS,但没有添加任何其他内容:

您会注意到,这些 Codepen 不包含任何 JavaScript。

切换可见性:open 属性

<details> 元素是披露声明 widget 容器。<summary> 是其父级 <details> 的摘要或图例。通过 summary 始终显示,用作切换父内容其余内容的显示按钮。互动 如果使用 <summary>,则通过切换 <details>元素的 open 属性。

open 属性是一个布尔值属性。如果存在,无论其值如何,无论该值如何,它都表示所有 <details> 向用户显示的内容如果 open 属性不存在,则只显示 <summary> 的内容。

由于系统会在用户与控件互动时自动添加和移除 open 属性,因此该属性可以在 CSS 中使用 根据元素的状态为其设置不同的样式。

您可以创建手风琴式折叠,其中包含多个 <details> 元素,每个元素都有一个 <summary> 子元素。省略 open 属性 表示 <details> 将全部收起或关闭,并且在网页加载时仅显示摘要标题; 每个标题都是父 <details> 中其余内容的开头。如果您在 HTML 中添加 open 属性,则 <details> 会在网页加载时展开并显示其内容。

处于收起状态的隐藏内容在某些浏览器中是可搜索的,而在另一些浏览器中则是无法搜索到的,即使处于收起状态的内容也是如此 不是 DOM 的一部分。如果您在 Edge 或 Chrome 中进行搜索,系统会展开包含搜索字词的详细信息 出现的问题。Firefox 或 Safari 不会复制此行为。

<summary> 必须是 <details> 元素的第一个子元素,表示其余元素的摘要、图片说明或图例 嵌套该元素的父 <details> 元素的内容。<summary> 元素的内容可以是任何标题 内容、纯文本或 HTML,都可以在段落内使用。

切换摘要标记

在前面的两个 Codepen 中,您会注意到箭头指向 inline-start 显示在摘要中披露微件通常使用可旋转(或扭转)的小三角形显示在屏幕上。 使用三角形旁边的标签来指示营业/停业状态。<summary> 元素的内容会标记披露 widget。 每个部分顶部的旋转箭头是一个::marker设置在 <summary> 元素。与列表项一样,<summary> 元素支持 list-style 简写属性及其长手属性,包括 list-style-type。 您可以使用 CSS 设置披露三角形的样式,包括将使用的标记从三角形更改为任何其他项目符号类型,包括 使用 list-style-image 生成图片。

如需应用其他样式,请使用类似于 details summary::marker 的选择器。通过 ::marker 伪元素仅接受有限数量的样式。移除 ::marker 并将其替换为更易风格的 ::before, 常见做法,CSS 样式会根据所生成内容的存在(或不存在)略微更改所生成内容的样式 属性。您可以通过设置 list-style: none 移除披露微件图标,也可以设置内容none 为准,但务必添加视觉指示符,以告知视力正常的用户摘要内容是一个切换开关 按钮。

details summary::before {
  /* all the styles */
}
details[open] summary::before {
  /* changes applied when open only */
}

此示例移除了默认标记,并添加生成的内容,以便在详情关闭和 - 时创建 +。 打开详细信息时

如果您希望详细信息块默认处于打开状态,请在起始 <details> 标记中添加 open 属性。您还可以添加空间 并转换使用生成内容创建的标记的旋转角度,以改善外观:

错误的处理方式

如果您未添加 <summary>,浏览器将为您创建一个:使用标记和“details”一词。此摘要 属于影子根,因此不会应用作者 CSS 摘要样式。遗憾的是,Safari 并不支持 键盘焦点顺序中的详细信息。

如果您添加了 <summary>,但它不是 <details> 中的第一个元素,浏览器仍会显示摘要 正常。同样,如果您在摘要中添加了链接、标签或其他互动元素, 以不同的方式处理互动内容中的互动内容。例如,如果您在摘要中添加了链接,某些浏览器 会同时将摘要和链接添加到默认 Tab 键导航顺序中,但默认情况下其他浏览器不会重点关注该链接。 如果您点击嵌套在 <summary> 中的 <label>,某些浏览器会将焦点放在关联的表单控件上;其他浏览器 会将焦点置于表单控件上,并将 <details> 切换为开启或关闭。

HTMLDetailsElement 接口

与所有 HTML 元素一样,HTMLDetailsElement 继承所有 来自 HTMLElement 的属性、方法和事件,并将 open 实例属性和 toggle 事件。HTMLDetailsElement.open 属性是一个布尔值 反映 open HTML 属性的值,用于表示 是否向用户显示相应元素的内容(不计算 <summary>)。触发切换事件 当 <details> 元素打开或关闭时触发。您可以使用 addEventListener() 监听此事件。

如果您想编写一个脚本,以在用户打开任何其他详细信息时关闭已打开的详细信息,请移除“打开”属性 使用 removeAttribute("open")

这是唯一一个使用 JavaScript 的示例。除了关闭其他 打开披露声明 widget。

请注意,<details><summary> 可以具有丰富的样式,甚至可以用于创建工具提示。 但是,如果您要在原生语义不匹配的用例中使用这些语义元素,请始终确保保持可访问性。 默认情况下,HTML 在大多数情况下是可访问的。作为开发者,我们的职责是确保我们提供的内容随时可供访问。

检查您的理解情况

测试您对详细信息和总结知识的掌握情况。

<summary> 必须是哪个元素的第一个子元素?

<fieldset>
<p>
<details>