<details>: The Details disclosure element

<details> 小部件可以处于两种状态之一。默认关闭状态仅显示 <summary> 内的三角形和标签（如果没有 <summary>，则显示 user agent 定义的默认字符串）。

¥A <details> widget can be in one of two states. The default closed state displays only the triangle and the label inside <summary> (or a user agent-defined default string if no <summary>).

当用户单击小部件或将其聚焦然后按空格键时，它会打开并显示其内容。通常使用旋转或扭转的三角形来表示打开或关闭小部件，这就是为什么它们有时被称为 "twisty"。

¥When the user clicks on the widget or focuses it then presses the space bar, it "twists" open, revealing its contents. The common use of a triangle which rotates or twists around to represent opening or closing the widget is why these are sometimes called "twisty".

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

¥You can use CSS to style the disclosure widget, and you can programmatically open and close the widget by setting/removing its open attribute. Unfortunately, at this time, there's no built-in way to animate the transition between open and closed.

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

¥By default when closed, the widget is only tall enough to display the disclosure triangle and summary. When open, it expands to display the details contained within.

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

¥Fully standards-compliant implementations automatically apply the CSS display: list-item to the <summary> element. You can use this to customize its appearance further. See Customizing the disclosure widget for further details.

¥Attributes

该元素包括 全局属性。

¥This element includes the global attributes.

open

该布尔属性指示详细信息（即 <details> 元素的内容）当前是否可见。当此属性存在时，详细信息将显示；当此属性不存在时，详细信息将隐藏。默认情况下，此属性不存在，这意味着详细信息不可见。

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

¥Note: You have to remove this attribute entirely to make the details hidden. open="false" makes the details visible because this attribute is Boolean.

name

此属性允许连接多个 <details> 元素，一次只能打开一个。这使得开发者无需编写脚本即可轻松创建 UI 功能，例如手风琴。

name 属性指定组名称 - 为多个 <details> 元素提供相同的 name 值以对它们进行分组。一次只能打开一组 <details> 元素中的一个 - 打开一个元素将导致另一个元素关闭。如果多个分组的 <details> 元素被赋予 open 属性，则只有源顺序中的第一个元素将被呈现为打开。

注意：<details> 元素不必在源中彼此相邻才能成为同一组的一部分。

¥Note: <details> elements don't have to be adjacent to one another in the source to be part of the same group.

¥Events

除了 HTML 元素支持的常见事件之外，<details> 元素还支持 toggle 事件，只要 <details> 元素的状态在打开和关闭之间发生变化，该事件就会分派到 <details> 元素。它是在状态更改后发送的，但如果在浏览器分派事件之前状态发生多次更改，则事件将合并，以便仅发送一个。

¥In addition to the usual events supported by HTML elements, the <details> element supports the toggle event, which is dispatched to the <details> element whenever its state changes between open and closed. It is sent after the state is changed, although if the state changes multiple times before the browser can dispatch the event, the events are coalesced so that only one is sent.

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

¥You can use an event listener for the toggle event to detect when the widget changes state:

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

¥Examples

¥A simple disclosure example

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

¥This example shows a simple <details> element with a <summary>.

<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>

结果

¥Result

¥Creating an open disclosure box

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

¥To start the <details> box in its open state, add the Boolean open attribute:

<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>

结果

¥Result

¥Customizing the appearance

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

¥Now let's apply some CSS to customize the appearance of the disclosure box.

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 创建类似于选项卡式界面的外观，单击选项卡将打开它以显示其内容。

¥This CSS creates a look similar to a tabbed interface, where clicking the tab opens it to reveal its contents.

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

¥The selector details[open] can be used to style the element which is open.

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>

结果

¥Result

¥Customizing the disclosure widget

显示三角形本身可以定制，尽管这没有得到广泛支持。由于元素标准化后的实验性实现，浏览器支持此自定义的方式存在差异，因此我们将不得不在一段时间内使用多种方法。

¥The disclosure triangle itself can be customized, although this is not as broadly supported. There are variations in how browsers support this customization due to experimental implementations as the element was standardized, so we'll have to use multiple approaches for a while.

<summary> 元素支持 list-style 简写属性及其普通属性（例如 list-style-type），以将显示三角形更改为你选择的任何内容（通常使用 list-style-image）。例如，我们可以通过设置 list-style: none 来删除公开小部件图标。

¥The <summary> element supports the list-style shorthand property and its longhand properties, such as list-style-type, to change the disclosure triangle to whatever you choose (usually with list-style-image). For example, we can remove the disclosure widget icon by setting list-style: none.

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 创建类似于选项卡式界面的外观，其中激活选项卡会展开并打开它以显示其内容。

¥This CSS creates a look similar to a tabbed interface, where activating the tab expands and opens it to reveal its contents.

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>

结果

¥Result

¥Technical summary

¥See also

• <summary>