# @hanzo/observe 中文文档

规范地址：https://npmcn.com/package/%40hanzo/observe/

版本：0\.1\.17
npm 元数据更新时间：2026-10-30T16:57:51.331Z
中文译文更新时间：2026-11-17T08:27:03.201Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hanzo/observe
原文对照：https://npmcn.com/package/%40hanzo/observe/?lang=original
源码仓库：https://github.com/hanzoai/ui

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

- 包体积（解压后）：709 kB，50 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=19\.2\.8
- 首次发布：2026-07-23T05:58:20.901Z
- 最新版本发布：2026-10-30T16:57:51.139Z
- 近 30 天下载量：13682（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

韩佐央视-默认互动抓取回放. 监视树对面的每次点击/输入/导航/可视性,每个注释都有语义等级(组件路径/角色/数据-测试d/aria)自动取自DOM,并通过@hanz发布

## 安装

```sh
npm install @hanzo/observe
```

也可以使用：`pnpm add @hanzo/observe`、`yarn add @hanzo/observe`、`bun add @hanzo/observe`

## README

# @hanzo/观察

React 默认的交互抓取, 在顶端 [`@hanzo/event`](https://npmcn.com/package/%40hanzo/event)。 。 。 .

挂载一个提供者,每次点击、输入、导航和(opt-in)可见度都是 被俘——每个 **带有语义等级的注释** 自动从 树 (组件路径 / 角色 / `data-testid` /可访问名称)——并排放 结束 `@hanzo/event` 到一个切入点`POST /v1/event`) 隐私 (输入编辑)和默认的故障软. 实时事件- 串接电源 复出会话.

