搜尋回饋 (Search Feedback)

  • 新提案
  • →
  • 封閉測試
  • →
  • 公開測試
  • →
  • 已穩定
成熟度說明
  • 新提案：未完成開發、請勿使用。
  • 封閉測試：開發暫時性完成，可使用。可能仍有親和力或其他使用上問題待透過實測發現。
  • 公開測試：開發暫時性完成，歡迎使用。具有完整親和力報告。
  • 已穩定：開發完成、歡迎使用。應無任何親和力或使用上問題。

搜尋回饋元件提供搜尋狀態的無障礙通知，讓螢幕閱讀器使用者在搜尋過程中能即時得知「搜尋中」、「找到 N 筆結果」、「無結果」或「錯誤」等狀態變化。

元件提供兩種示範：

  • 提交搜尋 — 送出表單、等待伺服器回應後顯示結果。
  • 即時篩選 — 輸入文字時即時過濾頁面上的既有清單。

提交搜尋

搜尋完成後，焦點移至結果標題（data-results-heading），引導使用者前往結果區域。

以下為模擬 4 種搜尋狀態的啟動按鈕
HTML
<div data-search-feedback-demo>
  <form data-search-form novalidate>
    <label for="search-input">搜尋關鍵字</label>
    <span id="search-hint" class="visually-hidden">搜尋後結果將顯示於下方</span>
    <input
      type="search"
      id="search-input"
      name="q"
      placeholder="請輸入關鍵字"
      autocomplete="off"
      aria-describedby="search-hint"
      data-search-input
    >
    <button type="submit">搜尋</button>
  </form>
  <output
    aria-atomic="true"
    class="search-feedback__status"
    id="search-status"
    data-search-status
  ></output>
  <output
    role="alert"
    aria-atomic="true"
    class="search-feedback__status"
    id="search-alert"
    data-search-alert
  ></output>
  <output
    class="search-feedback__status"
    data-results-heading
  ></output>
  <ul aria-label="搜尋結果" data-search-results hidden>
    <li>搜尋結果項目</li>
  </ul>
</div>

即時篩選

每次按鍵觸發篩選，搭配 300ms debounce 避免過於頻繁播報。使用中文輸入法（注音、拼音）時，組字期間不觸發篩選，待選字確定後才執行。

HTML
<div data-live-filter-demo>
  <label for="filter-input">即時篩選</label>
  <span id="filter-hint" class="visually-hidden">結果將隨您輸入即時更新</span>
  <input
    type="search"
    id="filter-input"
    placeholder="輸入關鍵字即時篩選"
    autocomplete="off"
    aria-describedby="filter-hint"
    data-live-filter-input
  >
  <div
    role="status"
    aria-atomic="true"
    class="search-feedback__status"
    id="live-filter-status"
    data-live-filter-status
  ></div>
  <div
    role="alert"
    aria-atomic="true"
    class="search-feedback__status"
    id="live-filter-alert"
    data-live-filter-alert
  ></div>
  <ul aria-label="篩選結果" data-live-filter-list>
    <li data-filter-text="項目一">項目一</li>
    <li data-filter-text="項目二">項目二</li>
    <li data-filter-text="項目三">項目三</li>
  </ul>
</div>

CSS

  • .search-feedback__status：狀態容器，需在初始 HTML 就存在，初始內容為空。
  • .search-feedback__status--loading / --found / --not-found / --error：各狀態 modifier class，由 JS 自動管理。

親和力

  • 狀態容器使用 role="status"（隱含 aria-live="polite"），搜尋結果變動時自動播報。
  • 無結果與錯誤使用 role="alert"（隱含 aria-live="assertive"），立即通知使用者。
  • 宣告文字使用 textContent 插入（含關鍵字時避免 XSS），不使用 innerHTML。

JavaScript

使用 search-feedback.js，提供以下函式：

  • updateStatus(statusEl, state, message) — 更新 role="status" 容器。state 可為 'loading'、'found'、'not-found'、'error' 或 ''（清空）。內部以 100ms 延遲重設文字，確保螢幕閱讀器重複播報相同訊息。
  • updateAlert(alertEl, state, message) — 更新 role="alert" 容器，用於無結果或錯誤等需立即通知的狀態。state 可為 'not-found'、'error' 或 ''。
  • debounce(fn, delay) — 延遲執行函式，避免即時篩選時每次按鍵都觸發播報。

參考