# @findlane/browser 中文文档

规范地址：https://npmcn.com/package/%40findlane/browser/

版本：0\.34\.0
npm 元数据更新时间：2026-11-06T01:27:32.191Z
中文译文更新时间：2026-11-14T18:43:10.189Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40findlane/browser
原文对照：https://npmcn.com/package/%40findlane/browser/?lang=original
项目主页：https://findlane.dev/docs/browser-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：259 kB，50 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2026-09-30T14:47:08.248Z
- 最新版本发布：2026-11-06T01:27:31.961Z
- 近 30 天下载量：4751（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

Findlane浏览器SDK:从浏览器中以索引的公用ID进行快速,能耐打字的公开搜索,外加回放钩和组件.

## 安装

```sh
npm install @findlane/browser
```

也可以使用：`pnpm add @findlane/browser`、`yarn add @findlane/browser`、`bun add @findlane/browser`

## README

# @ findlane/ 浏览器

Findlane浏览器SDK:快速地从浏览器中以索引的公用ID进行耐打字搜索. 没有依赖性,大约1KB,加上可选的反应钩和组件.

文档 : [https://findlane.dev/docs/browser-sdk 页面存档备份,存于互联网档案馆](https://findlane.dev/docs/browser-sdk)

## 安装

```sh
npm install @findlane/browser
```

## 快开始

```ts
import { SearchBrowserClient } from "@findlane/browser"

const client = new SearchBrowserClient({ publicId: "pub_your_public_index_id" })
const results = await client.search({ q: "trail shoe", limit: 10, highlight: true })
// results.hits[0].highlights?.title: "Trail <mark>shoe</mark>" (HTML-escaped, safe to insert as HTML)
```

没有构建步骤,就用脚本标记加载,这个标记定义了全局性 `Findlane`数字 :

```html
<script src="https://cdn.findlane.dev/browser/0/findlane.min.js"></script>
<script>
  const client = new Findlane.SearchBrowserClient({ publicId: "pub_your_public_id" })
</script>
```

每个索引在仪表板上都有可复制的公共身份证. 在启用浏览器搜索之前, 拥有者必须保存允许的索引来源 .

## 查询建议

作为访客类型提供的全搜索,以及索引的流行搜索空框. 他们不算是搜查 最近的搜索停留在访客浏览器中 .

```ts
await client.querySuggestions({ q: "hrek" }) // [{ q: "hrekkjavöku búningar", typed: [0, 4] }]
await client.popularSearches() // [{ q: "gríma" }, { q: "latex" }]
client.recentSearches.add("hárkolla")
```

## 反应

`@findlane/browser/react` 设有一个搜索框,建议搜索和结果为访客类型,一个带有过滤器的结果页,以及后面的钩子,用于18.2和19反应. 不导入的页面不加载.

```tsx
import { SearchBox } from "@findlane/browser/react"
import "@findlane/browser/react/styles.css" // optional

<SearchBox publicId="pub_your_public_id" getHref={(hit) => hit.record.url} action="/search"
  querySuggestions={4} popularSearches={6} recentSearches />
```

`SearchDialog` 是一个 & XQK 打开的对话框中的搜索框, 和 Docs 站点上相同 。 一个结果页面通过 `SearchProvider`,与 `RefinementList`, (中文(简体) ), `SortSelect`, (中文(简体) ), `Hits`, (中文(简体) ), `LoadMore`和钩子,例如 `useRefinementList` 财务报告和审定财务报表 `useRange` 为你自己的标记。 与 `routing`,搜索内容保留在 URL 中. `@findlane/browser/react/ssr` 使服务器上的第一个结果。 在产品页面上, `useProductView(objectID)`,或 `<ProductView>` 在服务器组件中,发送索引“事件”页面的页面视图。 文档 : [https://findlane.dev/docs/反应](https://findlane.dev/docs/react)

## 搜索请求

| 选项 |  |
| --- | --- |
| `q` | 腾讯. 单词与打字和前缀相匹配,取决于索引的设置. |
| `filters` | 要保存的字段值:一个值, `{ in: [...] }`区域 `{ gte, lte }` 数字和日期. |
| `facets` | 要计算值的字段, 例如 `["brand.name"]`。 。 。 . |
| `disjunctiveFacets` | Facets在自己字段没有过滤器的情况下计算出,所以一个复选框列表保留了它的其他值. |
| `sort` | 从索引设置中排序 ID,或 `"relevance"`。 。 。 . |
| `limit`, (中文(简体) ), `offset` | 呼号:最多可有50个点击请求,并可以抵消1000个请求. |
| `countMode`, (中文(简体) ), `facetMode` | `"page"` (默认,最快)或 `"exact"` 每次比赛的总和面数. |
| `highlight` | `true` 将匹配的词包入 `<mark>`,或 `{ preTag, postTag }`。 。 。 . |
| `attributesToRetrieve` | 只归还这些地. |

反应是 `hits` (每个单位) `record` 和任何 `highlights`, (中文(简体) ), `total`, (中文(简体) ), `facets`,以及 `tookMs`。通过 `{ signal }` 以作为取消请求的第二个参数,作为搜索现用类型.

## 活动

`client.events` 在背景中发送视图、点击、加码和顺序,用于索引的“事件”页面和“共同购买”。 与 `visitorIds: true`,它们还携带浏览器和访问的随机ID,当索引带走它们时 `client.events.forget()` 删除ID,并要求删除其事件。 文档 : [https://findlane.dev/docs/events 页面存档备份,存于互联网档案馆](https://findlane.dev/docs/events)

## 警卫

公共ID只允许其索引的搜索访问,在浏览器源中可见. 默认情况下, API 返回每个上传的记录字段 . `attributesToRetrieve` 请求减少速度的字段,但它不会使其他字段变得私密。 来源检查会约束浏览器;它们不会认证其他调用者. 做好公共目录栏目安全曝光. 仪表板可以去除来源,添加服务器强制限制,或者旋转ID.

对于登录的人,通过 `signedKey`: 使用 SDK 服务器的短寿命密钥 `signSearchKey`,或获取一个函数。 它的限制取代了索引的公共设置. 见 [登录访问者](https://findlane.dev/docs/security#logged-in-visitors)。 。 。 .

## 错误

请求抛出失败 `FindlaneError` 与 HTTP 连接 `status` 和API的讯息:

-   403:这个来源是不允许的.
-   429:公开搜索率限制.
-   402:工作空间已经使用了它的月搜索.

## 许可证

麻省理工学院

## 常见问题

### @findlane/browser 是什么？

Findlane浏览器SDK:从浏览器中以索引的公用ID进行快速,能耐打字的公开搜索,外加回放钩和组件\.

### 如何安装 @findlane/browser？

在项目目录运行 npm install @findlane/browser，或使用 pnpm add / yarn add / bun add。

### @findlane/browser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @findlane/browser 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @findlane/browser 可以商用吗？

@findlane/browser 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @findlane/browser 的下载量有多少？

根据 npm 官方下载统计，@findlane/browser 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,751 次，日均约 158 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @findlane/browser 还在维护吗？

最新版本 0\.34\.0 发布于 2026/11/06（8 天前）；至今共发布 39 个版本，其中过去 12 个月发布了 39 个；首次发布于 2026/09/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。