跳至中央內容區塊 :::
:::

給開發者的 ARIA Patterns：先用原生 HTML，再補 ARIA

用可執行的展開內容範例，比較原生 details 與 button 加 ARIA 的做法，確認名稱、狀態、鍵盤與可見內容如何配合，再查 W3C APG 的完整模式。

最後更新:

重點摘要

  • 先選符合任務的原生元素，再確認是否需要補充 ARIA。
  • ARIA 表達語意與狀態，不會自動完成鍵盤操作或內容切換。
  • 使用 APG Patterns 時，要同時實作鍵盤操作、焦點管理與狀態更新。

先用原生 HTML，真的不夠再用 ARIA

ARIA 的第一原則很直接：能用原生 HTML 就不要先加 ARIA。button、a、input、select、details、summary 這些元素已經帶有瀏覽器和輔助科技理解的語意與鍵盤行為。

如果用 div 或 span 重新做按鈕、選單或分頁，就必須自己補上名稱、角色、狀態、鍵盤操作與焦點管理。這通常比使用原生元素更容易出錯。

先試原生展開內容：details 與 summary

只是讓讀者展開一段補充資訊時，可先評估 details／summary 是否符合需求。這個原生版本不需要自己加 role、aria-expanded 或切換腳本；仍要在支援的瀏覽器與輔助科技上確認。

<details>
  <summary>配送說明</summary>
  <p>包裹寄出後會提供追蹤方式。</p>
  <a href="/contact/">詢問配送方式</a>
</details>

這是虛構商店的互動示例，不是 Accesserty 的配送服務。預期 Tab 到 summary，Enter／Space 切換內容；收合時不會 Tab 到內部連結。不要把這個簡單展開模式當成選單或 tabs，替它加上不相干的方向鍵規則。

需要自訂結構時：可操作的 ARIA 展開範例

若原生 details 不符合實際需求，以下用原生 button 保留 Enter／Space 操作，再以 aria-expanded 表達狀態。aria-controls 指向被控制區域；它是關係資訊，不會自動切換畫面。腳本未執行時保留內容可讀、隱藏尚不可操作的按鈕。

<button id="delivery-toggle" type="button" hidden
  aria-expanded="false" aria-controls="delivery-panel">
  配送說明
</button>
<div id="delivery-panel">
  <p>包裹寄出後會提供追蹤方式。</p>
  <a href="/contact/">詢問配送方式</a>
</div>
<script>
{
  const toggle = document.getElementById('delivery-toggle');
  const panel = document.getElementById('delivery-panel');
  toggle.addEventListener('click', () => {
    const expanded = toggle.getAttribute('aria-expanded') === 'true';
    panel.hidden = expanded;
    toggle.setAttribute('aria-expanded', String(!expanded));
  });
  panel.hidden = true;
  toggle.hidden = false;
}
</script>

把整段 HTML 與腳本放進獨立測試頁。初始化後內容收合，按鈕仍叫「配送說明」；Enter／Space 會各切換一次 expanded 與 hidden，焦點留在按鈕。展開後 Tab 才能進入內部連結。腳本只監聽 click，因為原生按鈕已處理鍵盤啟動；不要再加一組重複切換的 keydown。這是單一元件示範，多個實例需使用不同 ID 並分別綁定；有 CSP 的網站請放進允許的外部腳本，不要為範例放寬政策。

不要只複製 role

ARIA 只改變輔助科技接收到的語意，不會自動補上互動行為。role="button" 不會讓 div 自動支援 Enter 或 Space；aria-expanded="true" 也不會自動打開內容或管理焦點。

錯誤 ARIA 會讓畫面看起來正常，但讓輔助科技收到錯誤訊號。這比沒有 ARIA 更難除錯，因為問題常常只出現在螢幕閱讀器、語音控制或鍵盤流程中。

參考 APG 時，鍵盤、焦點與語意要一起實作

W3C 的 ARIA Authoring Practices Guide（APG）提供互動元件的實作指引。它的模式範例適合當作分頁、對話框、摺疊區塊、選單按鈕與組合輸入框的參考，但不能只複製其中一兩個屬性：鍵盤操作、焦點位置、可及名稱、角色、狀態與 HTML 元素之間的關係要一起確認。參考範例不等於整個網站已符合 WCAG。

  • 名稱：使用者聽到或看到的控制項名稱是否清楚。
  • 角色：role 是否符合元件實際用途。
  • 狀態：expanded、selected、checked、disabled 等狀態是否即時更新。
  • 鍵盤：方向鍵、Enter、Space、Escape、Tab 的行為是否符合該元件的操作方式。
  • 焦點：開啟、關閉、切換內容後，焦點是否落在合理位置。

常見錯誤

ARIA 問題常見於自訂元件、設計系統元件與第三方元件。這些元件一旦被重複使用，錯誤也會跟著出現在很多頁面，所以應該盡量在元件層修正。

  • 用 role 改語意，卻沒有補鍵盤操作。
  • aria-label 覆蓋了畫面上更清楚的文字。
  • aria-hidden 隱藏了仍可聚焦或仍可操作的內容。
  • aria-expanded、aria-selected、aria-current 等狀態沒有跟畫面同步。
  • dialog、menu 或 tabs 看起來可用，但焦點管理不符合使用者預期。

DevCheck 與 UI Kit 的角色

DevCheck 可以協助在目前頁面找出部分 ARIA 與語意問題，也能讓團隊在互動後狀態重新檢查。但它不能替你保證 pattern 已完整實作，因為鍵盤行為、焦點管理和內容理解仍需要人用真實流程測。

UI Kit 的方向則是在元件層減少重複錯誤。對常用元件來說，越早把原生 HTML、ARIA、鍵盤和焦點規則放進元件基礎，越不容易在每個頁面重新犯同樣的錯。

相關頁面