React 中使用 Algolia docsearch

Algolia 是一家美國的公司，該公司提供一項網路搜尋產品就叫做 Algolia。它是協助搜尋客戶網站中的產品或文章等資訊，不搜尋整個網路世界資訊。就如同我網站內使用 ctrl + k 啟動的搜尋功能，此功能就是來自於該家公司的產品及技術。且相信大家對 Algolia 應該也不陌生，因為常在讀技術文件都會看到它身影，如 React、Vue 及 Tailwind CSS 等官方文件都有使用它，提供開發者快速搜尋想要的技術內容，並解決問題開發問題。

然而，在這篇文章中，會介紹到 React 使用 Algolia docsearch 的方式，雖然還有其他的框架 Vue、Angular 及 Astro 等(前端框架真的是一堆)，但在這邊不會介紹到其它框架使用方式。Algolia 也是一間非常佛系的公司，為什麼這麼說? 因為你的網站是商業運營會收費，非商業運營(如:Blog)則不會收費，這也是為什麼我會選擇他的原因，因為不用錢的最香~

官方文件也說到 Open for all developer documentation and technical blogs.

Key 取得

在實作 algolia 搜尋功能前需要時需要先申請 Key，方便 Algolia 知道使用的是哪個資料。

1. 登入 algolia
2. 新增一個應用程式
3. 輸入 Blog domain
4. 授權 Algolia crawler 爬取自己網站，驗證是否為網站管理者
5. 輸入 Crawler name，之後需要指定為指向資料
6. 取得 API KEY 位置

DocSearch 安裝流程

DocSearch 安裝

pnpm add @docsearch/react@4
# or
npm install @docsearch/react@4

DocSearch 元件

官方提供元件引入範例使用，主要 key 都由上方第六項的 API key 可以取得。

• appId： 值為第六步畫面取得
• includes： 值為第五步 Crawler name 設定的名字，這項參數相當重要，如未傳入也會拋出 Error
• apiKey： 值為第六步畫面取得

import { DocSearch } from '@docsearch/react';

import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      indices="YOUR_INDEX_NAME"
      apiKey="YOUR_SEARCH_API_KEY"
    />
  );
}

export default App;

官方提供快速測試元件

<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indices="docsearch"
  askAi="askAIDemo"
/>

indexName 已棄用

如果有翻過官方文件，它提供範例是傳入 indexName，但在官方的 API Reference 中已經有說明，該參數已棄用，並由 indices 做為未來的參數傳遞。

• includes API Reference 連結
• indexName API Reference 連結

DocSearch 樣式安裝

安裝 @docsearch/css@4 v4 版本樣式，並將樣式引入在 React 的 main.ts 或 Next.js 的 layout.tsx 中使用。

安裝

pnpm add @docsearch/css@4
# or
npm install @docsearch/css@4

使用

import '@docsearch/css';

客製化樣式設定

在官方給的樣式設定中，當然不可能符合每個人網站的色彩風格，如需要客製化樣式，可以將剛剛安裝的 @docsearch/css@4 從 node_modules 中複製出使用。

複製 @docsearch/css 位置

node_modules
└── @docsearch
    └── css
        └── dist
            ├── _variables.css
            ├── button.css
            ├── modal.css
            ├── style.css
            └── style.scss

• _variables.css：docsearch 的樣式變數
• button.css：按鈕樣式檔案，是由拆分出來的檔案
• modal.css：搜尋框樣式檔案，是由拆分出來的檔案
• style.css：此檔案由 style.scss 編譯出的檔案
• style.scss：主要 docsearch 撰寫的樣式

樣式放置專案結構中

筆者開發使用 Tailwind CSS 所以沒有安裝 SCSS，這邊只複製出 _variables.css 及 style.css 兩支檔案，並一起匯入 main.css 檔案，再從外部 globals.css 匯入docsearch 的樣式。如果讀者比較喜歡拆得更細一點可以複製套件原本提供的 button.css 及 modal.css，這樣就不用複製 style.css 檔案。

以下樣式是筆者自己規劃放置的方式，每個人習慣不同，可以依照讀者自己喜歡的方式放置檔案，並且在正確位置引入樣式檔案。

src
└── styles
    ├── docsearch
    │   ├── _variables.css
    │   ├── style.css
    │   └── main.css
    └── globals.css

完成以上的步驟，就可以透過裡面的 CSS 去修改符合自己設計稿樣式及色彩(如果要稍微學過 Bootstrap 的話，整個流程是很相似的)。

DocSearch 文字設定

UI 文字參數-translations

Algolia 預設文字為英文，但可以透過套件提供的元件參數進行修改。以下為筆者為 LoGravel 部落格修改的內容，如需更詳細設定，可參考官方文件的translations。

<DocSearch
  placeholder="搜尋文件"
  translations={{
    button: {
      buttonText: '快速搜尋',
      buttonAriaLabel: 'Search',
    },
    modal: {
      searchBox: {
        clearButtonTitle: '清除',
      },
      startScreen: {
        recentSearchesTitle: '搜尋歷史',
        favoriteSearchesTitle: '收藏',
      },
      noResultsScreen: {
        noResultsText: '無法查到相關搜尋結果:',
      },
      footer: {
        selectText: '選擇',
        navigateText: '切換',
        closeText: '關閉',
        poweredByText: '搜尋供應商',
      },
    },
  }}