下拉菜单行为

非官方测试版翻译

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

注意

以下关于 Autocomplete.js 的引用已过时。如需使用最新版本，请访问 Autocomplete 文档

我们的 JavaScript 库 DocSearch.js 封装了 Algolia autocomplete.js 库。该库监听搜索输入框中的每次按键操作，向 Algolia 发起查询，并在下拉菜单中展示结果。所有配置均已预先完成，可直接用于 DocSearch 工作流。我们的 UI 库还提供了可深度定制的配置选项。您将体验到 Algolia 为文档搜索提供的开箱即用功能，开启边输入边学习的全新体验。

appId

该库通过 appId 参数定义您的专属应用 ID。

docsearch({
  appId: '<YOUR_APP_ID>',
  […],
});

handleSelected

当建议项被选中时（通过点击或按键），此方法将被触发。默认情况下，DocSearch 会显示指向结果页面的锚点链接。您可覆盖结果（也称为命中项）以添加自定义行为。请注意，通过 CMD/CTRL + Click 操作已支持在新标签页打开链接。

该方法接收以下参数：

• input：指向搜索 input 元素的引用，支持 .open()、.close()、.getVal() 和 .setVal() 方法

• event：触发选择操作的实际事件对象

• suggestion：表示当前选中项的对象，包含代表目标地址的 .url 键

• datasetNumber：此值恒为 1（DocSearch 每次仅搜索一个数据集），可忽略此属性

• context：选择操作的附加信息，包含 .selectionMethod 键，其值可能是 click（点击）、enterKey（回车键）、tabKey（Tab键）或 blur（失焦），具体取决于选择方式

docsearch({
  // ...
  handleSelected: function (input, event, suggestion, datasetNumber, context) {
    // Prevents the default behavior on click and rather opens the suggestion
    // in a new tab.
    if (context.selectionMethod === 'click') {
      input.setVal('');

      const windowReference = window.open(suggestion.url, '_blank');
      windowReference.focus();
    }
  },
});

您可在 CodeSandbox 上实时体验。

queryHook

每次按键都会触发此方法，用于在向 Algolia 发起查询前转换输入关键词。默认情况下不执行操作，但您可按需添加自定义逻辑。

docsearch({
  […],
  queryHook: function(query) {
    // Transform query, and then return the updated version
  }
});

transformData

此方法会在每条命中结果显示前触发。默认不执行操作，但您可利用此钩子添加自定义逻辑，预处理 Algolia 返回的命中结果。

docsearch({
  […],
  transformData: function(hits) {
    // Transform the list of hits
  }
});

autocompleteOptions

通过 autocompleteOptions 参数，可向底层 Autocomplete.js 库传递任意配置选项。所有可用值请参阅官方文档。

您还可通过 docsearch 实例的 .autocomplete 属性监听 autocomplete 事件。

const search = docsearch({
  […],
  autocompleteOptions: {
    // See https://github.com/algolia/autocomplete/tree/master#global-options
  }
});

// See https://github.com/algolia/autocomplete/tree/master#custom-events
search.autocomplete.on('autocomplete:opened', event => {
});

algoliaOptions

通过 algoliaOptions 键可向 Algolia API 转发搜索参数。所有 Algolia API 选项请参阅其专属文档。

例如，您可能需要增加下拉菜单显示的结果数量。hitsPerPage 参数用于设置显示结果数。

docsearch({
  algoliaOptions: {
    hitsPerPage: 10,
    // See https://www.algolia.com/doc/api-reference/api-parameters/
  },
});