紀錄工作經驗、相關知識,解決技術相關問題。

HTML

HTML search 標籤教學:ARIA search 地標無障礙實作與 SearchAction 結構化資料現況

HTML search 標籤教學:ARIA search 地標無障礙實作與 SearchAction 結構化資料現況 特色圖片

在過往十多年的前端開發中,八大 WAI-ARIA 無障礙地標裡唯獨 role="search" 遲遲沒有對應的原生 HTML 元素,導致工程師必須在 <form role="search"> 或 <div role="search"> 上手動掛載 ARIA 屬性。直到 2023 年 3 月,WHATWG 正式將 HTML search 標籤(<search>)納入 HTML Living Standard(PR #7320),終於補齊了原生語意地標的最後一塊拼圖。這篇技術筆記將從 WHATWG HTML §4.4.15 與 W3C HTML-AAM 1.0 規範出發,帶你釐清 <search> 與 <form> 的職責差異、SPA 無表單即時篩選實作,以及常見的雙重地標誤區。


⚡ 快速簡單使用(30 秒複製即用範本)

以下提供兩種最常見的生產級 HTML search 標籤實作範本:情境 A(傳統 GET 表單全站搜尋)與情境 B(無須 <form> 的 SPA 即時前端篩選器,搭配 aria-live="polite" 播報結果筆數):

<!-- 情境 A:傳統全站關鍵字搜尋(注意內部 form 切勿再加 role="search",避免產生雙重巢狀地標) -->
<search class="site-search" aria-label="全站文章">
  <form action="/search" method="get">
    <label for="global-search-input" class="visually-hidden">搜尋技術文章關鍵字</label>
    <input
      id="global-search-input"
      type="search"
      name="q"
       autocomplete="off"
      placeholder="輸入關鍵字(例如:hgroup、ARIA)..."
      required
    >
    <button type="submit">搜尋</button>
  </form>
</search>

<!-- 情境 B:SPA 即時條件過濾器(WHATWG 規範明確支援不包 form 的純前端 JavaScript 篩選區塊) -->
<search class="live-filter" aria-label="專案列表條件篩選">
  <div class="filter-controls">
    <label for="project-filter-input">依名稱即時過濾:</label>
    <input
      id="project-filter-input"
      type="search"
      placeholder="輸入專案名稱..."
    >
  </div>
  <!-- 搭配 role="status" (隱含 aria-live="polite") 向螢幕閱讀器即時回報過濾後筆數 -->
  <p id="filter-result-count" role="status" aria-live="polite">
    目前顯示全部 24 個專案
  </p>
</search>

一、核心速查:HTML search 標籤與相關搜尋語意元素對照表

不少初學者容易將容器層級的 <search>、表單提交層級的 <form> 與輸入框層級的 <input type="search"> 混為一談,甚至誤以為 <search> 對應的是 region 角色。以下依據官方規範整理四者的精確定位:

元素或屬性規範標準與引入時間W3C HTML-AAM 無障礙角色映射核心職責與工程注意事項
<search>WHATWG HTML §4.4.15(2023 年 3 月新增)隱式映射為 role="search" 地標(注意:並非 role="region"!)包裝所有與「搜尋或資料篩選(Filtering)」相關的表單控制項、快速篩選標籤與即時搜尋結果區
<form>HTML 2.0(RFC 1866)即已定義對應 role="form",但沒有無障礙名稱時不作為地標公開負責將使用者輸入欄位序列化並發送 HTTP GET/POST 請求(若已包在 <search> 內,無須再加 role="search")
<input type="search">WHATWG HTML 表單控制項沒有 list 建議清單時映射為 role="searchbox"單行搜尋文字輸入框;規範說明它與 type="text" 的差異主要在外觀。想提示虛擬鍵盤的 Enter 鍵顯示「搜尋」,可另加 enterkeyhint="search"
role="search"W3C WAI-ARIA 1.2顯式宣告為 search 地標舊版無 <search> 時代的作法;在現代專案中已可直接由原生 <search> 取代

二、為什麼有了 form role="search" 還需要新增 HTML search 標籤?

在 Code Review 時,常有工程師提問:「既然以前在 <form role="search"> 加個屬性就能產生搜尋地標,為什麼 WHATWG 在 2023 年還要特地新增一個 <search> 標籤?」

根據 WHATWG HTML Living Standard §4.4.15 的設計規範,<search> 解決了傳統 <form role="search"> 無法涵蓋的兩大現代前端場景:

WHATWG HTML search 標籤涵蓋範圍與兩大實作架構圖

圖:HTML <search> 標籤支援之「傳統 <form> 提交搜尋」與「SPA 無 <form> 即時動態篩選」雙架構對照

1. 場景一:無須 form 提交的現代 SPA 即時篩選器(Client-Side Filtering)

在 React、Vue 或 Alpine.js 建構的現代儀表板與電商商品列表中,使用者在輸入框打字或點擊篩選膠囊按鈕(Filter Chips)時,前端常直接透過 Array.prototype.filter() 或非同步 fetch() 即時更新列表,根本不需要觸發傳統 <form> 的頁面跳轉提交。
過去為了避免假表單提交,開發者只能退而求其次寫 <div role="search">;現在規範明確指出:<search> 內部不強制包含 <form> 元素,任何執行「搜尋(Searching)或過濾(Filtering)」功能的控制項組合,都能直接用 <search> 語意化包裹!

2. 場景二:將「搜尋輸入框」與「即時搜尋結果/歷史熱詞」納入同一地標

當使用者在頂部搜尋框輸入文字並彈出「即時搜尋建議下拉面板(Autocomplete Results)」或「熱門搜尋關鍵字清單」時,這些元素在 DOM 結構上通常位於 <form> 標籤之外。使用外層的 <search> 容器,就能將 <form> 與下方的結果列表完整封裝在同一個 search 地標內:

<search aria-label="技術文件檢索">
  <form action="/docs/search" method="get">
    <label for="doc-q">搜尋 API 文件</label>
    <input id="doc-q" type="search" name="q" aria-controls="quick-results">
    <button type="submit">查詢</button>
  </form>

  <!-- 位於 form 外部、但同屬 search 地標範圍內的即時搜尋結果區 -->
  <div id="quick-results" role="region" aria-label="即時搜尋建議" aria-live="polite">
    <p>熱門檢索關鍵字:<a href="/docs/search?q=CSP">CSP 政策</a>、<a href="/docs/search?q=SRI">SRI 雜湊</a></p>
  </div>
</search>

三、無障礙踩坑排查:使用 HTML search 標籤最常犯的三大誤區

在導入 HTML search 標籤時,若未留意 W3C 無障礙名稱計算(AccName 1.2)與地標嵌套規則,極易在無障礙檢測工具中產生反效果:

搜尋地標常見巢狀與命名反模式 vs. W3C HTML-AAM 1.0 標準寫法對照圖

圖:<search> 地標最常見的「雙重巢狀宣告」、「aria-label 角色詞重複」與「Label 雙重覆蓋」三大誤區與修正方案

1. 誤區一:在 search 內部又寫 form role="search" 造成雙重巢狀地標

許多工程師在重構舊程式碼時,直接把外層的 <div> 改成 <search>,卻忘了把內部 <form role="search"> 的 role="search" 拔掉:

<!-- ❌ 錯誤寫法:外層 search 與內層 form role="search" 形成兩個重疊的 search 地標! -->
<search>
  <form action="/search" method="get" role="search">
    ...
  </form>
</search>

<!-- ✅ 正確寫法:由外層 <search> 獨自承擔 search 地標角色,內部 <form> 保持純淨 -->
<search>
  <form action="/search" method="get">
    ...
  </form>
</search>

根據 W3C HTML-AAM 1.0 (#el-search),<search> 本身就對應 role="search";依 MDN 瀏覽器相容性資料,Chrome 118、Edge 118、Firefox 118、Safari 17 起支援 <search> 元素。在內層 <form> 再加上 role="search",無障礙樹中就會出現兩層巢狀的 search 地標,螢幕閱讀器的地標清單也會多出一個重複的搜尋地標。

2. 誤區二:在 aria-label 中寫入「搜尋」二字導致語音重複

當單一頁面同時擁有「頂部全站搜尋」與「側欄商品篩選」兩個 <search> 標籤時,必須透過 aria-label 或 aria-labelledby 區分(APG 地標規範:頁面有多個 search 地標時,每個都應有獨一無二的標籤)。同一份規範也提醒不要把地標角色寫進標籤,因為輔助科技播報地標時會一併唸出角色名稱:

  • ❌ 錯誤命名:<search aria-label="全站搜尋"> ➔ 螢幕閱讀器播報:"全站搜尋 搜尋"。
  • ✅ 正確命名:<search aria-label="全站文章"> 或 <search aria-label="商品規格"> ➔ 螢幕閱讀器播報:"全站文章 搜尋"。

3. 誤區三:既有 label for="..." 卻又在 input 重複加上 aria-label

在表單無障礙設計中,每個 <input type="search"> 都必須有明確的標籤。有些新手寫了 <label for="site-q">搜尋本站內容:</label>,又在 <input id="site-q"> 上加了一模一樣的 aria-label="搜尋本站內容"。
這完全是多此一舉:當畫面上允許顯示文字標籤時,直接使用 <label for="site-q"> 即可;若視覺設計稿只有放大鏡圖示、不顯示文字標籤,也應優先使用 .visually-hidden(.sr-only)隱藏 <label for="site-q">,維持單一命名來源。


四、站內搜尋框與結構化資料(Schema.org WebSite / SearchAction)現況解析

在探討 HTML search 標籤與 SEO 的關聯時,必須建立一個客觀的工程認知:HTML 的 <search> 標籤主要服務於瀏覽器語意結構與輔助科技(Screen Reader)地標導覽;而搜尋引擎對站內搜尋網址結構的理解,則是透過 GET 查詢參數與 Schema.org JSON-LD。

📌 Google 已停用網站連結搜尋框(Sitelinks Search Box):
過去許多 SEO 教學會宣稱加上 WebSite + SearchAction 結構化資料,就能在 Google 搜尋結果顯示「網站連結搜尋框」。Google 在 2024 年 10 月 21 日的 Search Central 部落格公告中說明,自 2024 年 11 月 21 日起在全球所有語言與國家的搜尋結果移除這個元素,並移除 Search Console 的對應複合式結果報表;相關說明文件也已於 2024 年 11 月下架(見 Google Search Central 文件更新紀錄)。現在加上 SearchAction 已不會讓 Google 顯示任何搜尋框。

Google Search Central 部落格 2024 年 10 月 21 日公告〈Farewell, Sitelinks Search Box〉,說明自 2024 年 11 月 21 日起移除網站連結搜尋框(截圖來源:Google Search Central Blog)

既有網站已經放了 SearchAction 也不必急著刪:公告指出這類不再支援的結構化資料不會在搜尋中造成問題,也不會在 Search Console 報表觸發錯誤。要注意的是,Google 網站名稱(Site names)功能仍使用 WebSite 結構化資料,若要清理舊標記,只移除 potentialAction,保留 WebSite 本身。

依網站名稱文件,WebSite 結構化資料要放在網站首頁,必要屬性是 name(網站名稱)與 url(首頁的標準網址)。JSON-LD 一樣要包在 <script type="application/ld+json"> 標籤內:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "範例技術筆記",
  "url": "https://example.com/"
}
</script>

也就是說,站內搜尋的無障礙語意交給 <search> 地標處理;結構化資料這一側,目前對 Google 仍有作用的是用來指定網站名稱的 WebSite,而不是 SearchAction。


五、總結與官方規範參考文獻

回顧 HTML search 標籤(<search>)的實務要點:

  1. 明確角色映射:<search> 原生映射為 role="search" 地標(而非 region),內部 <form> 切勿再重複加上 role="search"。
  2. 支援無 <form> 動態過濾:除了傳統表單提交外,SPA 的純前端即時篩選器(Filtering)同樣適用 <search>,並建議搭配 role="status"(aria-live="polite")即時播報篩選結果數量。
  3. 精煉多地標命名:單頁有多個 <search> 時必加 aria-label,且字串內避開「搜尋」二字以防重複朗讀。

下一篇筆記我們將進入 HTML Form 表單控制項系列,深入探討 <label> 的 for 屬性、隱式與顯式關聯差異,以及擴大點擊熱區的無障礙最佳實踐。

官方權威參考文獻

參考資料與延伸閱讀

發佈留言