slimsearch

一个强大的客户端搜索插件，支持自定义索引与全文搜索。

使用方法

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

import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'

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

搜索索引

通过 slimsearch，搜索速度极快，即使在大型站点上也是如此。

默认情况下，插件仅索引标题，文章摘要和你添加的自定义字段。如果你想要索引文章的全部内容，你可以通过设置 indexContent: true 来开启。

为了阻止页面被索引，你可以在 Frontmatter 中设置 search: false。为了程序化地过滤页面，你可以设置 filter 选项。

自定义索引项

无论是主题开发者还是用户，在 Frontmatter 中或者通过 extendsPage 生命周期为页面添加额外数据都是常见的，并且很多情况下你可能希望把这些数据也编入索引。

customFields 选项接受一个数组，其中每一项代表一项自定义搜索索引的配置项。每一个配置项包含两个部分:

• getter: 该自定义项目的获取器。此函数需要接受 page 对象作为参数，并以字符串 (单个)、字符串数组 (多个)、null (该项目缺失) 的形式返回该自定义项目的值。
• formatter: 一个字符串控制项目该如何在自定义搜索结果中显示，其中 $content 会替换成 getter 返回的项目值。如果你在使用多语言，你还可以将其设置为对象，以分别设置每一个语言的显示格式。

---
author: 你的名字
---

Markdown 内容...

import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'

export default {
  plugins: [
    slimsearchPlugin({
      customFields: [
        {
          name: 'author',
          getter: (page) => page.frontmatter.author,
          formatter: '作者：$content',
        },
      ],
    }),
  ],
}

import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  // 我们假定你在使用如下多语言
  locales: {
    '/': {
      lang: 'en-US',
    },
    '/zh/': {
      lang: 'zh-CN',
    },
  },

  plugins: [
    slimsearchPlugin({
      customFields: [
        {
          name: 'updateTime',
          getter: (page) => page.data.git?.updateTime.toLocaleString(),
          formatter: {
            '/': 'Update time: $content',
            '/zh/': '更新时间：$content',
          },
        },
      ],
    }),
  ],
})

配置项

indexContent

• 类型: boolean
• 默认值: false

是否索引内容。

suggestion

• 类型: boolean
• 默认值: false

是否自动提示搜索建议。

customFields

• 类型: CustomFieldOptions[]

  interface CustomFieldOptions {
    /**
     * 自定义项目的获取器
     */
    getter: (page: Page) => string[] | string | null | undefined
  
    /**
     * 展示的内容
     *
     * @description `$content` 会被 `getter` 返回的内容替换
     *
     * @default `$content`
     */
    formatter?: Record<string, string> | string
  }

• 必填: 否

自定义搜索索引项。

hotKeys

• 类型: (KeyOptions | string)[]

  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
  }

• 默认值: [{ key: "k", ctrl: true }, { key: "/", ctrl: true }]

指定热键的 event.key。

当热键被按下时，搜索框的输入框会被聚焦，设置为空数组以禁用热键。

queryHistoryCount

• 类型: number
• 默认值: 5

存储搜索查询词历史的最大数量，可以设置为 0 以禁用。

resultHistoryCount

• 类型: number
• 默认值: 5

存储搜索结果历史的最大数量，可以设置为 0 以禁用。

searchDelay

• 类型: number
• 默认值: 150

结束输入到开始搜索的延时

filter

• 类型: (page: Page) => boolean
• 默认值: () => true

用于过滤页面的函数。

sortStrategy

• 类型: "max" | "total"
• 默认值: "max"

结果排序策略

当有多个匹配的结果时，会按照策略对结果进行排序。max 表示最高分更高的页面会排在前面。total 表示总分更高的页面会排在前面。

worker

• 类型: string
• 默认值: slimsearch.worker.js

输出的 Worker 文件名称

hotReload

• 类型: boolean
• 默认值: 是否使用 --debug 标记

是否在开发服务器中启用实时热重载。

indexOptions

• 类型: SlimSearchIndexOptions

  interface SlimSearchIndexOptions {
    /**
     * 用于对索引字段项进行分词的函数。
     */
    tokenize?: (text: string, fieldName?: string) => string[]
    /**
     * 用于处理或规范索引字段中的术语的函数。
     */
    processTerm?: (term: string) => string[] | string | false | null | undefined
  }

• 必填: 否

创建索引选项。

indexLocaleOptions

• 类型: Record<string, SlimSearchIndexOptions>
• 必填: 否

分语言的创建索引选项，键为语言路径。

locales

• 类型: SlimSearchLocaleConfig

  interface SlimSearchLocaleData {
    /**
     * 搜索框占位符文字
     */
    placeholder: string
  
    /**
     * 搜索文字
     */
    search: string
  
    /**
     * 清除搜索文字
     */
    clear: string
  
    /**
     * 删除当前项目
     */
    remove: string
  
    /**
     * 搜索中文字
     */
    searching: string
  
    /**
     * 取消文字
     */
    cancel: string
  
    /**
     * 默认标题
     */
    defaultTitle: string
  
    /**
     * 选择提示
     */
    select: string
  
    /**
     * 选择提示
     */
    navigate: string
  
    /**
     * 自动补全提示
     */
    autocomplete: string
  
    /**
     * 关闭提示
     */
    exit: string
  
    /**
     * 加载提示
     */
    loading: string
  
    /**
     * 搜索文字历史 标题
     */
    queryHistory: string
  
    /**
     * 搜索结果历史 标题
     */
    resultHistory: string
  
    /**
     * 无搜索历史提示
     */
    emptyHistory: string
  
    /**
     * 无结果提示
     */
    emptyResult: string
  }
  
  interface SlimSearchLocaleConfig {
    [localePath: string]: Partial<SlimSearchLocaleData>
  }

