搜尋列
用法
章節連結:用法搜尋列讓讀者輸入關鍵字,搜尋網站的內容,通常放在頁首或搜尋結果頁的上方。右邊固定有一個放大鏡按鈕,按下它或按 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 圖示。下方為可互動的真實元件:
純 HTML
章節連結:純 HTML<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>React
章節連結:Reactimport { 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。
API
章節連結:API下表自 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` 時使用。 |
無障礙(Accessibility)
章節連結:無障礙(Accessibility)- 外框為
<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)。