> ### 多数应用程序不应该直接挂载此程序 .
> 
> 这是ENGINE。 接通一个应用程序挂载的就是它的供应商—— `<Hanzo analytics>` 从 `@hanzo/ui`,或 `<TelemetryProvider/>` 从 `@hanzogui/telemetry` 都为你启动这个引擎 并征得同意 已解决,客户端已建。 正在挂载 `<ObserveProvider/>` 还有 并不是升级,而是第二台发动机,直到0.1.7,每台发动机翻了一倍 事件(见 [一个根,一个引擎](https://npmcn.com/package/%40hanzo/observe/#readme-one-root-one-engine)) (中文(简体) ).
> 
> 当您正在建造其中一条线时, 请联系下面的提供者, 或 把引擎放在一个没有到达的地方.

```tsx
'use client'
import { AnalyticsProvider } from '@hanzo/event/react'
import { ObserveProvider } from '@hanzo/observe/react'

export function Root({ children }) {
  return (
    <AnalyticsProvider config={{ product: 'console' }}>
      <ObserveProvider>{children}</ObserveProvider>
    </AnalyticsProvider>
  )
}
```

现在每一次互动都以预留方式到达管子上 属性为:

```jsonc
{
  "$el": "Dashboard/UserCard/button[save]",   // the significant-node trail
  "$role": "button",
  "$testid": "save",
  "$component": "SaveButton",
  "$path": ["Dashboard", "UserCard", "button[save]"],
  "$href": "/pricing",                        // the link it follows
  "$id": "save",                              // the target's own id
  "$section": "plans"                         // the section of the page it sits in
}
```

## 活动

| 活动 | 何时 | 注释以外的属性 |
| --- | --- | --- |
| `$click` | 每次点击 | 位置 (下方),当一个指针按住时 |
| `$rageclick` | 倒数第 1 s 和 30 平方厘米内的第 三 个按; 一旦爆破 | 职位 |
| `$input` | a 字段按键键,每个字段被卸下(400ms) | `$value` (编) |
| `$change` | 已解决的字段 | `$value` (编) |
| `$submit` | 提交的表格 |  |
| `$view` | (单位:千美元) `[data-hz-view]` 元素的一分之一被看到,或者它所看到的东西覆盖了一半的取景口(因此仍然可以看到一个高于两个取景口的取景口); 每分元素一次; 元素安装于 `start()` 包含。 当引擎启动时,一个完全在视图上方的部分,在引擎顶部重新打开的一页上(没有碎片,没有重新装入或退入/退出),在看到它之前被滚动过:然后报告它 `passed: true` 没有 `ratio` | `ratio`,或 `passed` |
| `$scroll` | 文档滚动到其高度的25、50、75和100%,每页浏览一次 | `depth`, (中文(简体) ), `$page_width`, (中文(简体) ), `$page_height`, (中文(简体) ), `$viewport_width`, (中文(简体) ), `$viewport_height` |
| `$pageview` | sPA 导航,当 `nav` 开始 | `path` |
| `$pageleave` | 页面视图的约定时间, 以片段表示: 当页面被隐藏、卸下、 路由远离, 或引擎停止时 | 下级 |

每个事件都附有注释(注:`$el`, (中文(简体) ), `$role`, (中文(简体) ), `$path`,以及 `$testid`, (中文(简体) ), `$name`, (中文(简体) ), `$component`, (中文(简体) ), `$kind` 当目标有他们的时候,当目标有他们的时候, 发生地点:

-   **`$href`** - 最亲近的 `a[href]`,目标或祖先:在 此来源, 来源 + 路径名在另一个路径, 赤子方案( o)`mailto:`, (中文(简体) ), `tel:`(中文(简体) ) 用于非 http(s) 的 。 从不问,从不问片段.
-   **`$id`** - 目标自己的身份.
-   **`$section`** - 最亲近的 `section[id]` 或者说 `[data-hz-view]`页:1 `data-hz-view` 值,否则其id.

每个角色最多只有256个, 而不是被剪过.

**职位**打开 `$click` 财务报告和审定财务报表 `$rageclick`,就是热图的取自:

| 密钥 | 数值 |
| --- | --- |
| `$x`, (中文(简体) ), `$y` | 页面坐标中的指针(固定或粘性目标的视图口坐标) |
| `$target_fixed` | 页面滚动时目标是否保留 |
| `$el_x`, (中文(简体) ), `$el_y` | 目标盒子内左上方的指针 |
| `$viewport_width`, (中文(简体) ), `$viewport_height` | 它被测量的窗口 |
| `$page_width`, (中文(简体) ), `$page_height` | 文档 `scrollWidth` 编号 : `scrollHeight` |

皆入圆相. 点击时不按指针——键盘活化, `el.click()`,转发到其字段的标签(`detail === 0`——无载, 永远不要考虑愤怒的点击.

卷轴深度是从一个被动的听众 仅读取, 并请求在页面视图达到每个里程碑后不设置帧。 一个新的 地址再次启动里程碑 `nav` 打开或关闭;页面上方是 不是卷轴,所以一个路由器 放置下一页 报告什么。 只有一个 引擎打开 `document` 测量它.

## 订婚时间

`$pageleave` 说一个页面视图能容纳游客多久. **活动** 时间是 时间,文档可见,窗口有焦点, 访客做到了 (指针、钥匙、车轮、触摸、卷轴)`IDLE_MS`因此,一个 选项卡在一夜之间打开,不读作一页上的8小时.

视图报告 **部分**: 当页面被隐藏时( 电话的最后一刻) 可靠地运行脚本,当它被卸下时,当路由器离开时,当 发动机停止。 一种只用它添加的内容来回报道的观点, 而未添加任何内容的片段,则未发送. **页面视图上的时间是 合计 `$active_ms` 超过 `$view_id`**;没有计算两次。 一个部分是 在其测量的页面下存档(该事件为 `url`编号 :`path`,而不是地址为 路由器已经移动到 。 绑定物发送隐藏或卸载的页面 由信标一时段.

| 密钥 | 数值 |
| --- | --- |
| `$view_id`, (中文(简体) ), `$seq` | 页面视图, 以及该部分在其中的位置( 首先是 0) |
| `$reason` | `hidden`, (中文(简体) ), `pagehide`, (中文(简体) ), `nav` 或者说 `stop` |
| `$active_ms` | 在此段内活动毫秒 |
| `$elapsed_ms` | 视图开始后的墙壁时间( 第一道视图: 自导航开始以来) |
| `$sections` | `{ name: ms }`: 活动时间,每个观看区(`viewSelector`,由 `data-hz-view` 或 id)在这一部分中被 `$view` 规则 |
| `$scroll_max` | 最远的视图被滚动, 以从顶端的 px 为单位( 运行中的最大) |
| `$depth_max` | 显示多少页,百分比 |
| `$page_*`, (中文(简体) ), `$viewport_*` | 所测量的大小 |
| `$ttfb_ms`, (中文(简体) ), `$fcp_ms`, (中文(简体) ), `$lcp_ms`, (中文(简体) ), `$cls`, (中文(简体) ), `$inp_ms` | 页面加载的时间和核心 Web Vitals, 仅在硬装入的视图上, 仅按其状态显示; 一个浏览器, 不按时间省略它 |

只有引擎打开 `document` 措施; `engage: false` 关掉.

## 语义等级

对于元素,一个相互作用的起落,引擎走 DOM 祖先和 将每个步骤描述为 `SemanticNode` —— 说 `tag`,阿里亚 `role` (解释性或 隐含), `testid`,无障碍 `name`,以及 `component`。结果是一个小 JSON-LD文档`@context`, (中文(简体) ), `@type: "Interaction"`, (中文(简体) ), `path`, (中文(简体) ), `target`, (中文(简体) ), `label`(中文(简体) ) 与活动。 因此,点击不是"点击 (x,y)"而是"点击 **保存** 按钮,内部 **用户卡**内部 **盘子** 导航"

元件名称解决最权威的第一,顺序选择如此 船舶时名称不变 :

1.  **`data-hz-name` 编号 : `data-component`** 一个人写的 关于这个节点.
2.  **`data-observe`** - 建造时盖章 `@hanzo/annotate`。 。 。 .
3.  **`data-slot`** ——设计系统设置的元素部分名称 使(使)`button`, (中文(简体) ), `select-trigger`, (中文(简体) ), `dialog-content`) (中文(简体) ). `@hanzo/ui` 邮票 一个在每一个原始 通过一个帮助者, 和阴影做同样,所以 a 整个组成部分图书馆的功能是没有按站点编号的.
4.  **最近的名为 React 的纤维拥有者** - 更富(`SaveButton`没有 `button`),但只发展:生产建设条 `_debugOwner` 财务报告和审定财务报表 简化名字 排队 _下级_ `data-slot` 故意的 一个名字 在部署时蒸发 静静地空出仪表板.

无论胜负如何,节点都会保留其限定词: `card/button[Save]`没有 `card/ button`。一个组件名称 说它是什么, 一个库使 各有数百.

## 一个根,一个引擎

引擎安装 **授权** 根上收听器( e)`document`通常情况下) 两个运行的引擎在一个根上 捕获每个交互 **两次** ——和a 双倍点击在下游是无法区分的 与订婚的访客。 这是 不是假设: 应用程序通过遵循两套真实指令获得一个 一次,因为一个库提供者启动一个引擎,而这个 README 曾经告诉 要挂载另一个应用程序 .

自0.1.7起,第一个发动机 `start()` 拥有它的根 并保持它直到它 停止;同一根上一个后期的引擎保持惰性,并说 (单位:千美元)`engine.capturing === false`) (中文(简体) ). 索赔在一页中按 `Symbol.for` 登记册而不是模块范围——本套装的两份副本 在一个捆绑中有两个模块范围,不会看到对方的索赔 完全如此,正是在最有可能发生重复的情况下。 不同的根源 (a) 范围d `Element`附加时 `document`并存的很好.

## 隐私

默认隐私第一:

-   **输入值被扣.** 一个 `$input`编号 :`$change` 活动带有字段 `kind` 和价值 `length`,从不输入文本.
-   **敏感字段总是被编辑** (密码/电子邮件/卡/cvv/指使) / ssn/.)——甚至没有长度.
-   **`data-hz-private`** (或 `data-observe="off"` 编号 : `data-private`在一个元素上或 任何祖先都把整个亚树排除在捕捉之外.

要捕获非敏感文本值( 如搜索框), 通过 `redaction={{ maskInput: false }}` 敏感字段无论怎样都保持编辑.

**同意不在此决定.** 发动机要用 `enabled` 作为值;是否 任何访问者都可以被观察到(全球隐私控制、不跟踪、存储) 横幅选择,一个构建时的 kill switch)是一个地方的一个政策—— 提供者层——它传递答案。 绘制第二个, 部分副本 政策进入引擎是 两人最终如何不同意一个 明确选入.

## 重播会话

```tsx
import { useEventStream } from '@hanzo/observe/react'

function Timeline() {
  const { events, clear } = useEventStream({ limit: 200 })
  return <ol>{events.map((e, i) => <li key={i}>{e.name} → {e.semantic.label}</li>)}</ol>
}
```

`useEventStream` 订阅相同的流 引擎种子; 这是一个滚动, 用于构建实时会话回放UI的记忆窗口.

## 框架不可知核心

这个 `.` 条目没有反应或运输依赖性——它是引擎 注释者 重写者 和流:

```ts
import { observe } from '@hanzo/observe'

const engine = observe((i) => analytics.capture(i.name, { el: i.semantic.label }))
engine.stream.subscribe(render) // live playback
engine.stop()
```

斯维尔特人就是这样`@hanzo/observe-svelte`) 和原产地 (单位:千美元)`@hanzo/observe-native`)适配器更上一层楼.

## 关于构建时组件名称的说明

制作中的可靠部件名称需要一个建构步骤,即邮票 `data-hz-name` 打开已打开的元素( 运行时间已读取) 。 这是JSX/AST代码 从这个运行时间 SDK 中分离工具——是文件记录的后继工具,而不是其中的一部分 这个包裹.

## 许可证

麻省理工学院 — — 见 [利比里亚](https://npmcn.com/package/LICENSE.md)HIP-0137 (中文(简体) )`hanzoai/hips`) (中文(简体) ).

## 常见问题

### @hanzo/observe 是什么？

韩佐央视-默认互动抓取回放\. 监视树对面的每次点击/输入/导航/可视性,每个注释都有语义等级\(组件路径/角色/数据-测试d/aria\)自动取自DOM,并通过@hanz发布

### 如何安装 @hanzo/observe？

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

### @hanzo/observe 支持 TypeScript 吗？

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

### @hanzo/observe 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @hanzo/observe 可以商用吗？

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

### @hanzo/observe 的下载量有多少？

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

### @hanzo/observe 还在维护吗？

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

