# @blockcast/multicast-contract 中文文档

规范地址：https://npmcn.com/package/%40blockcast/multicast-contract/

版本：1\.0\.0
npm 元数据更新时间：2026-10-13T01:00:07.001Z
中文译文更新时间：2026-11-08T07:16:01.937Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40blockcast/multicast-contract
原文对照：https://npmcn.com/package/%40blockcast/multicast-contract/?lang=original
项目主页：https://github.com/Blockcast/beacon/tree/main/packages/multicast-contract#readme
源码仓库：https://github.com/Blockcast/beacon

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

- 包体积（解压后）：116 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-09-19T21:44:40.456Z
- 最新版本发布：2026-10-13T01:00:06.640Z
- 近 30 天下载量：2152（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

循环断叶包 持有被冻结的v1窗口. 多播合同,其只读准备表面,以及可执行兼容套件. 零运行时间依赖性通过设计.

## 安装

```sh
npm install @blockcast/multicast-contract
```

也可以使用：`pnpm add @blockcast/multicast-contract`、`yarn add @blockcast/multicast-contract`、`bun add @blockcast/multicast-contract`

## README

# `@blockcast/multicast-contract`

冰冻的V1 `window.multicast` 合同,其只读状态表面,以及 可执行兼容套件.

零运行时间依赖,故意. 此软件包是导入的汇 DAG,它阻止了 犬科全球宣言被拉入 一个包循环。 在此增加一个依赖性,特别是: `@blockcast/shared` 或者说 `@blockcast/transport` —— 重新创建此软件包存在的循环以打破和 将未发布的软件包拖入公共表面。 CI声称依赖性 设置保持为空.

## 一页看

```ts
import type { MulticastGateway, Subscription } from '@blockcast/multicast-contract';

// Feature-detect the GLOBAL, never its methods. The global is genuinely absent
// when no provider is installed; every member is required once it exists.
if (!window.multicast) throw new Error('no multicast provider installed');

const subscription = await window.multicast.subscribe({
  group: '232.0.0.99',   // IPv4 (IGMPv3) or IPv6 (MLDv2) literal
  port: 9876,
  source: '198.51.100.1', // omit for any-source multicast
  consume: 'bytes',
});

subscription.addEventListener('bytes', (event) => {
  // event.detail is an ArrayBuffer, always.
  decode(event.detail);
});
subscription.addEventListener('transportchange', (event) => {
  // 'native' | 'amt' — fires on every resolution, including failover.
  reportLeg(event.detail);
});

await subscription.unsubscribe();
```

### 有五样东西会咬你

1.  **比较错误代码, 永远不要 `instanceof`。 。 。 .** 提供人跳是 JSON系列化,没有结构化克隆,所以 `Error` 子类丢失 中转中原型链. 使用 `multicastErrorCodeOf(err)`。 。 。 .
2.  **`not-ready` 继续其事业 `err.readiness`代码里没有.** 那边 是一个 `not-ready` 成员,不是每个原因一个:十向原因生活在 `Readiness` 记录`err.readiness.code`),这是相同的词汇 `evaluateReadiness` 返回。 因此,"不允许"读作 `err.code === 'not-ready' && err.readiness?.code === 'network-permission-denied'`, (中文(简体) ), 故意与 `network-permission-required` - 那个 首先需要用户推翻拒绝,第二需要一个提示 尚未显示 . `err.readiness` 实值 `undefined` 提供商预定时间 此字段; 这意味着 **不详**永远 _准备_说明 `origin-not-trusted` 是一个单独的拒绝(页面来源,而不是OS本地网络访问),并且是 完全没有准备的密码.
3.  **随函附上 `bytes` 听者迅速.** 最多 `EARLY_BYTES_RETENTION_LIMIT` (128) 在第一个有效载荷之前保留 随从听受. 溢出时 _整个_ 前缀被删除——故意, 因为重放一个部分前缀,然后恢复现场发送会 编织出一条跨越真正不连续的无间隙流.
4.  **`origin` 要求每个非成员参加.** 一个装入的配置 `relay`编号 :`relayPort` 但是没有 `origin: 'amt'` 匹配遗留的 IP 多播 换成成员。 TypeScript 拒绝; plain JavaScript 默地倒回 本土多播并忽略了接力.
5.  **一个可选的能力字段,即 `undefined` 表示 _不详_没有 _无_。 。 。 .** 提供者先于地. 将缺席视为"无" 禁用实际有效的运输工具.

## 准备情况

`evaluateReadiness` 纯粹是呼叫者提供观测的功能。 这个 报告; 它从不提示、 给予或打开窗口 关于已部署的系统,一个网关呼叫自动打开 a 供应商窗口,所以一个自我测试的准备状态 API会弹出一个窗口仅用于 被问到一个问题.

```ts
import { evaluateReadiness } from '@blockcast/multicast-contract';

const readiness = evaluateReadiness(observation);
if (!readiness.ready) console.warn(readiness.code, readiness.detail);
```

3个区分,结果类型分开,每个区分都向 崩溃时错误修正 :

