示例与扩展

非官方测试版翻译

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

这些示例支持交互操作。点击按钮打开搜索模态框并尝试输入查询。

基本关键词搜索

使用默认配置搭配您的索引凭证即可。适用于典型文档站点、博客以及任何符合 DocSearch 索引规范的网站。

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

---

Ask AI：AI 辅助回答

添加 Algolia AskAI 可获取基于索引内容生成的综合答案。通过 searchParameters 中的 facetFilters、filters、attributesToRetrieve、restrictSearchableAttributes 和 distinct 参数限定 LLM 上下文范围。

<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)

替换默认命中结果标记以适配您的品牌风格和布局。以下是一个自定义组件的最小实现示例。

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 不限于标准文档记录格式。通过 transformItems 可将任意数据结构转换为 DocSearch 所需的内部格式，从而为应用程序、帮助中心、更新日志等自定义内容构建搜索功能。

以下代码片段演示了如何将非标准记录映射到内部格式，支持实时体验：

<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 范围限定：通过 facetFilters、filters、attributesToRetrieve、restrictSearchableAttributes 和 distinct 参数控制 AI 上下文范围，提升答案质量。

• 深度定制：利用 hitComponent、transformItems 和 translations 让 DocSearch 无缝融入任何产品界面。