搜索

VitePress 支持使用 Algolia DocSearch 搜索你的文档站点。请参阅他们的入门指南。在你的 .vitepress/config.js 中，你至少需要提供以下内容才能使其工作：

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...'
      }
    }
  }
}

Algolia 搜索

当使用 Algolia 搜索时，你可以引用 Algolia DocSearch 的文档 了解更多配置选项。

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        locales: {
          zh: {
            placeholder: '搜索文档',
            translations: {
              button: {
                buttonText: '搜索文档',
                buttonAriaLabel: '搜索文档'
              },
              modal: {
                searchBox: {
                  resetButtonTitle: '清除查询条件',
                  resetButtonAriaLabel: '清除查询条件',
                  cancelButtonText: '取消',
                  cancelButtonAriaLabel: '取消'
                },
                startScreen: {
                  recentSearchesTitle: '搜索历史',
                  noRecentSearchesText: '没有搜索历史',
                  saveRecentSearchButtonTitle: '保存至搜索历史',
                  removeRecentSearchButtonTitle: '从搜索历史中移除',
                  favoriteSearchesTitle: '收藏',
                  removeFavoriteSearchButtonTitle: '从收藏中移除'
                },
                errorScreen: {
                  titleText: '无法获取结果',
                  helpText: '你可能需要检查你的网络连接'
                },
                footer: {
                  selectText: '选择',
                  navigateText: '切换',
                  closeText: '关闭',
                  searchByText: '搜索提供者'
                },
                noResultsScreen: {
                  noResultsText: '无法找到相关结果',
                  suggestedQueryText: '你可以尝试查询',
                  reportMissingResultsText: '你认为该查询应该有结果？',
                  reportMissingResultsLinkText: '点击反馈'
                }
              }
            }
          }
        }
      }
    }
  }
}

i18n

你可以使用如下配置来使用多语言搜索：

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        locales: {
          root: {
            placeholder: 'Search docs',
            translations: {
              button: {
                buttonText: 'Search docs',
                buttonAriaLabel: 'Search docs'
              },
              modal: {
                searchBox: {
                  resetButtonTitle: 'Clear search criteria',
                  resetButtonAriaLabel: 'Clear search criteria',
                  cancelButtonText: 'Cancel',
                  cancelButtonAriaLabel: 'Cancel'
                },
                startScreen: {
                  recentSearchesTitle: 'Recent searches',
                  noRecentSearchesText: 'No recent searches',
                  saveRecentSearchButtonTitle: 'Save this search',
                  removeRecentSearchButtonTitle: 'Remove this search from history',
                  favoriteSearchesTitle: 'Favorites',
                  removeFavoriteSearchButtonTitle: 'Remove this search from favorites'
                },
                errorScreen: {
                  titleText: 'Unable to fetch results',
                  helpText: 'You might want to check your network connection.'
                },
                footer: {
                  selectText: 'to select',
                  navigateText: 'to navigate',
                  closeText: 'to close',
                  searchByText: 'Search by'
                },
                noResultsScreen: {
                  noResultsText: 'No results for',
                  suggestedQueryText: 'Try searching for',
                  reportMissingResultsText: 'Believe this query should return results?',
                  reportMissingResultsLinkText: 'Let us know.'
                }
              }
            }
          },
          zh: {
            placeholder: '搜索文档',
            translations: {
              // 省略，与上面相同
            }
          }
        }
      }
    }
  }
}

本地搜索

VitePress 支持使用浏览器内索引进行模糊全文搜索，这要归功于 minisearch。要启用此功能，只需在 .vitepress/config.js 文件中将 themeConfig.search.provider 选项设置为 'local'：

export default {
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
}

示例配置：

export default {
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        locales: {
          zh: {
            translations: {
              button: {
                buttonText: '搜索文档',
                buttonAriaLabel: '搜索文档'
              },
              modal: {
                noResultsText: '无法找到相关结果',
                resetButtonTitle: '清除查询条件',
                footer: {
                  selectText: '选择',
                  navigateText: '切换'
                }
              }
            }
          }
        }
      }
    }
  }
}

i18n

你可以使用如下配置来使用多语言搜索：

export default {
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        locales: {
          root: {
            translations: {
              button: {
                buttonText: 'Search docs',
                buttonAriaLabel: 'Search docs'
              },
              modal: {
                noResultsText: 'No results for',
                resetButtonTitle: 'Clear search criteria',
                footer: {
                  selectText: 'to select',
                  navigateText: 'to navigate',
                  closeText: 'to close'
                }
              }
            }
          },
          zh: {
            translations: {
              button: {
                buttonText: '搜索文档',
                buttonAriaLabel: '搜索文档'
              },
              modal: {
                noResultsText: '无法找到相关结果',
                resetButtonTitle: '清除查询条件',
                footer: {
                  selectText: '选择',
                  navigateText: '切换',
                  closeText: '关闭'
                }
              }
            }
          }
        }
      }
    }
  }
}

类型定义

export interface AlgoliaSearchOptions extends DocSearchProps {
  locales?: Record<string, Partial<DocSearchProps>>
}

export interface LocalSearchOptions {
  locales?: Record<string, Partial<LocalSearchTranslations>>
  miniSearch?: Options
  /**
   * @default
   * /[s-.]+/
   */
  separator?: string
}

export interface LocalSearchTranslations {
  button?: ButtonTranslations
  modal?: ModalTranslations
}

export interface ButtonTranslations {
  buttonText?: string
  buttonAriaLabel?: string
}

export interface ModalTranslations {
  noResultsText?: string
  resetButtonTitle?: string
  footer?: FooterTranslations
}

export interface FooterTranslations {
  selectText?: string
  navigateText?: string
  closeText?: string
}