# @datadog/framepost 中文文档

规范地址：https://npmcn.com/package/%40datadog/framepost/

版本：0\.4\.1
npm 元数据更新时间：2024-05-07T19:18:13.535Z
中文译文更新时间：2026-11-11T13:29:59.964Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40datadog/framepost
原文对照：https://npmcn.com/package/%40datadog/framepost/?lang=original
项目主页：https://github.com/DataDog/apps/tree/master/packages/framepost
源码仓库：https://github.com/DataDog/apps

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

- 包体积（解压后）：73.6 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2020-10-29T15:47:25.585Z
- 最新版本发布：2024-05-07T19:18:13.371Z
- 近 30 天下载量：46022（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：68（近 12 个月 0 个）

## 中文简介

安全的父母-子女iframe通信

## 安装

```sh
npm install @datadog/framepost
```

也可以使用：`pnpm add @datadog/framepost`、`yarn add @datadog/framepost`、`bun add @datadog/framepost`

## README

# 框架后

FramePost是一个用于亲子iframe通信的库. 它旨在处理安全通信的细节,同时也提供方便用户的API,使iframecommuncation更能感觉使用API. 这通过建立 `channel` 父母与子女之间通过相互握手,然后才能进行任何其他逻辑.

## 父客户端

父母客户端负责与孩子一起初始化频道. 在建立信道时,母程序可能包含任意数据,作为 `context` 在握手过程中被送到儿童手中. _必须在 Iframe 完全装入后进行_。强烈建议该频道在 `onload` 事件:

```
import { ParentClient } from '@datadog/framepost';

const client = new ParentClient();

const frame = document.createElement('iframe');

frame.src = 'https://domain.dom/path/to/frame.html';

const context = {
    infoAboutParent: 'it is a demo',
}

frame.onload = () => {
    client.requestChannel(frame, frame.src, context);
}
```

## 儿童客户端

儿童客户端在初始脚本执行时必须在iframe中初始化. 儿童可提供背景,供父母在儿童成长时握手时参考 `context` 配置选项 .

```
import { ChildClient } from '@datadog/framepost';

const context = {
    infoAboutChild: 'It is a demo'
}

const client = new ChildClient({ context });
```

## 共享 API

初始握手成功后,每个客户端将使用共享API处理与对应方的通信.

### `client.getContext()`数字 :

获取相反客户在握手过程中发送的上下文 :

```
// in parent
const contextFromChild = await client.getContext();

// in child
const contextFromParent = await client.getContext();
```

### `client.on()`

对应方为: `client.send()`。订阅一个事件处理器,从相反客户端执行指定类型的事件。 事件密钥必须是独一无二的 。 返回未订阅的钩子 .

```
const unsubscribe = client.on('route_change', newRouteData => {
    ...
})

// later
unsubscribe();
```

### `client.send()`

对应方为: `client.on()`。向相反客户端发送带有指定事件密钥和数据的事件。 事件密钥必须是独一无二的 :

```
client.send('event_key', dataAboutEvent);
```

### `client.request()`数字 :

对应方为: `client.onRequest()`. 用于同步发送和接收来自相反客户端的数据的方便方法. 被设计成像基于承诺的 api 调用。 为了让往返请求正确运行 `onRequest` 带有匹配请求密钥的处理器必须在启动重排前在相反的客户端中收听. 见下文.

```
const data = await client.request('getMyData', requestParams);

```

### `client.onRequest()`数字 :

对应方为: `client.request()`。接收请求从 a 发送的数据 `client.request` 呼叫相反的客户端。 执行所提供的处理器,将返回的回复发回相反的客户端.

```
client.onRequest('getMyData', async requestParams => {
    const responseData = await doSomeStuff());

    return responseData;
})
```

## 高级

### 调试模式

任一客户端都可以以调试模式初始化 :

```
const parentClient = new ParentClient({ debug: true });
const childClient = new ChildClient({ debug: true });
```

这将打印关于各种事件和错误的调试语句 .

### 剖析

酷特写警报! Framewost 将收集和报告每个频道处理的信息交易的时间安排配置。 为了启用,通过 `profile: true` 给每个客户端的 每个客户端将默默地收集可以在父端请求的数据 `parentClient.getProfile()`数字 :

```
// in child
const childClient = new ChildClient({ proile: true });

// in parent
child parentClient = new ParentClient({ profile: true });

// after channel init and a few transactions:

parentClient.getMessageProfile().then(profile => {
    // do whatever you want with profile data
    console.log(profile);
});

```

## 常见问题

### @datadog/framepost 是什么？

安全的父母-子女iframe通信

### 如何安装 @datadog/framepost？

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

### @datadog/framepost 支持 TypeScript 吗？

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

### @datadog/framepost 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @datadog/framepost 可以商用吗？

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

### @datadog/framepost 的下载量有多少？

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

### @datadog/framepost 还在维护吗？

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