# Fumadocs UI (the default theme of Fumadocs): 搜尋 UI
URL: /zh-TW/docs/ui/search
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/search.zh-TW.mdx

用於搜尋文件的 UI

## 概覽 [#overview]

您可以透過 [`<RootProvider />`](/docs/ui/layouts/root-provider) 自訂搜尋 UI。

```tsx title="app/layout.tsx"
import { RootProvider } from 'fumadocs-ui/provider/<framework>';
import type { ReactNode } from 'react';
import { SearchDialog } from '@/components/my-search-dialog';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html>
      <body>
        <RootProvider
          // [!code highlight:4]
          search={{
            enabled: false, // 完全停用搜尋
            SearchDialog, // 替換搜尋對話方塊
          }}
        >
          {children}
        </RootProvider>
      </body>
    </html>
  );
}
```

### 快速鍵 [#hot-keys]

您可以自訂開啟搜尋對話方塊的快速鍵，預設為 <kbd>⌘</kbd> <kbd>K</kbd> 或 <kbd>Ctrl</kbd> <kbd>K</kbd>。

```tsx
import { RootProvider } from 'fumadocs-ui/provider/<framework>';

<RootProvider
  search={{
    hotKey: [
      {
        display: 'K',
        key: 'k', // 按鍵代碼，或用來判斷按鍵是否被按下的函式
      },
    ],
  }}
>
  {children}
</RootProvider>;
```

### 參考資料 [#references]

完整的選項清單。

### SearchProps

| Prop            | Type                                                         | Description                                                                                                                                                                      |
| --------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preload?`      | `boolean \| undefined`                                       | **Deprecated.** Preload search dialog before opening it Default: `` `true` ``                                                                                                    |
| `links?`        | `SearchLink[] \| undefined`                                  | Custom links to be displayed if search is empty                                                                                                                                  |
| `hotKey?`       | `HotKey[] \| undefined`                                      | Hotkeys for triggering search dialog Default: `Meta/Ctrl + K`                                                                                                                    |
| `SearchDialog?` | `React.ComponentType<DefaultSearchDialogProps> \| undefined` | Replace default search dialog, allowing you to use other solutions such as Algolia Search It receives the `open` and `onOpenChange` prop, can be lazy loaded with `React.lazy()` |
| `options?`      | `Partial<DefaultSearchDialogProps> \| undefined`             | Additional props to the dialog                                                                                                                                                   |
| `enabled?`      | `boolean \| undefined`                                       | Enable search functionality Default: `` `true` ``                                                                                                                                |

## 自訂 UI [#custom-ui]

Fumadocs UI 也提供較底層的 `<SearchDialog />` 元件供進階使用，您可以藉此建立自己的搜尋對話方塊，取代預設的版本。

```tsx twoslash
'use client';
import React from 'react';
import { useFetchSearch } from 'fumadocs-core/search/client';
import {
  SearchDialog,
  SearchDialogClose,
  SearchDialogContent,
  SearchDialogHeader,
  SearchDialogFooter,
  SearchDialogIcon,
  SearchDialogInput,
  SearchDialogList,
  SearchDialogOverlay,
  type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useI18n } from 'fumadocs-ui/contexts/i18n';

export default function DefaultSearchDialog(props: SharedProps) {
  const { locale } = useI18n(); // （選用）用於 i18n
  const search = useFetchSearch({
    locale,
  });

  return (
    <SearchDialog {...search} {...props}>
      <SearchDialogOverlay />
      <SearchDialogContent>
        <SearchDialogHeader>
          <SearchDialogIcon />
          <SearchDialogInput />
          <SearchDialogClose />
        </SearchDialogHeader>
        <SearchDialogList />
      </SearchDialogContent>
      <SearchDialogFooter>{/* 頁尾項目 */}</SearchDialogFooter>
    </SearchDialog>
  );
}
```

### 內容算繪器 [#content-renderer]

若想自行算繪搜尋項目的 Markdown 內容，請傳入 `renderMarkdown`。

```tsx title="components/search.tsx"
<SearchDialogList
  // [!code highlight:8]
  Item={(props) => (
    <SearchDialogListItem
      {...props}
      renderMarkdown={(text) => {
        // ...
      }}
    />
  )}
/>
```

### 表格 [#tables]

自訂結果中表格的算繪方式。自訂的 `Table` 會自行算繪各列資料：

```tsx title="components/search.tsx"
<SearchDialogList
  // 不使用卡片，直接顯示各列
  Table={({ table, Item, onSelect }) =>
    table.rows.map((row) => (
      <Fragment key={row.id}>{Item({ item: row, onClick: () => onSelect(row) })}</Fragment>
    ))
  }
/>
```

### 醒目標示 [#highlights]

搜尋關鍵字的符合結果會透過 [CSS Custom Highlight API](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API) 醒目標示，您可以使用 `::highlight(fd-search)` 自訂其樣式。

```css title="global.css"
::highlight(fd-search) {
  color: var(--color-fd-primary-foreground);
  background-color: var(--color-fd-primary);
}
```

`<SearchDialogList />` 會突顯 `<SearchDialog />` 的 `data` 中的查詢字詞；若未提供，則改為突顯搜尋輸入框中的內容。

若您自行算繪搜尋結果，請使用 `useHighlightQuery()` 進行突顯。

```tsx title="components/search-result.tsx"
'use client';
import { useHighlightQuery } from 'fumadocs-core/search/client';
import type { ReactNode } from 'react';

export function SearchResult({ query, children }: { query: string; children: ReactNode }) {
  const ref = useHighlightQuery(query);

  return <div ref={ref}>{children}</div>;
}
```

帶有 `data-highlight-ignore` 屬性的元素，其內部文字不會被突顯，例如元件的徽章。