<details>: 细节披露元素

基线 广泛可用

此功能已完善,可在多种设备和浏览器版本上运行。它自 2020 年 1 月.

<details> HTML 元素创建一个披露小部件,其中信息仅在小部件切换到“打开”状态时可见。必须使用 <summary> 元素提供摘要或标签。

披露小部件通常在屏幕上使用一个小三角形来表示,该三角形会旋转(或扭曲)以指示打开/关闭状态,旁边有一个标签。<summary> 元素的内容用作披露小部件的标签。<details> 的内容提供了 <summary>无障碍描述

试一试

<details> 小部件可以处于两种状态之一。默认的关闭状态仅显示<summary> 内的三角形和标签(如果沒有 <summary>,则显示 用户代理 定义的默认字符串)。

当用户点击小部件或聚焦它然后按下空格键时,它会“旋转”打开,显示其内容。三角形旋转或扭曲以表示打开或关闭小部件的常用方式是为什么这些有时被称为“扭转”。

您可以使用 CSS 来设置披露小部件的样式,并且可以通过设置/移除其 open 属性来以编程方式打开和关闭小部件。不幸的是,目前还没有内置方法来为打开和关闭之间的过渡设置动画。

默认情况下,关闭时,小部件的高度仅足以显示披露三角形和摘要。打开时,它会扩展以显示其中包含的详细信息。

完全符合标准的实现会自动将 CSS display: list-item 应用于 <summary> 元素。您可以使用它来进一步自定义其外观。有关更多详细信息,请参阅 自定义披露小部件

属性

此元素包含 全局属性

open

此布尔属性指示详细信息(即 <details> 元素的内容)当前是否可见。如果存在此属性,则显示详细信息,如果此属性不存在,则隐藏详细信息。默认情况下此属性不存在,这意味着详细信息不可见。

注意:您必须完全删除此属性才能使详细信息隐藏。open="false" 使详细信息可见,因为此属性是布尔属性。

name

此属性使多个 <details> 元素能够连接,并且一次只能打开一个。这允许开发人员轻松地创建 UI 功能(例如手风琴),而无需脚本。

name 属性指定组名 - 为多个 <details> 元素赋予相同的 name 值以将它们分组。一次只能打开分组的 <details> 元素中的一个 - 打开一个将导致另一个关闭。如果为多个分组的 <details> 元素赋予 open 属性,则仅在源代码顺序中的第一个元素将被渲染为打开状态。

注意:<details> 元素不必在源代码中彼此相邻才能属于同一个组。

事件

除了 HTML 元素支持的常用事件之外,<details> 元素还支持 toggle 事件,该事件在小部件状态在打开和关闭之间切换时,会分派到 <details> 元素。它在状态更改之后发送,但如果状态在浏览器能够分派事件之前多次更改,则事件将合并,因此只发送一个事件。

您可以使用 toggle 事件的事件监听器来检测小部件何时改变状态

js
details.addEventListener("toggle", (event) => {
  if (details.open) {
    /* the element was toggled open */
  } else {
    /* the element was toggled closed */
  }
});

示例

一个简单的披露示例

此示例显示了一个带有 <summary> 的简单 <details> 元素。

html
<details>
  <summary>System Requirements</summary>
  <p>
    Requires a computer running an operating system. The computer must have some
    memory and ideally some kind of long-term storage. An input device as well
    as some form of output device is recommended.
  </p>
</details>

结果

创建打开的披露框

要使<details>框在打开状态下启动,请添加布尔值open属性。

html
<details open>
  <summary>System Requirements</summary>
  <p>
    Requires a computer running an operating system. The computer must have some
    memory and ideally some kind of long-term storage. An input device as well
    as some form of output device is recommended.
  </p>
</details>

结果

多个命名披露框

我们包含了几个<details>框,它们都具有相同的名称,因此一次只能打开一个。

html
<details name="reqs">
  <summary>Graduation Requirements</summary>
  <p>
    Requires 40 credits, including a passing grade in health, geography,
    history, economics, and wood shop.
  </p>
</details>
<details name="reqs">
  <summary>System Requirements</summary>
  <p>
    Requires a computer running an operating system. The computer must have some
    memory and ideally some kind of long-term storage. An input device as well
    as some form of output device is recommended.
  </p>
</details>
<details name="reqs">
  <summary>Job Requirements</summary>
  <p>
    Requires knowledge of HTML, CSS, JavaScript, accessibility, web performance,
    privacy, security, and internationalization, as well as a dislike of
    broccoli.
  </p>
</details>

结果

尝试打开所有披露小部件。当你打开一个时,所有其他都会自动关闭。

自定义外观

现在让我们应用一些 CSS 来自定义披露框的外观。

CSS

css
details {
  font:
    16px "Open Sans",
    Calibri,
    sans-serif;
  width: 620px;
}

details > summary {
  padding: 2px 6px;
  width: 15em;
  background-color: #ddd;
  border: none;
  box-shadow: 3px 3px 4px black;
  cursor: pointer;
}

details > p {
  border-radius: 0 0 10px 10px;
  background-color: #ddd;
  padding: 2px 6px;
  margin: 0;
  box-shadow: 3px 3px 4px black;
}

details[open] > summary {
  background-color: #ccf;
}

此 CSS 创建了一个类似于选项卡界面的外观,单击选项卡会打开它以显示其内容。

选择器details[open]可用于设置打开元素的样式。

HTML

html
<details>
  <summary>System Requirements</summary>
  <p>
    Requires a computer running an operating system. The computer must have some
    memory and ideally some kind of long-term storage. An input device as well
    as some form of output device is recommended.
  </p>
</details>

结果

自定义披露小部件

披露三角形本身可以自定义,尽管这并不被广泛支持。由于元素被标准化,浏览器对这种自定义的支持存在差异,因此我们必须使用多种方法一段时间。

<summary>元素支持list-style速记属性及其完整属性,例如list-style-type,将披露三角形更改为任何你选择的内容(通常使用list-style-image)。例如,我们可以通过设置list-style: none来删除披露小部件图标。

CSS

css
details {
  font:
    16px "Open Sans",
    Calibri,
    sans-serif;
  width: 620px;
}

details > summary {
  padding: 2px 6px;
  width: 15em;
  background-color: #ddd;
  border: none;
  box-shadow: 3px 3px 4px black;
  cursor: pointer;
  list-style: none;
}

details > p {
  border-radius: 0 0 10px 10px;
  background-color: #ddd;
  padding: 2px 6px;
  margin: 0;
  box-shadow: 3px 3px 4px black;
}

此 CSS 创建了一个类似于选项卡界面的外观,激活选项卡会展开并打开它以显示其内容。

HTML

html
<details>
  <summary>System Requirements</summary>
  <p>
    Requires a computer running an operating system. The computer must have some
    memory and ideally some kind of long-term storage. An input device as well
    as some form of output device is recommended.
  </p>
</details>

结果

技术摘要

内容类别 流内容、分区根、交互式内容、可感知内容。
允许内容 一个<summary>元素,后面跟着流内容
标签省略 没有,开始和结束标签都是强制性的。
允许父级 任何接受流内容的元素。
隐式 ARIA 角色 group
允许 ARIA 角色 不允许role
DOM 接口 HTMLDetailsElement

规范

规范
HTML 标准
# the-details-element

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