Examples and extensions

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

These examples are interactive. Click a button to open the modal and try a query.

基本关键词搜索

Use the default experience with your index credentials. This works great for typical docs, blogs, and any site with a DocSearch-compliant index.

<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="docsearch"
  insights={true}
  translations={{ button: { buttonText: 'keyword search (demo)' } }}
/>

---

Ask AI：AI 辅助回答

Add Algolia Ask AI to get synthesized answers grounded in your indexed content. You can scope the LLM context using searchParameters like facetFilters, filters, attributesToRetrieve,restrictSearchableAttributes, and distinct.

<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="docsearch"
  askAi={{
    assistantId: 'askAIDemo',
    searchParameters: {
      facetFilters: ['language:en'],
    },
  }}
  insights={true}
  translations={{ button: { buttonText: 'search with askai (demo)' } }}
/>

---

侧边栏：持久化 AI 聊天

侧边栏提供固定在页面边缘的持久化聊天界面，特别适合文档类网站——用户可在不离开当前浏览位置的情况下进行追问。点击屏幕右下角的按钮即可体验演示功能。

<DocSearchSidepanel
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="docsearch"
  assistantId="askAIDemo"
/>

---

组合式 API：DocSearchButton + DocSearchModal

通过组合式 API 可将按钮与模态框作为独立组件渲染。您可精确控制各组件的渲染位置以及模态框代码的加载时机。

import { DocSearch } from '@docsearch/core';
import { DocSearchButton, DocSearchModal } from '@docsearch/modal';

import '@docsearch/css/style.css';

<DocSearch>
  <DocSearchButton translations={{ buttonText: 'Composable search (demo)' }} />
  <DocSearchModal
    appId="PMZUYBQDAK"
    indexName="docsearch"
    apiKey="a00716d83c64f6c61905c078b7d5ab66"
    askAi={{
      assistantId: 'ccdec697-e3fe-465b-a1c3-657e7bf18aef',
      agentStudio: true,
    }}
  />
</DocSearch>;

---

自定义命中结果渲染 (hitComponent)

Replace the default hit markup to match your brand and layout. Below is a minimal example of a custom component.

function CustomHit({ hit }) {
  // render a compact, branded hit card
  return (
    <a
      href={hit.url}
      style={{ display: 'block', padding: '12px 16px', textDecoration: 'none' }}
    >
      <div style={{ display: 'flex', gap: 12 }}>
        <div
          style={{
            width: 40,
            height: 40,
            backgroundColor: '#e3f2fd',
            borderRadius: 6,
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
            fontWeight: 600,
            color: '#1976d2',
          }}
        >
          {hit.type?.toUpperCase?.() || 'DOC'}
        </div>
        <div style={{ minWidth: 0 }}>
          <div
            style={{
              fontWeight: 600,
              whiteSpace: 'nowrap',
              overflow: 'hidden',
              textOverflow: 'ellipsis',
            }}
          >
            {hit.hierarchy?.lvl1 || 'untitled'}
          </div>
          {hit.hierarchy?.lvl2 && (
            <div
              style={{
                color: '#666',
                whiteSpace: 'nowrap',
                overflow: 'hidden',
                textOverflow: 'ellipsis',
              }}
            >
              {hit.hierarchy.lvl2}
            </div>
          )}
          {hit.content && (
            <div style={{ color: '#888', marginTop: 4 }}>{hit.content}</div>
          )}
        </div>
      </div>
    </a>
  );
}

<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="docsearch"
  hitComponent={CustomHit}
  insights={true}
  translations={{ button: { buttonText: 'custom hits (demo)' } }}
/>;

---

在新标签页打开链接

默认情况下，DocSearch 在当前窗口打开搜索结果链接。若需在新标签页打开，必须同时使用自定义 hitComponent 和 navigator 属性来统一处理点击与键盘导航。

// Custom hit component with target="_blank"
function HitWithNewTab({ hit, children }) {
  return (
    <a href={hit.url} target="_blank" rel="noopener noreferrer">
      {children}
    </a>
  );
}

// Navigator configuration to handle keyboard navigation
const newTabNavigator = {
  navigate: ({ itemUrl }) => window.open(itemUrl, '_blank'),
  navigateNewTab: ({ itemUrl }) => window.open(itemUrl, '_blank'),
  navigateNewWindow: ({ itemUrl }) => window.open(itemUrl, '_blank'),
};

<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="docsearch"
  hitComponent={HitWithNewTab}
  navigator={newTabNavigator}
  insights={true}
  translations={{ button: { buttonText: 'open in new tabs (demo)' } }}
/>;

警告

注意：仅使用带 target="_blank" 的 hitComponent 可支持鼠标点击，但键盘导航（方向键 + Enter）需配合 navigator 属性才能在新标签页中稳定打开链接。

---

使用 transformItems 自定义数据结构

DocSearch is not limited to DocSearch-like records. Use transformItems to adapt any record shape into the internal structure DocSearch expects. This lets you build search for apps, help centers, changelogs, or any custom content.

The snippet below maps a non-standard record to the internal format. Try it live:

<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="crawler_doc"
  askAi={{ assistantId: 'askAIDemo' }}
  searchParameters={{
    attributesToRetrieve: ['*'],
    attributesToSnippet: ['*'],
    hitsPerPage: 20,
  }}
  transformItems={(items) =>
    items.map((item) => ({
      objectID: item.objectID,
      content: item.content ?? '',
      url: item.domain + item.path,
      hierarchy: {
        lvl0: (item.breadcrumb || []).join(' > ') ?? '',
        lvl1: item.h1 ?? '',
        lvl2: item.h2 ?? '',
        lvl3: null,
        lvl4: null,
        lvl5: null,
        lvl6: null,
      },
      url_without_anchor: item.domain + item.path,
      type: 'content',
      anchor: null,
      _highlightResult: item._highlightResult,
      _snippetResult: item._snippetResult,
    }))
  }
  insights={true}
  translations={{ button: { buttonText: 'transform items (demo)' } }}
/>

---

实用技巧

• 数据监控：启用 insights 发送使用分析数据，持续优化相关性排序。

• Ask AI scoping: use facetFilters, filters, attributesToRetrieve, restrictSearchableAttributes, and distinct to control AI context and improve answer quality.

• Customization: use hitComponent, transformItems, and translations to make DocSearch feel native to any product surface.