跳到內容
開始使用

搜尋列

表單 Search Bar

搜尋列讓讀者輸入關鍵字,搜尋網站的內容,通常放在頁首或搜尋結果頁的上方。右邊固定有一個放大鏡按鈕,按下它或按 Enter 就開始搜尋;需要讓讀者先選搜尋範圍時,可以在左邊加上分類選單,例如「全部」「書籍」「文章」。如果是表單裡要填的一個欄位,例如姓名或電子郵件,請改用「輸入框」。

部位說明
外框有圓角和框線的一整條。滑鼠移上去或選到時框線變色;選到時外面還多一圈柔光。
分類選單可省略。最左邊的選單,讓讀者先選搜尋範圍。它的寬度有上限,名稱太長會被截掉。
輸入區讀者打字的地方。框內的提示文字同時是螢幕閱讀器唸出的名稱,沒有寫時是「搜尋」。
搜尋鈕最右邊的放大鏡按鈕,按下去開始搜尋;螢幕閱讀器會唸「搜尋」。
停用狀態整條變淡,不能輸入、不能選分類,也不能按搜尋。
類型 說明
建議 提示文字寫出可以搜尋什麼,例如「搜尋文章、活動」。這段文字也是螢幕閱讀器唸出的名稱,請不要留白。
建議 分類名稱保持兩、三個字,例如「全部」「書籍」「文章」。分類選單的寬度有上限,太長的名稱會被截掉。
建議 把搜尋列放在讀者習慣找的位置,例如頁首或搜尋結果頁的上方,整個網站保持一致。
避免 不要在搜尋列旁邊再放一個「搜尋」按鈕;搜尋列已經有自己的放大鏡按鈕。
避免 不要用搜尋列讓讀者填姓名、電話這類資料;請用「輸入框」。

目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題

  • 預設變體: 用元件本身的預設變體。
  • 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
  • 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
  • 和預設主題不同的地方: (以下都是示意值)只有這個元件用到的顏色:主色、品牌底色(滑鼠移上時)、焦點框(用鍵盤選到時的外框)。其餘和預設主題一樣。 看完整的顏色對照

上方的大預覽會跟著頁首的「主題」和「色彩模式」一起變;這個元件還沒有淺色、深色並排的範例。

以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。

Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-search-bar> 的頁面;這一段的範例和 API 表就是它的說明。

<tc-search-bar> 是外框式(outlined)搜尋列,採用白色底、radius.md 圓角與 focus-within 焦點環,視覺與 <tc-input> 一致。版面為 [可選分類選擇器 | 文字輸入框 | 搜尋鈕],搜尋鈕使用內嵌的 search 圖示。下方為可互動的真實元件:

<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" />
<script type="module" src="@tzuchi/components/cdn"></script>
<tc-search-bar name="q" placeholder="搜尋"></tc-search-bar>
import { TcSearchBar } from '@tzuchi/react';
<TcSearchBar
placeholder="搜尋"
onTcSearch={(e) => runSearch(e.detail.value, e.detail.category)}
/>;

加上 with-category 會在前端顯示分類選擇器,選項以 categories(物件陣列 property 或 JSON 字串屬性)提供。切換分類會發出 tc-category-change:

  • 輸入時發出 tc-input,detail: { value }。
  • 按下 Enter 或點擊搜尋鈕發出 tc-search,detail: { value, category }。
  • 切換分類發出 tc-category-change,detail: { category }。

所有事件皆 composed 且 bubbles。

下表自 Custom Elements Manifest 自動產生:

Attribute Type Default Description
value string '' 搜尋字串(反映為屬性)。
placeholder string '搜尋' 未輸入時顯示的提示文字,同時作為輸入框的無障礙標籤。
name string '' 表單欄位名稱(套用至內部 input)。
disabled boolean false 停用:停用內部所有原生控制項(非 pointer-events:none)。
with-category boolean false 顯示前置分類選擇器。
category string '' 目前選取的分類 value(反映為屬性)。
categories TcSearchCategory[] [] 分類選項清單。可由 property 設定物件陣列,或由 HTML/React 以 JSON 字串屬性提供。 僅在 `with-category` 時使用。
  • 外框為 <form role="search">,組成自己的送出流程(非 form-associated)。
  • 文字輸入框以 aria-label(預設取 placeholder)提供無障礙名稱。
  • 搜尋鈕 aria-label="搜尋",分類選擇器 aria-label="搜尋分類"。
  • :focus-within 焦點環使用 border.focus 與柔光環,內部控制項 :focus-visible 使用 --tc-focus-ring-* token。
  • disabled 會停用內部所有原生控制項(非 pointer-events:none)。