search

为你的文档网站提供本地搜索能力。

使用方法

npm i -D @vuepress/plugin-search@next

.vuepress/config.ts
import { searchPlugin } from '@vuepress/plugin-search'

export default {
  plugins: [
    searchPlugin({
      // 配置项
    }),
  ],
}

指南

本地搜索索引

该插件会根据你的页面，在本地生成搜索索引，然后在用户访问站点时加载搜索索引文件。换句话说，这是一个轻量级的内置搜索能力，不会进行任何外部请求。

然而，当你的站点包含大量页面时，搜索索引文件也会变得非常大，它可能会拖慢你的页面加载速度。在这种情况下，我们建议你使用更成熟的解决方案 - docsearch 。

选项

localesLocaleConfig<SearchPluginLocaleData>

默认值{}

搜索框在不同 locales 下的文字。

参考：多语言配置。

locales.<localePath>.placeholderstring

搜索框的占位符文本。

hotKeys(KeyOptions | string)[]

默认值['s', '/']

指定热键的 event.key 。当按下热键时，搜索框会被聚焦。将该配置项设为空数组可以禁用热键功能。

hotKeys[*].key必填string

热键的 event.key 值。

hotKeys[*].ctrlboolean

是否同时按下 event.ctrlKey。

hotKeys[*].shiftboolean

是否同时按下 event.shiftKey。

hotKeys[*].altboolean

是否同时按下 event.altKey。

hotKeys[*].metaboolean

是否同时按下 event.metaKey。

maxSuggestionsnumber

默认值5

指定搜索结果的最大条数。

isSearchable(page: Page) => boolean

默认值() => true

一个函数，用于判断一个页面是否应该被包含在搜索索引中。

.vuepress/config.ts
export default {
  plugins: [
    searchPlugin({
      // 排除首页
      isSearchable: (page) => page.path !== '/',
    }),
  ],
}

getExtraFields(page: Page) => string[]

默认值() => []

一个函数，用于在页面的搜索索引中添加额外字段。

默认情况下，该插件会将页面标题和小标题作为搜索索引。该配置项可以帮助你添加更多的可搜索字段。

.vuepress/config.ts
export default {
  plugins: [
    searchPlugin({
      // 允许搜索 Frontmatter 中的 `tags`
      getExtraFields: (page) => page.frontmatter.tags ?? [],
    }),
  ],
}

样式

你可以通过 CSS 变量来自定义搜索框的样式：

:root {
  --search-c-bg: var(--vp-c-bg);
  --search-c-accent: var(--vp-c-accent);
  --search-c-text: var(--vp-c-text);
  --search-c-divider: var(--vp-c-divider);
  --search-c-item-text: var(--vp-c-text-subtle);
  --search-c-item-focus: var(--vp-c-bg-alt);
  --search-input-width: 8rem;
  --search-result-width: 20rem;
}

组件

SearchBox