-   `provider-unobservable` 对 `provider-absent` - 供应商检测是一种 火和遗忘探测器,没有内置的超时,所以在最后期限之前 相克相克,沉默不是判决.
-   `udp-bind-unverified` 对 `udp-bind-failed` ——提供方只尝试绑定 一旦两个许可,所以 `udpBind` 是三态和 `null` 表示 _未尝试_。 。 。 .
-   `network-permission-required` 对 `network-permission-denied` - 一个 `unsupported` 权限名称不是拒绝。 铬为它取名 不执行,本地网络名称在不同的 拼写.

`iwa-not-installed` 财务报告和审定财务报表 `iwa-extension-disconnected` 门 **扩展 仅指地形**键入 `extensionResponded === true`。两个现场提供者 不对称:扩展安装 `window.multicast` 时间 `document_start` 对IWA一无所知 然后通过IWA接通所有电话 global 的存在证明什么也没有; 桥式多填充安装 global 只有在连接之后, 所以存在已经意味着一个活桥和它 绝对不会说扩展。 测量两个地貌 将报告一个 健康的多填充后页为断开.

权威授权名称是 `local-network` 财务报告和审定财务报表 `loopback-network`。 。 。 . 年长者 `local-network-access` 别名报告 `denied` 健康系统 仅提供信息;以 `describeLegacyPermissionAlias`。 。 。 .

位置是可选的和外部订阅语义的. `evaluateReadiness` 从来没有咨询过它,和 `runConformanceSuite` 在每次跑道上标出分隔线 通过驱动独立 `location-outside-readiness-suite` 检查,哪个 扫描每个备战代码一个观察.

## 遵约

```ts
import { runConformanceSuite } from '@blockcast/multicast-contract/conformance';

const report = await runConformanceSuite(driver);
if (!report.conformant) console.error(report.checks.filter((c) => c.status !== 'pass'));
```

对照一个 `ConformanceDriver`,不反对浏览器,所以一个 “符合者”的定义涵盖浏览器提供者、参考假名和 iOS/Android适配器. 忽略可选控制钩的驱动程序使 需要它报告的检查 `skipped` - 和 **跳过检查从不通过**数字 : `report.conformant` 虚伪而无所观察.

`FakeMulticastProvider` 是一个符合参考标准的模拟提供者。 用这个 而不是手卷另一个 `window.multicast` stub; 它可以调用字节 通过与真正的运输相同的基数64跳, 所以消费者测试通过 反之亦能活过序列边界.

```ts
import { runConformanceSuite } from '@blockcast/multicast-contract/conformance';
import { FakeMulticastProvider } from '@blockcast/multicast-contract/fake-gateway';

const report = await runConformanceSuite(new FakeMulticastProvider());
```

## 图标

```bash
npm run typecheck   # tsc --noEmit
npm test            # node --test, no install of anything beyond typescript
npm run build       # emits dist/ with declarations
```

## 正在同时安装 `@blockcast/mmt-transport`

`@blockcast/mmt-transport` 自有船只 `declare global` 块 `Window.multicast`键入 `WindowMulticastGateway`此软件包已声明 相同的全球范围 `MulticastGateway` - 唯一能说明问题的宣言 两者在 一个TypeScript程序是宣告-相接冲突.

对照 `@blockcast/mmt-transport` 0.2.0、0.2.1和0.2.2(每个稳定 在TypeScript 5.9.3上发布至今):

| 您的代码 | `skipLibCheck: false` | `skipLibCheck: true` |
| --- | --- | --- |
| 读取 `window.multicast`; 此软件包首先导入 | `TS2717` | 干净 |
| 读取 `window.multicast`· ; `mmt-transport` 首次导入 | `TS2717` + 键 `TS2322` | **`TS2322`,在自己的文件中** |
| 从不命名全局——使用 `getGateway()` | `TS2717` | 干净 |

二事随顺.

**`TS2717` 在安装两个软件包时是不可避免的.** 据报 在一个依赖的 `.d.ts`和平常一样 `skipLibCheck: true` 压制之. 它不影响发射.

**`TS2322` 是可避免的,而且不依赖进口订单来避免.** 哪个 声明胜出 合并由整个模块加载顺序决定 程序,不是通过一个文件的导入列表,所以今天干净的构建可以中断 当添加一个无关的文件时。 相反,从不命名全局类型:使用 `getGateway()` 编号 : `hasGateway()` 从 `@blockcast/multicast-browser`,哪个 返回时 `MulticastGateway | null`。 。 。 .

```ts
import { getGateway } from '@blockcast/multicast-browser';

const gateway = getGateway();       // MulticastGateway | null
if (gateway) await gateway.subscribe(config);
```

没有 `@blockcast/*` 软件包取决于 `mmt-transport`因此它到达了你的树 只有你自己安装它——没有过渡路径.

## 常见问题

### @blockcast/multicast-contract 是什么？

循环断叶包 持有被冻结的v1窗口\. 多播合同,其只读准备表面,以及可执行兼容套件\. 零运行时间依赖性通过设计\.

### 如何安装 @blockcast/multicast-contract？

在项目目录运行 npm install @blockcast/multicast-contract，或使用 pnpm add / yarn add / bun add。

### @blockcast/multicast-contract 支持 TypeScript 吗？

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

### @blockcast/multicast-contract 支持 ESM 还是 CommonJS？

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

### @blockcast/multicast-contract 可以商用吗？

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

### @blockcast/multicast-contract 的下载量有多少？

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

### @blockcast/multicast-contract 还在维护吗？

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