• 必填: 否

搜索插件的多语言配置。

Frontmatter

search

• 类型：boolean
• 默认值：true

是否索引该页面。

高级

自定义索引生成

如果你正在索引其他不使用“单词”的语言，如中文、日语或韩语，你应该设置 indexOptions 和 indexLocaleOptions 以执行正确的分词。

如果你正在构建中文文档，则可以使用 nodejs-jieba 进行分词。 (日语和韩语没有内置词典，但你可以提供自己的词典，并使用 nodejs-jieba 拆分单词)。

如果你的文档只包含中文，你可以像这样对内容进行标记：

import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'
import { cut } from 'nodejs-jieba'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  lang: 'zh-CN',

  plugins: [
    slimsearchPlugin({
      // 索引全部内容
      indexContent: true,
      indexOptions: {
        // 使用 nodejs-jieba 进行分词
        tokenize: (text, fieldName) =>
          fieldName === 'id' ? [text] : cut(text, true),
      },
    }),
  ],
})

如果你需要在某些语言环境中进行分词，你可以设置 indexLocaleOptions:

import { slimsearchPlugin } from '@vuepress/plugin-slimsearch'
import { cut } from 'nodejs-jieba'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  locales: {
    '/': {
      lang: 'en-US',
    },
    '/zh/': {
      lang: 'zh-CN',
    },
  },

  plugins: [
    slimsearchPlugin({
      indexContent: true,
      indexLocaleOptions: {
        '/zh/': {
          // 使用 nodejs-jieba 进行分词
          tokenize: (text, fieldName) =>
            fieldName === 'id' ? [text] : cut(text, true),
        },
      },
    }),
  ],
})

通过 API 使用

如果你想要访问搜索 API，你可以从 @vuepress/plugin-slimsearch/client 中导入 createSearchWorker 来获取搜索结果:

import { createSearchWorker } from '@vuepress/plugin-slimsearch/client'

const { all, suggest, search, terminate } = createSearchWorker()

// 自动建议
suggest('key').then((suggestions) => {
  // 显示建议
})

// 搜索
search('keyword').then((results) => {
  // 显示搜索结果
})

// 同时返回建议和搜索结果
all('key').then(({ suggestions, results }) => {
  // 显示建议和搜索结果
})

// 当不需要时终止 Worker
terminate()

开发服务器中的限制

搜索服务由 Worker 提供支持，在开发模式下我们无法捆绑 Worker 文件。

为了在开发模式下加载搜索索引，我们使用了带有 type: "module" 的现代 Worker。因此，如果你想尝试在开发服务器中搜索，你应该使用支持的浏览器，请参阅 CanIUse 了解支持详情。

为了更好的性能，在开发模式下添加/编辑/删除 Markdown 内容不会触发搜索索引的更新。如果你正在校对或优化你的搜索结果，你可以通过设置 hotReload: true 选项来启用热重载。

与服务端搜索比较

客户端搜索有优点，比如没有后台服务，容易添加，但你应该知道它也有缺点。

在大多数情况，如果你在构建一个大型站点，你应该选择服务提供商为你的站点提供搜索服务，例如 Algolia，或者选择开源工具在自己的服务器上加载搜索服务并定期为自己的网站生成索引。对于大型站点这很必要因为用户通过网络请求向搜索 API 发送搜索字词，并直接得到搜索结果。

特别提示，DocSearch 是 Algolia 为开源项目提供的免费搜索服务。如果你在创建开源项目文档或开源技术博客，你可 申请它，并使用 @vuepress/plugin-docsearch 插件提供搜索。

客户端配置

defineSearchConfig

自定义 搜索选项，接受普通对象，Ref 或 Getter。

由于搜索是在 Web Worker 中完成的，因此不支持 slimsearch 中需要被设置为函数的选项。

为了提供更准确的搜索查询、建议和结果，我们额外提供了 querySplitter suggestionsFilter 和 resultsFilter 选项，你可以为特定或所有语言设定它们：

interface SearchLocaleOptions
  extends Omit<
    SearchOptions,
    'boostDocument' | 'fields' | 'filter' | 'processTerm' | 'tokenize'
  > {
  /** 分词器 */
  querySplitter?: (query: string) => Promise<string[]>

  /** 过滤建议 */
  suggestionsFilter?: (
    suggestions: string[],
    query: string,
    locale: string,
    pageData: PageData,
  ) => string[]

  /** 过滤结果 */
  resultsFilter?: (
    results: SearchResult[],
    query: string,
    locale: string,
    pageData: PageData,
  ) => SearchResult[]
}

interface SearchOptions extends SearchLocaleOptions {
  /** 基于每个语言来设置选项 */
  locales?: Record<string, SearchLocaleOptions>
}

export const defineSearchConfig: (
  options: MaybeRefOrGetter<SearchOptions>,
) => void

import { defineSearchConfig } from '@vuepress/plugin-slimsearch/client'

defineSearchConfig({
  // 此处放置搜索选项

  locales: {
    '/zh/': {
      // 为特定语言设置搜索选项
    },
  },
})

组件

• SearchBox