# @domscribe/runtime 中文文档

规范地址：https://npmcn.com/package/%40domscribe/runtime/

版本：0\.7\.0
npm 元数据更新时间：2026-10-27T19:41:59.935Z
中文译文更新时间：2026-11-12T15:50:38.743Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40domscribe/runtime
原文对照：https://npmcn.com/package/%40domscribe/runtime/?lang=original
项目主页：https://github.com/patchorbit/domscribe#readme
源码仓库：https://github.com/patchorbit/domscribe

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

- 包体积（解压后）：181 kB，74 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-03-18T01:16:46.927Z
- 最新版本发布：2026-10-27T19:41:59.100Z
- 近 30 天下载量：140690（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

DOMLIS 浏览器侧运行时上下文抓取

## 安装

```sh
npm install @domscribe/runtime
```

也可以使用：`pnpm add @domscribe/runtime`、`yarn add @domscribe/runtime`、`bun add @domscribe/runtime`

## README

# @ domains/ 运行时间

Domlis的浏览器边上下文捕捉引擎.

`@domscribe/runtime` 当开发者点击一个元素时,在浏览器中运行并捕获组件道具,状态和DOM上下文. 它的核心是框架不可知性——适应者提供具体框架的行为.

## 安装

```bash
npm install @domscribe/runtime
```

## 框架支助

| 框架 | 适配器 | 捕获战略 |
| --- | --- | --- |
| 反应 18-19 | `@domscribe/react` | 纤维行走, DevTools 钩子, 最佳努力 |
| 第3组 | `@domscribe/vue` | VNode 检查, 组成 + 选项 API |
| 下一个.js 15-16 | `@domscribe/next` | 反应适配器 + `withDomscribe()` 配置包装 |
| 纳克特 3+ | `@domscribe/nuxt` | Vue 适配器 + 自动配置 Nuxt 模块 |

对于大多数项目,您会安装一个框架适配器,而不是 `@domscribe/runtime` 直接说 适配器声明 `@domscribe/runtime` 作为同伴的依赖和处理初始化.

## 运行时间管理器

`RuntimeManager` 是管理活性适配器的单通,向覆被和其他内部消费者提供捕获API.

```ts
import { RuntimeManager } from '@domscribe/runtime';

const runtime = RuntimeManager.getInstance();
await runtime.initialize({
  adapter: myAdapter,
  phase: 1,
  debug: false,
  redactPII: true,
  blockSelectors: [],
});
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `adapter` | `FrameworkAdapter` | `NoopAdapter` | 用于上下文捕捉的框架适配器 |
| `phase` | `1 | 2` | `1` | 地物相相门. 第一阶段:道具和状态捕捉. 第2阶段:事件流量和业绩衡量标准(未来). |
| `debug` | `boolean` | `false` | 启用调试日志 |
| `redactPII` | `boolean` | `true` | 在捕获的数据中编辑敏感值(电子邮件、信使) |
| `blockSelectors` | `string[]` | `[]` | CSS 元素在捕获时跳过的选择器 |
| `serialization` | `SerializationConstraints` | `undefined` | 捕获道具和状态的序列限制(见下文) |

`initialize()` 能够安全地拨打多次——后续使用相同配置的呼叫是无操作的.

## 序列限制

运行时间对组件道具进行序列化,并有限制状态,以防止有效载荷尺寸过大. 所有字段都是可选的——默认由序列器应用.

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `maxDepth` | `6` (道具), `4` (状态) | 最大对象横向深度 |
| `maxArrayLength` | `20` | 切换前的最大数组元素 |
| `maxStringLength` | `2048` | 切换前的最大字符串长度 |
| `maxProperties` | `50` | 每个对象的最大属性 |
| `maxTotalBytes` | `262144` (256KB) (韩语) | 整个序列化产出的近似字节预算 |

当超过限制时,序列器会插入人可读的哨兵(`[Max Depth Exceeded]`, (中文(简体) ), `[Truncated: size limit]`)和截取元数据(`{ __truncated: true, originalLength: N }`)所以特工们可以看到被省略的内容.

这些制约因素可通过下列途径对每个项目进行配置: `serialization` 选项 `RuntimeOptions`,所有框架适配器插件都通过它们的 `runtime` 名称空间.

## Framewapter 接口

适应者执行 `FrameworkAdapter` 接口将运行时间连接到特定框架的内部组件模型.

```ts
interface FrameworkAdapter {
  readonly name: string;
  readonly version?: string;
  getComponentInstance(element: HTMLElement): Nullable<unknown>;
  captureProps(component: unknown): Nullable<Record<string, unknown>>;
  captureState(component: unknown): Nullable<Record<string, unknown>>;
  getComponentName?(component: unknown): Nullable<string>;
  getComponentTree?(component: unknown): Nullable<ComponentTreeNode>;
  getSerializationHints?(): SerializationHints;
}
```

### 串行提示

适应器可以执行 `getSerializationHints()` 以声明哪些对象键是框架内部,在序列化过程中应当跳过。 这使得框架管道(如回放纤维树,Vue反应标记)无法消耗字节预算.

```ts
interface SerializationHints {
  skipKeys?: Set<string>; // Exact keys to omit (e.g., '_owner')
  skipKeyPrefixes?: string[]; // Prefixes to omit (e.g., '__react' catches '__reactFiber$xyz')
}
```

反应适配器跳过 `_owner`, (中文(简体) ), `_store`,还有所有 `__react*` 键。 Vue 适配器跳过 `__v_*` 反应内相. 这个 `NoopAdapter` 返回不提示 —— 所有密钥都是序列化的 .

见 [自定义适配器指南](https://npmcn.com/package/%40domscribe/runtime/CUSTOM_ADAPTERS.md) 用于完整的接口、实例和整合指示.

## 链接

部分 [多写](https://github.com/patchorbit/domscribe)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @domscribe/runtime 是什么？

DOMLIS 浏览器侧运行时上下文抓取

### 如何安装 @domscribe/runtime？

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

### @domscribe/runtime 支持 TypeScript 吗？

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

### @domscribe/runtime 支持 ESM 还是 CommonJS？

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

### @domscribe/runtime 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @domscribe/runtime 可以商用吗？

@domscribe/runtime 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @domscribe/runtime 的下载量有多少？

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

### @domscribe/runtime 还在维护吗？

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