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

<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 事件的事件監聽器來檢測小部件何時更改狀態：

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

範例

簡單的揭露範例

此範例顯示一個簡單的 <details> 元素及其 <summary>。

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>

結果

自定義外觀

現在讓我們應用一些 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`

規範

Specification
HTML Standard # the-details-element

瀏覽器相容性

BCD tables only load in the browser

參見

<summary>