<details>:详细信息展现元素

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Some parts of this feature may have varying levels of support.

HTML <details> 元素可创建一个组件,仅在被切换成展开状态时,它才会显示内含的信息。<summary> 元素可为该部件提供概要或者标签。

展现组件通常在屏幕上使用一个小三角形,旋转(或扭转)以表示打开/关闭的状态,三角形旁边有一个标签。<summary> 元素的内容被用来作为展示小部件的标签。

尝试一下

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

当用户点击小组件或聚焦它然后按空格键时,它就会“扭转”展开,显示出其中的内容。通常使用一个旋转或扭转的三角形来代表打开或关闭小组件,这就是为什么这些小组件有时被称为“旋钮”。

你可以使用 CSS 来设计展示小组件,你可以通过设置/移除 open 属性以编程方式打开和关闭该小组件。遗憾的是,目前还没有内置的方法来对打开和关闭之间的过渡进行动画处理。

默认情况下,当关闭时,该小组件的高度只足以显示展开三角形和摘要。当打开时,它就会展开以显示其中包含的细节。

完全符合标准的实现会自动将 CSS display: list-item 应用到 <summary> 元素。你可以用它来进一步定制其外观。请参阅自定义展开组件以了解更多细节。

属性

此元素包含全局属性

open

这个布尔属性表示细节内容——也就是 <details> 元素的内容——目前是否可见。默认情况下为 false,意味着细节内容是不可见的。

备注: 你必须完全删除这个属性来使细节内容隐藏。open="false" 使细节内容可见,因为这个属性是布尔值。

事件

除了 HTML 元素支持的常规事件外,<details> 元素还支持 toggle 事件,当 <details> 元素的状态在打开和关闭之间变化时,该事件会被派发到该元素。该事件是在状态发生变化发送的,不过如果状态在浏览器派发该事件之前发生了多次变化,那么这些事件就会被合并,从而只发送一个。

你可以为 toggle 事件使用一个事件监听器来检测小组件何时改变状态:

js
details.addEventListener("toggle", (event) => {
  if (details.open) {
    /* 元素切换至打开状态 */
  } else {
    /* 元素切换至关闭状态 */
  }
});

示例

一个简单的展开示例

此示例展示了一个带有 <summary><details> 元素。

html
<details>
  <summary>系统需求</summary>
  <p>
    要求有一台运行操作系统的计算机。计算机必须有一些内存,最好有某种长期存储。建议有一个输入设备以及某种形式的输出设备。
  </p>
</details>

结果

创建一个展开的盒子

为了使得 <details> 盒子初始为展开状态,要添加布尔属性 open

html
<details open>
  <summary>系统需求</summary>
  <p>
    要求有一台运行操作系统的计算机。计算机必须有一些内存,最好有某种长期存储。建议有一个输入设备以及某种形式的输出设备。
  </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>系统需求</summary>
  <p>
    要求有一台运行操作系统的计算机。计算机必须有一些内存,最好有某种长期存储。建议有一个输入设备以及某种形式的输出设备。
  </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>系统需求</summary>
  <p>
    要求有一台运行操作系统的计算机。计算机必须有一些内存,最好有某种长期存储。建议有一个输入设备以及某种形式的输出设备。
  </p>
</details>

结果

技术概要

内容分类 流式内容、分段内容、交互内容、可感知内容
允许的内容 一个紧跟流式内容<summary> 元素
标签省略 不允许,开始标签和结束标签都不能省略。
允许的父元素 任何接受流式内容的元素。
隐含的 ARIA 角色 group
允许的 ARIA 角色 没有允许的 role
DOM 接口 HTMLDetailsElement

规范

Specification
HTML
# the-details-element

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
details
name
open

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.

参见