詳細資料與摘要

瞭解實用細節和摘要元素的運作方式,以及說明 以便使用。

揭露小工具是一種使用者介面控制項,可用於隱藏及顯示內容。如果您是在 web.dev 上讀取這項資訊,且 可視區域寬度小於 106 em,請按一下 [在這個頁面上]上方顯示的是 本節如果沒看到,請將瀏覽器縮小以檢視此網頁上的目錄內容表格 揭露聲明小工具。

摺疊圖形使用者介面是一系列垂直堆疊的 揭露小工具。摺疊式使用者介面常見的用途是許多網站的「常見問題」(FAQ) 網頁。 摺疊式常見問題包含可見問題清單;按一下問題即可展開 (或「揭露」)。

jQuery 至少包含 2009 年起的摺疊式 UI 模式。不含 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> 元素。你現在可以建立功能了,但其實更少 而不是只用語意 HTML 達到引人注目的揭露小工具。您只需要 <details><summary> 元素即可:兩者是內建的處理方法 可展開及收合內容當使用者點選或輕觸 <summary>,或是在執行以下動作時放開 Enter<summary> 有焦點,系統會顯示父項 <details> 切換按鈕的內容!

如同所有語意內容,您可以逐步強化預設功能和外觀。在這個例子中 新增 CSS,但沒有其他任何內容:

請注意,這些 Codepens 不包含 JavaScript。

切換顯示設定:open 屬性

<details> 元素是揭露聲明小工具容器。<summary> 是其父項 <details> 的摘要或圖例。 摘要 始終顯示,充當按鈕,可切換顯示父項內容的其他部分。互動 使用 <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。

切換摘要標記

在先前的兩個 Codepens 中,您會看到 inline-start 箭頭 摘要部分揭露聲明小工具通常會使用可旋轉 (或扭曲) 的小三角形圖示 表示處於營業/關閉狀態,且三角形旁邊有標籤。揭露小工具的 <summary> 元素內容標籤。 每個部分頂端的旋轉箭頭都是 ::marker<summary> 元素。如同清單項目,<summary> 元素支援 list-style 簡寫屬性及長途屬性,包括 list-style-type。 你可以使用 CSS 設定揭露三角形的樣式,包括將使用的標記從三角形變更為其他項目符號類型,包括: 帶有 list-style-image 的圖片。

如要套用其他樣式,請使用與 details summary::marker 類似的選取器。 ::marker pseudo-element 只接受有限的樣式。移除 ::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> 中的第一個元素,瀏覽器仍會顯示摘要 。也不會在摘要中加入連結、標籤或其他互動元素,但不包括瀏覽器 以不同方式處理互動式內容中的互動式內容。舉例來說,如果您在摘要中加入連結,表示部分瀏覽器 會在預設標籤順序中加入摘要與連結,但其他瀏覽器預設不會聚焦在連結上。 如果您點選 <summary> 中的巢狀 <label>,部分瀏覽器會將焦點移至相關聯的表單控制項;其他瀏覽器 可讓焦點移至表單控制項,並將 <details> 切換為開啟或關閉。

HTMLDetailsElement 介面

如同所有 HTML 元素,HTMLDetailsElement 會沿用所有元素 屬性、方法和事件HTMLElement,然後將 open 執行個體屬性和 toggle 活動。HTMLDetailsElement.open 屬性為布林值 值會反映 open HTML 屬性,表示 是否要向使用者顯示元素內容 (不含 <summary>)。切換事件會觸發 <details> 元素切換開啟或關閉時。您可以使用 addEventListener() 監聽這個事件。

如要編寫指令碼,在使用者開啟任何其他詳細資料時關閉已開啟的詳細資料,請移除開啟屬性 使用 removeAttribute("open")

這是唯一使用 JavaScript 的範例。您可能不需使用 JavaScript,但此功能會關閉其他 開啟揭露聲明小工具。

請注意,<details><summary> 可大幅設定樣式,甚至還能用來建立工具提示。 不過,如要將這些語意元素用於原生語意不相符的用途,請一律確保維持無障礙功能。 大多數部分的 HTML 都預設為可存取。我們身為開發人員的職責,是確保使用者無法存取我們的內容。

隨堂測驗

測試您對細節和摘要的瞭解程度。

<summary> 必須是哪個元素的第一個子項?

<details>
<p>
<fieldset>