跳到主要內容

Accordion

Demo 與 Accessibility Tree

讓產品在不同能力、不同情境的使用者身上都能運作 —— 包含使用螢幕閱讀器、只用鍵盤、視力受限，或只是身處在陽光下看不清螢幕的人。

Accessibility Tree

觀察對象：第一個標題按鈕。

元素目前不在無障礙樹中。

Accessibility Tree

觀察對象：展開中的面板。

元素目前不在無障礙樹中。

鍵盤操作

按鍵行為
Enter / Space展開已收合的面板；若該面板可收合，再按一次收合。一次只能展開一個時，展開新面板會收合原本展開的。
Tab移至下一個可聚焦元素。所有標題按鈕都在頁面的 Tab 順序中。
Shift + Tab移至上一個可聚焦元素。

ARIA 屬性

屬性值用途
rolebutton標題列必須是按鈕。用原生 <button> 即隱含此角色，不需另外書寫。
aria-expandedtrue / false反映對應面板此刻是否可見，是這個元件最核心的狀態。
aria-controls面板元素的 id把按鈕與它控制的面板關聯起來。
aria-disabledtrue已展開且不允許收合時標上。與原生 disabled 不同：元素仍可聚焦，行為要自己擋。
roleregion面板作為地標，讓使用者能直接跳過去。面板超過約六個時應停用，否則地標清單會被灌爆。
aria-labelledby標題按鈕的 id面板用 role=region 時，以它的標題按鈕作為無障礙名稱。
aria-hiddentrue箭頭圖示是純視覺，狀態已由 aria-expanded 表達，不應重複進入無障礙樹。

WCAG 對應

  • 等級 A1.3.1 資訊與關聯性

    標題按鈕包在 heading 內且層級符合頁面資訊架構；heading 內只能有那顆按鈕，其他持續顯示的元素要放到外面。面板以 aria-labelledby 與自己的標題關聯。

  • 等級 A2.1.1 鍵盤

    Enter 與空白鍵即可展開收合，不需要滑鼠。

  • 等級 A2.4.3 焦點順序

    所有標題按鈕都納入頁面的 Tab 順序，順序與視覺順序一致。

  • 等級 AA2.4.7 焦點可見

    每個標題按鈕都有橘色 focus ring。

  • 等級 A4.1.2 名稱、角色、值

    標題列具備 button 角色，aria-expanded 隨面板可見狀態更新，aria-controls 指向被控制的面板。

APG 規則

  • 元件語意

    Accordion 標題列具有 button 角色語意

    每個 Accordion 的標題控制元件須具備 role=button 。

  • 頁面結構

    Accordion 的標題標籤內只能包含其標題按鈕

    Accordion 的標題按鈕是其 heading 標籤內唯一的元素；其他視覺上持續顯示的元素須置於 heading 標籤外部。

  • 頁面結構

    Accordion 標題列使用適當的標題層級

    每個 Accordion 的標題按鈕須包含在 heading 標籤內，且標題層級須符合頁面的資訊架構。

  • 元件語意

    Accordion 的 aria-expanded 須正確反映內容區塊的展開狀態

    每個 Accordion 的標題按鈕在對應內容區塊可見時，aria-expanded 須為 true；內容區塊不可見時則須為 false。

  • 元件語意

    已展開且不可收合的 Accordion 標題列須標記 aria-disabled

    若已展開的內容區塊不允許收合，其標題按鈕須設定 aria-disabled=true。

  • 元件語意選做

    Accordion 的內容區域 （region）須以對應的標題按鈕作為無障礙名稱

    若 Accordion 的內容區域使用 role=region，須透過 aria-labelledby 對應至該內容區域的按鈕。

  • 頁面結構選做

    Accordion 應避免產生過多的區域地標（region landmarks）

    若 Accordion 的內容區域使用 role=region，應避免產生過多的地標，例如當頁面中可同時展開的內容區域超過約六個時，就須謹慎使用。

  • 鍵盤操作

    Accordion 標題列可用 Enter 鍵或 Space 鍵切換展開與收合

    當鍵盤焦點位於 Accordion 的標題列時，按下 Enter 或空白鍵可展開已收合的面板；若支援收合功能，再按一次可收合已展開的面板。若頁面只允許同時展開一個面板，展開新面板時會自動收合原本展開的面板。

  • 焦點管理

    Accordion 的可聚焦元素依循頁面的 Tab 鍵順序

    Tab 鍵與 Shift+Tab 鍵可分別移至下一個與上一個可聚焦元素； Accordion 中所有可聚焦元素皆須納入頁面的 Tab 鍵順序。