> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiIyNjZjMTIyMy1lYmIyLTRiMGYtYWQ2Yy1jNGRmOGUyMTYwNDkiLCJleHAiOjE3NzgyNjY4MDIsImlhdCI6MTc3ODI2NjUwMn0.YrrwnyoehprkzCIlst2Dqb3RhYFuaRklHgKKvWyeYqk
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 独立搜索组件

> 使用 @fern-api/search-widget 包在任何 React 应用程序中嵌入 Fern 的 AI 驱动搜索。

[`@fern-api/search-widget`](https://www.npmjs.com/package/@fern-api/search-widget) 包提供了一个独立的 React 组件，可以将 Ask Fern 的 AI 驱动搜索功能带到您的 Fern Docs 网站之外的任何 React 应用程序中。在您的仪表板、营销网站或内部工具中嵌入搜索模态框，让用户无需离开其工作流程即可找到相关文档。

<Frame caption="嵌入在仪表板中的搜索组件。试用[在线演示](https://fern-demo.github.io/fern-search-widget-demo/)或浏览[演示源码](https://github.com/fern-demo/fern-search-widget-demo)。">
  <video autoPlay muted loop>
    <source src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/5d6b73b949f2e2d73e1a5d28cee18276ef18cf125a7cccb5e2895f59bcc593e1/products/docs/pages/ask-fern/assets/search-widget.mp4" type="video/mp4" />
  </video>
</Frame>

## 前提条件

* **React 19** — 所有其他依赖项都已打包。
* **启用了 [Ask Fern](/learn/docs/ai-features/ask-fern/overview) 的实时云托管 Fern Docs 站点** — 该组件在运行时连接到您已发布的文档站点。不支持自托管和本地预览环境。
* **公开文档** — 该组件仅支持公开文档。如果您的站点使用[身份验证](/learn/docs/authentication/overview)，该组件将仅返回未经身份验证的结果。

## 快速开始

<Steps>
  <Step title="安装包">
    <CodeBlocks>
      ```bash npm
      npm install @fern-api/search-widget react@19 react-dom@19
      ```

      ```bash pnpm
      pnpm add @fern-api/search-widget react@19 react-dom@19
      ```

      ```bash yarn
      yarn add @fern-api/search-widget react@19 react-dom@19
      ```
    </CodeBlocks>

    该包大约为 2 MB（JS + CSS 合计）。
  </Step>

  <Step title="添加搜索模态框">
    导入 `SearchModal` 和打包的样式，然后使用您的文档域名渲染组件。该组件会渲染一个按钮，点击时打开搜索模态框。

    ```tsx
    import { SearchModal } from '@fern-api/search-widget';
    import '@fern-api/search-widget/styles';

    function App() {
      return (
        <SearchModal domain="https://docs.example.com" lang="en">
          搜索文档
        </SearchModal>
      );
    }
    ```
  </Step>

  <Step title="自定义触发按钮">
    `SearchModal` 组件会渲染一个打开搜索模态框的按钮。使用 `className`、`style` 或定位默认的 `fern-search-button` 类来设置样式。所有标准的 HTML 按钮属性都会被转发。

    ```tsx
    <SearchModal
      domain="https://docs.example.com"
      lang="en"
      className="my-search-button"
    >
      搜索文档
    </SearchModal>
    ```

    像 `* { margin: 0; padding: 0; }` 这样的全局 CSS 重置会破坏模态框的内部布局。将全局重置限定范围，排除搜索模态框内的元素。
  </Step>
</Steps>

## 属性

还支持所有标准的 HTML 按钮属性，并转发到触发按钮。

<ParamField path="domain" type="string" required={true}>
  您已发布的 Fern Docs 站点的 URL（例如，`https://docs.example.com`）。如果您的文档不在根目录，请包含完整路径（例如，`https://buildwithfern.com/learn`）。
</ParamField>

<ParamField path="lang" type="string" default="en">
  搜索界面的语言代码。
</ParamField>

<ParamField path="icon" type="React.ReactNode">
  在按钮中显示的图标元素。
</ParamField>

<ParamField path="className" type="string">
  触发按钮的 CSS 类名。
</ParamField>

<ParamField path="style" type="React.CSSProperties">
  触发按钮的内联样式。
</ParamField>

<ParamField path="children" type="React.ReactNode">
  按钮内容（文本、图标等）。
</ParamField>

<ParamField path="disabled" type="boolean">
  禁用按钮。
</ParamField>

<ParamField path="onClick" type="function">
  在模态框打开之前运行的额外点击处理程序。
</ParamField>