@hanzo/observe

中文文档
0.1.17发布于 2026/10/31MITTypeScriptESM + CJS近 30 天下载 1.4万

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

中文使用文档
文档目录10 节
  1. 多数应用程序不应该直接挂载此程序 .
  2. 活动
  3. 订婚时间
  4. 语义等级
  5. 一个根,一个引擎
  6. 隐私
  7. 重播会话
  8. 框架不可知核心
  9. 关于构建时组件名称的说明
  10. 许可证

@hanzo/观察

React 默认的交互抓取, 在顶端 @hanzo/event。 。 。 .

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

多数应用程序不应该直接挂载此程序 .

这是ENGINE。 接通一个应用程序挂载的就是它的供应商—— <Hanzo analytics> 从 @hanzo/ui,或 <TelemetryProvider/> 从 @hanzogui/telemetry 都为你启动这个引擎 并征得同意 已解决,客户端已建。 正在挂载 <ObserveProvider/> 还有 并不是升级,而是第二台发动机,直到0.1.7,每台发动机翻了一倍 事件(见 一个根,一个引擎) (中文(简体) ).

当您正在建造其中一条线时, 请联系下面的提供者, 或 把引擎放在一个没有到达的地方.

'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>
  )
}

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

{
  "$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 平方厘米内的第 三 个按; 一旦爆破职位
$inputa 字段按键键,每个字段被卸下(400ms)$value (编)
$change已解决的字段$value (编)
$submit提交的表格
$view(单位:千美元) [data-hz-view] 元素的一分之一被看到,或者它所看到的东西覆盖了一半的取景口(因此仍然可以看到一个高于两个取景口的取景口); 每分元素一次; 元素安装于 start() 包含。 当引擎启动时,一个完全在视图上方的部分,在引擎顶部重新打开的一页上(没有碎片,没有重新装入或退入/退出),在看到它之前被滚动过:然后报告它 passed: true 没有 ratioratio,或 passed
$scroll文档滚动到其高度的25、50、75和100%,每页浏览一次depth, (中文(简体) ), $page_width, (中文(简体) ), $page_height, (中文(简体) ), $viewport_width, (中文(简体) ), $viewport_height
$pageviewsPA 导航,当 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)
$reasonhidden, (中文(简体) ), 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)是一个地方的一个政策—— 提供者层——它传递答案。 绘制第二个, 部分副本 政策进入引擎是 两人最终如何不同意一个 明确选入.

重播会话

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的记忆窗口.

框架不可知核心

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

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 中分离工具——是文件记录的后继工具,而不是其中的一部分 这个包裹.

许可证

麻省理工学院 — — 见 利比里亚HIP-0137 (中文(简体) )hanzoai/hips) (中文(简体) ).

版本与发布记录

@hanzo/observe 共发布 14 个版本,首次发布于 2026/07/23;过去 12 个月发布了 14 个版本。

版本发布日期距今
0.1.17latest2026/10/3117 天前
0.1.162026/10/3017 天前
0.1.152026/10/3017 天前
0.1.142026/10/3018 天前
0.1.132026/10/3018 天前
0.1.122026/10/2622 天前

关于 @hanzo/observe 的常见问题

@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 和提交记录判断。