VuePress 生态系统VuePress 生态系统
  • 主题指南
  • 默认主题
  • Hope 主题
  • Plume 主题
  • Reco 主题
  • 功能插件
  • Markdown 插件
  • 搜索插件
  • 博客插件
  • 渐进式应用插件
  • 统计分析插件
  • 搜索引擎优化插件
  • 开发插件
  • 工具插件
  • @vuepress/helper
  • English
  • 简体中文
GitHub
  • 主题指南
  • 默认主题
  • Hope 主题
  • Plume 主题
  • Reco 主题
  • 功能插件
  • Markdown 插件
  • 搜索插件
  • 博客插件
  • 渐进式应用插件
  • 统计分析插件
  • 搜索引擎优化插件
  • 开发插件
  • 工具插件
  • @vuepress/helper
  • English
  • 简体中文
GitHub
  • 搜索插件指南
  • docsearch
  • meilisearch
  • search
  • slimsearch

search

@vuepress/plugin-search

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

使用方法

npm i -D @vuepress/plugin-search@next
.vuepress/config.ts
import { searchPlugin } from '@vuepress/plugin-search'

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

本地搜索索引

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

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

配置项

locales

  • 类型: Record<string, { placeholder?: string }>

  • 详情:

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

  • 示例:

.vuepress/config.ts
export default {
  plugins: [
    searchPlugin({
      locales: {
        '/': {
          placeholder: 'Search',
        },
        '/zh/': {
          placeholder: '搜索',
        },
      },
    }),
  ],
}
  • 参考:
    • 指南 > 多语言支持

hotKeys

  • 类型: (string | KeyOptions)[]

    export interface KeyOptions {
      /**
       * Value of `event.key` to trigger the hot key
       *
       * 热键的 `event.key` 值
       */
      key: string
    
      /**
       * Whether to press `event.altKey` at the same time
       *
       * 是否同时按下 `event.altKey`
       *
       * @default false
       */
      alt?: boolean
    
      /**
       * Whether to press `event.ctrlKey` at the same time
       *
       * 是否同时按下 `event.ctrlKey`
       *
       * @default false
       */
      ctrl?: boolean
    
      /**
       * Whether to press `event.shiftKey` at the same time
       *
       * 是否同时按下 `event.shiftKey`
       *
       * @default false
       */
      shift?: boolean
    
      /**
       * Whether to press `event.metaKey` at the same time
       *
       * 是否同时按下 `event.metaKey`
       *
       * @default false
       */
      meta?: boolean
    }
  • 默认值: ['s', '/']

  • 详情:

    指定热键的 event.key 。

    当按下热键时,搜索框会被聚焦。

    将该配置项设为空数组可以禁用热键功能。

maxSuggestions

  • 类型: number

  • 默认值: 5

  • 详情:

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

isSearchable

  • 类型: (page: Page) => boolean

  • 默认值: () => true

  • 详情:

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

    • 返回 true 来包含该页面。
    • 返回 false 来排除该页面。
  • 示例:

.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-border: var(--vp-c-gutter);
  --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
在 GitHub 上编辑此页
上次更新: 2025/4/12 19:03
贡献者: Mister-Hope
Prev
meilisearch
Next
slimsearch