# @cardano-sdk/projection 中文文档

规范地址：https://npmcn.com/package/%40cardano-sdk/projection/

版本：0\.13\.21
npm 元数据更新时间：2026-09-25T13:52:56.838Z
中文译文更新时间：2026-11-09T04:24:51.415Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cardano-sdk/projection
原文对照：https://npmcn.com/package/%40cardano-sdk/projection/?lang=original
项目主页：https://github.com/input-output-hk/cardano-js-sdk#readme
源码仓库：https://github.com/input-output-hk/cardano-js-sdk

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

- 包体积（解压后）：711 kB，368 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：10 个
- 首次发布：2022-11-22T21:06:41.979Z
- 最新版本发布：2026-09-25T13:52:56.662Z
- 近 30 天下载量：26988（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：173（近 12 个月 6 个）

## 中文简介

链同步事件投影

## 安装

```sh
npm install @cardano-sdk/projection
```

也可以使用：`pnpm add @cardano-sdk/projection`、`yarn add @cardano-sdk/projection`、`bun add @cardano-sdk/projection`

## README

# Cardano JS SDK 预测

这个软件包是一个通用投影类型和公用事业的库.

> \[TIP\] [事件驱动架构中的预测和阅读模型指南](https://event-driven.io/en/projections_and_read_models_in_event_driven_architecture/)

如果您有兴趣投影到 PostgreSQL 数据库,请查看 [投影类型](https://npmcn.com/package/%40cardano-sdk/projection-typeorm) 软件包.

如果你对莱斯运行的投影仪应用感兴趣,请看 [设置](https://npmcn.com/package/%40cardano-sdk/cardano-services/src/Projection) 财务报告和审定财务报表 [读取](https://npmcn.com/package/%40cardano-sdk/cardano-services/README.md) 内 `cardano-services` 软件包.

## 先决条件

为了了解 `cardano-js-sdk` 首先你需要基本了解:

-   [观察器](https://github.com/tc39/proposal-observable) (我们正在使用 [RxJS 软件](https://rxjs.dev/) 执行)
-   链式同步迷你协议(详细解释如下) [Ogmios 文档](https://ogmios.dev/mini-protocols/local-chain-sync/)(中文(简体) )

## 类型

### 投影事件“ 外部Props”

所有预测从获得来源/制作者开始1个,这是一个 `Observable<ProjectionEvent<{}>>`。这些事件与链同步事件非常相近,但有一些重要的区别:

1.  块格式与类型兼容 `@cardano-sdk/core` 软件包.
2.  事件包括一些额外的属性 : `{eraSumaries, genesisParameters, epochNo, crossEpochBoundary}`。 。 。 .
3.  `RollBackward` 事件包括块数据(而不是仅仅指定回滚点),并且为 **每个** 向后滚动.

#### 外推( 通用参数)

源可观测到的可被管道通过一系列RxJS运算符,这些运算符可能会给事件添加一些属性. 简言之, `ProjectionEvent<T> = ProjectionEvent<{}> & T`。详见 [地图员](https://npmcn.com/package/%40cardano-sdk/projection/#readme-mappers)。 。 。 .

### 稳定窗口

自兹 `ProjectionEvent{eventType=RollBackward}` 包括块数据,我们必须存储一些数字( 至少 `k`,这是最新块的"安全参数",这样如果一个叉子/回滚发生,我们可以调用 `StabilityWindowBuffer.getBlock(hash)` 用于构建有效的 `ProjectionEvent`。 。 。 .

### 可观测卡尔德诺节点

这是我们与卡尔达诺节点的链条同步和本地状态查询协议的接口. 唯一可用的执行 `cardano-js-sdk` 实值 `OgmiosObservableCardanoNode`。 。 。 .

## 公用事业

### 来自卡尔德诺节点的靴子

创建投影源( E)`Observable<ProjectionEvent>`来源:

-   [可观测卡尔德诺节点](https://npmcn.com/package/%40cardano-sdk/projection/#readme-observablecardanonode)
-   [稳定窗口](https://npmcn.com/package/%40cardano-sdk/projection/#readme-stabilitywindowbuffer)
-   `Observable<TipOrOrigin>` 显示上次处理的事件(本地提示)的块头。 这是用来找到相交点的 .

```mermaid
---
title: Bootstrap Algorithm
---
flowchart LR
    subscribe[Subscribe] --> find-intersect{Find node\nintersection\nwith local tip}
    find-intersect --> |Found| start[Start ChainSync\nfrom intersection]
    start --> get-event{Get event\nfrom node,\ncheck type}
    get-event --> |RollBackward| get-block[Get block from StabilityWindowBuffer]
    get-event --> |RollForward| hydrate
    start --> hydrate[Hydrate event\nwith additional\npropertes]
    hydrate --> emit[Emit\nProjectionEvent]
    find-intersect --> |Not Found| get-block[Get block from\nStabilityWindowBuffer]
    get-block --> rollback[Create\nRollBackward\nevent]
    rollback --> hydrate
    rollback --> wait[Wait for\nlocal tip change]
    wait --> is-rollback-point{Is rollback point?}
    is-rollback-point --> |No| get-block
    is-rollback-point --> |Yes| started-sync{Already started\nChain Sync?}
    started-sync --> |Yes| get-event
    started-sync --> |No| find-intersect
```

### 地图员

预测通常是

1.  解释块(如从所有交易中提取出一些相关的属性). `Mappers` 是包含 RxJS 运算符的命名空间,这些运算符处理ProjectionEvent(块)并发出一个具有一些额外属性的新事件对象.
2.  用它做一些事情(例如存储到数据库中).

举个例子:

```typescript
// source$: Observable<ProjectionEvent<{}>>
source$.pipe(
  // policyId is a parameter that should be provided
  // by handle issuer, e.g. ADA Handle
  Mappers.withHandles({ policyId }),
  // type WithHandles = { handles: HandleOwnership; }
  // Event type can also be inferred (no need for explicit type declaration)
  tap((event: ProjectionEvent<WithHandles>) => {
    console.log('Handles found by withHandles operator', event.handles);
  })
);
```

### 其他用户

#### 在记忆中窗口窗口

如果您的应用程序不需要持久性, 您可以使用模拟执行 [稳定窗口](https://npmcn.com/package/%40cardano-sdk/projection/#readme-stabilitywindowbuffer),也可以用作 Bootstrap 的本地提示跟踪器(提供 `Observable<TipOrOrigin>`) (中文(简体) ).

* * *

_1个目前我们观测到的投影源 不是纯粹的“生产者”,因为事件有 `requestNext` 用于控制源的方法。 这一点将来会有所改变._

## 常见问题

### @cardano-sdk/projection 是什么？

链同步事件投影

### 如何安装 @cardano-sdk/projection？

在项目目录运行 npm install @cardano-sdk/projection，或使用 pnpm add / yarn add / bun add。

### @cardano-sdk/projection 支持 TypeScript 吗？

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

### @cardano-sdk/projection 支持 ESM 还是 CommonJS？

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

### @cardano-sdk/projection 需要什么版本的 Node\.js？

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

### @cardano-sdk/projection 可以商用吗？

@cardano-sdk/projection 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cardano-sdk/projection 的下载量有多少？

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

### @cardano-sdk/projection 还在维护吗？

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