instantsearch

InstantSearch

使用 InstantSearch 构建可用于生产环境的高质量搜索体验。请按顺序遵循以下工作流。不要跳过任何步骤。

支持的库

InstantSearch 提供三个库。根据项目的依赖项或框架判断适用的库，或询问用户。

库	包	适用场景
React InstantSearch	react-instantsearch	React、Next.js、Remix
Vue InstantSearch	vue-instantsearch	Vue、Nuxt
InstantSearch.js	instantsearch.js	Vanilla JS，或没有专用库的任何框架

确定库后，针对所有技术规则、反模式、样式、术语表和特定模式的指导，请使用对应的参考目录（例如 references/react/）。

注意： 各库的覆盖范围：

• React InstantSearch：全面覆盖（自动补全、搜索结果页面、自定义组件、中间件、SSR）。
• Vue InstantSearch 和 InstantSearch.js：仅覆盖库级规则和自动补全。对于其他模式，请遵循事实来源检查，并在搭建复杂流程前询问用户。

工作流

1. 了解情况

编写任何代码之前，先收集背景信息。首先检查代码库中是否已配置 InstantSearch（搜索客户端、提供程序、现有组件）。如果已配置，请阅读现有配置，而不要再次询问。

如果是从头开始，请逐步进行，每一步都等待用户回答后再继续。

• 凭据：询问用户的 Algolia 应用 ID、仅搜索 API 密钥和索引名称。

• 查询建议：询问用户是否有查询建议索引。

• 架构：获取凭据后，从主索引中提取几条记录，以了解可用属性及其结构。请与用户确认，而不要要求用户列出所有内容。在提出渲染选项之前，需要了解架构。无需从查询建议索引提取数据：其结构是标准的，由组件处理。

  curl -s -X POST \
    "https://${APP_ID}.algolia.net/1/indexes/${INDEX_NAME}/query" \
    -H "x-algolia-api-key: ${API_KEY}" \
    -H "x-algolia-application-id: ${APP_ID}" \
    -H "content-type: application/json" \
    -d '{"params": "hitsPerPage=5"}'
  

• 项目检查：阅读项目现有的样式方案、断点、布局、响应式模式、组件库和框架详情。确定要使用哪个 InstantSearch 库（见上表）。

• 路由：查找详情页的路由模式（例如 /products/[id]、/articles/[slug]），并查找现有的列表页或搜索结果页。如果找到，请确认该页面确实会读取查询参数并呈现动态结果（而不只是静态列表）。如果未找到，或页面是静态的，请询问用户：“提交查询后，搜索应跳转到哪个页面？还是说没有结果页？”

• 放置位置：查找搜索体验应在界面中的位置。请参考该模式的功能参考文档获取指导，或询问用户。

• 渲染方式：向用户提供具体且编号的结果呈现选项。这些选项取决于架构（可用属性）和项目设计。请参考该模式的功能参考文档，了解可提供的选项。

在获得凭据、了解架构和渲染偏好，并熟悉项目设计之前，不要继续。

2. 核对事实来源

此技能仅针对最有价值的模式提供指导。每当你需要使用此技能未明确记录的小组件、钩子、连接器、属性、中间件、未来标志或 API 时，必须先查阅事实来源，再编写代码。训练数据已经过时、信息有损，而且经常会弄错属性的结构。

请按照该库的事实来源参考文档，使用准确的命令和 URL 模式：

库	参考文档
React	source-of-truth.md
Vue	source-of-truth.md
JS	source-of-truth.md

参考文档始终按以下顺序涵盖这些内容：

1. 读取 node_modules 中已安装的类型，了解属性结构、renderState 和连接器契约。
2. 通过规范 URL 模式获取 Algolia 的最新文档。
3. 在已安装的 CSS / 源代码中搜索你打算设置样式的类名。
4. **然后才编写代码。**如果某一步失败（离线、404、缺少类型），请先询问用户，不要猜测。

即使存在模式参考，只要你需要使用其中未明确涵盖的属性或行为，也要执行上述步骤。

3. 构建

根据库和用户的请求，选择匹配的模式参考。如果用户所需内容没有对应的模式参考，请回退到事实来源核对（第 2 步），并在搭建推测性的小组件树之前询问用户。

各库可用的模式：

模式	React	Vue	JS
自动补全	功能、样式、反模式	功能、样式、反模式	功能、样式、反模式
搜索结果页（包括分面搜索、排序、分页）	功能、样式、反模式	—	—
另请阅读并应用库级参考资料（无论使用哪种模式，均适用）：

参考资料	React	Vue	JS
技术规则	technology-rules.md	technology-rules.md	technology-rules.md
反模式	anti-patterns.md	anti-patterns.md	anti-patterns.md
样式	styling.md	styling.md	styling.md
术语表	glossary.md	glossary.md	glossary.md
信息来源	source-of-truth.md	source-of-truth.md	source-of-truth.md
自定义组件	custom-widgets.md	—	—
中间件	middleware.md	—	—
SSR	ssr.md	—	—
模式	React	Vue	JS
------------------------------------------------------------	------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------	---	---
自动补全	features, styling, anti-patterns	—	—
搜索结果页（包括分面搜索、排序、分页）	features, styling, anti-patterns	—	—

另请阅读并应用库级参考资料（无论使用哪种模式，均适用）：

参考资料	React	Vue	JS
技术规则	technology-rules.md	—	—
反模式	anti-patterns.md	—	—
样式	styling.md	—	—
术语表	glossary.md	—	—
事实来源	source-of-truth.md	—	—
自定义小部件	custom-widgets.md	—	—
中间件	middleware.md	—	—
SSR	ssr.md	—	—

请先查阅类型和实时文档（步骤 2）。只有两者都无法解决时，才询问用户。切勿退回使用旧版库或猜测 API。

4. 样式

逐步遵循库的样式指南，然后应用特定模式的样式指南。与网站现有的 CSS 方法、配色方案、排版、间距和组件模式保持一致。

5. 审查

根据库的反模式、特定模式的反模式和功能检查清单审查你的工作。修复所有违规之处。