# @contentauth/c2pa-web 中文文档

规范地址：https://npmcn.com/package/%40contentauth/c2pa-web/

版本：0\.16\.0
npm 元数据更新时间：2026-11-04T22:14:22.262Z
中文译文更新时间：2026-11-10T16:35:23.269Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：21.3 MB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-08-30T08:10:38.296Z
- 最新版本发布：2026-11-04T22:14:21.918Z
- 近 30 天下载量：310230（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 45 个）

## 中文简介

用于互动的 SDK [C2PA 元数据](https://c2pa.org/) 在网络上.

## 安装

```sh
npm install @contentauth/c2pa-web
```

也可以使用：`pnpm add @contentauth/c2pa-web`、`yarn add @contentauth/c2pa-web`、`bun add @contentauth/c2pa-web`

## README

# c2pa-网络

用于互动的 SDK [C2PA 元数据](https://c2pa.org/) 在网络上.

作为一个指导思想, `c2pa-web` b. 努力严格遵循由《公约》设立的API模式 [`c2pa-rs`](https://github.com/contentauth/c2pa-rs)。 。 。 .

## 安装

```sh
npm install @contentauth/c2pa-web
```

## 文档

这个 [已版本的网络 API 文档](https://contentauth.github.io/c2pa-js/web/) 与 TypeDoc 一起从已出版的版本中声明生成 `@contentauth/c2pa-web`,包括主要和 `/inline` 进入点. 使用版本选择器来切换发行. 现有 [多包源文档](https://contentauth.github.io/c2pa-js/) 现保留.

关于文件构建和版本列表维护,见 [构建 API 文档](https://github.com/contentauth/c2pa-js/tree/main/docs/project-contributions.md#building-api-documentation)。 。 。 .

## 导入库

应付 [具体要求](https://developer.mozilla.org/en-US/docs/WebAssembly/Guides/Loading_and_running) 用于处理 Wasm 模块,有两种方法导入库:

-   使用单独的瓦斯姆二进制,提供更好的性能.
-   使用内含的瓦斯姆二进制,更方便.

### 使用单独的 Wasm 二进制

建议导入库的方法是在运行时从网络取取瓦斯姆二进制. 这需要Wasm二进制单独托管.

使用适合工具的解决方案;例如,使用Vite:

```typescript
import { createC2pa } from '@contentauth/c2pa-web';

import wasmSrc from '@contentauth/c2pa-web/resources/c2pa.wasm?url';

const c2pa = createC2pa({ wasmSrc });
```

或者,您可以从 CDN 中请求二进制 :

```typescript
import { createC2pa } from '@contentauth/c2pa-web';

// Ensure that [PACKAGE VERSION] matches the currently-installed version of @contentauth/c2pa-web.
const c2pa = await createC2pa({
  wasmSrc:
    'https://cdn.jsdelivr.net/npm/@contentauth/c2pa-web@[PACKAGE VERSION]/dist/resources/c2pa_bg.wasm'
});
```

### 使用内置的瓦斯二进制

如果无法或不方便在网络上请求单独的资源,请使用 `@contentauth/c2pa-web/inline` 软件包,该软件包将Wasm 二进制编码为JavaScript文件中的基础64字符串.

使用此软件包不需要额外的网络请求 。 然而,它补充说 _显著_ 大小到 JavaScript 捆绑, 无法利用更高性能 [`WebAssembly.compileStreaming()`](https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/JavaScript_interface/compileStreaming_static) API (英语).

```typescript
import { createC2pa } from '@contentauth/c2pa-web/inline';

const c2pa = await createC2pa();
```

## 配置行为 `Context`

`createC2pa` 设置工人和瓦斯姆二进制; `Reader` 财务报告和审定财务报表 `Builder`创建方法每个都接受可选 `Context` (见 [`c2pa-utilities`读取](https://npmcn.com/package/%40contentauth/c2pa-utilities/README.md#context-and-settings) 因此,同一个运行的工人可以创造尽可能多的 `Reader`编号`Builder`按需要,每个配置独立:

```typescript
import { createC2pa, Reader, Builder, Context } from '@contentauth/c2pa-web';

import wasmSrc from '@contentauth/c2pa-web/resources/c2pa.wasm?url';

const c2pa = await createC2pa({ wasmSrc });

const context = new Context({
  verify: {
    verifyTrust: true
  },
  trust: {
    trustAnchors: 'https://example.com/trust-anchors.pem'
  }
});

const reader = await Reader.fromBlob(c2pa, blob.type, blob, context);
const builder = await Builder.new(c2pa, context);

// A second Reader can use a completely different Context on the same c2pa instance.
// No need to call createC2pa() again just to change settings.
const reader2 = await Reader.fromBlob(
  c2pa,
  blob2.type,
  blob2,
  new Context({ verify: { verifyTrust: false } })
);
```

每个 `Context` 持有任何单一 `Settings` 对象被传递到其构建器,不处理任何设置的合并。 合并多个 `Settings` 源代码,先将它们合并到 `mergeSettings()`,然后构造一个 `Context` 从单,合并的结果。 见 [`c2pa-utilities`读取](https://npmcn.com/package/%40contentauth/c2pa-utilities/README.md#combining-settings) 详细情况.

A 类 `Context`'设置在创建时解决一次,然后被回忆起来再使用. 通过同样的 `Context` 实例到多个 `Reader`编号 :`Builder` 电话不会在每通电话上重调信任锁定的URL.

### 工厂 API(折旧)

早先的版本 `c2pa-web` 一次通过 SDK 配置 `createC2pa({ settings })`,并创建 `Reader`编号 :`Builder` 对象通过 `c2pa.reader`编号 :`c2pa.builder` 工厂方法 `Settings` 每个调用对象, 在这些顶级设置上合并。 这一点仍然得到支持,但被贬为赞成 `Reader`编号 :`Builder`带有清晰的静态方法 `Context`,并将在未来的版本中删除:

```typescript
const c2pa = await createC2pa({ wasmSrc, settings: { verify: { verifyTrust: true } } });

// Settings passed here are merged over, and take precedence over, the top-level settings above.
const reader = await c2pa.reader.fromBlob(blob.type, blob, {
  trust: { trustAnchors: 'https://example.com/trust-anchors.pem' }
});
const builder = await c2pa.builder.new();
```

## 使用图书馆

另见 [已版本的 API 参考文件](https://contentauth.github.io/c2pa-js/web/)。 。 。 .

### 阅读 C2PA 列表

获取图像并提供给 `Reader`数字 :

```typescript
import { Reader } from '@contentauth/c2pa-web';

const response = await fetch(
  'https://spec.c2pa.org/public-testfiles/image/jpeg/adobe-20220124-C.jpg'
);
const blob = await response.blob();

const reader = await Reader.fromBlob(c2pa, blob.type, blob);

const manifestStore = await reader.manifestStore();

console.log(manifestStore);

// Free SDK objects when they are no longer needed to avoid memory leaks.
await reader.free();
```

`Reader.fromBlob` 拒绝大于1GB的资产,丢弃 `AssetTooLargeError`。 。 。 . `Reader.fromBlobFragment` 拒绝任何碎片大于1GB的资产,同时投掷 `AssetTooLargeError`。 。 。 .

> \[尖叫声\] `Reader.fromBlob`是因为 `format` 参数(通常为 `blob.type`)是可选的。 如果省略或为空,则原生库会倒回从资产字节中检测出格式. **这不是一个需要依靠的特征.** 总是供应 `format` 当它被称作"以字节为基础的检测"时,因为比起直接的找寻速度要慢并可能不可靠,这在后期可能会被表出为更混乱的错误. 只有在呼叫者无法确定资产格式时才省略. `Reader.fromBlobFragment` 编辑 `Builder` API总是需要一种明确的格式.

### 含有成分的建筑C2PA清单

使用 `Builder` API创建C2PA显示并添加成份(源资产)来记录出处链.

#### 设置构建者意图

建造者意图说明在资产上进行的作业类型。 这影响到清单的结构以及自动增加的断言。 使用其中一项意图:

-   `create`:表示资产是新的数字创建,a `DigitalSourceType` 需要时间。 清单中不得有母成分。 A 类 `c2pa.created` 如果不提供,将添加动作.
-   `edit`:表示该资产是对已存在母资产的编辑. 清单必须有母成分。 如果不另行提供,则从源流中生成母成分。 A 类 `c2pa.opened` 动作将被绑定在母成分上.
-   `update`: 限制版本 `edit` 非编辑改动。 作为父母,一定只有一个成分。 无法更改父方的散列内容 。 对可以作出的改变的类型还有额外的限制.

```typescript
import { Builder } from '@contentauth/c2pa-web';

const builder = await Builder.new(c2pa);

await builder.setIntent({
  create:
    'http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia'
});

await builder.setIntent('edit');

await builder.setIntent('update');
```

这个 `create` 意图接受一个 `DigitalSourceType` 说明资产的来源。 共同价值包括:

-   `'http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia'` - AI生成的内容
-   `'http://cv.iptc.org/newscodes/digitalsourcetype/digitalCapture'` - 数码相机捕获
-   `'http://cv.iptc.org/newscodes/digitalsourcetype/composite'` - 多种来源的综合

数字源类型完整列表,参见 [C2PA 规格](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_digital_source_type) 财务报告和审定财务报表 [IPTC 数字源类型词汇](https://cv.iptc.org/newscodes/digitalsourcetype)。 。 。 .

关于建造者意图的更详细情况,见 [c2pa-rs 构建器文档](https://docs.rs/c2pa/latest/c2pa/struct.Builder.html)。 。 。 .

#### 从 blobs 添加成分

当您有机会获得该成分资产时,请使用 `addIngredientFromBlob` 包括元数据和资产数据:

```typescript
// Fetch or load the ingredient asset
const ingredientResponse = await fetch('path/to/source-image.jpg');
const ingredientBlob = await ingredientResponse.blob();

// Create a builder
const builder = await Builder.new(c2pa);

// Add the ingredient with its blob
await builder.addIngredientFromBlob(
  {
    title: 'source-image.jpg',
    format: 'image/jpeg',
    instance_id: 'ingredient-123',
    relationship: 'parentOf'
  },
  'image/jpeg', // Format
  ingredientBlob // The actual asset bytes
);

const definition = await builder.getDefinition();
console.log(definition.ingredients); // Contains the ingredient with embedded data

await builder.free();
```

#### 添加多种成分

您可以在文档复合出处链中添加多个成分 :

```typescript
const builder = await Builder.new(c2pa);

// Fetch ingredient assets
const background = await fetch('background.jpg').then((r) => r.blob());
const overlay = await fetch('overlay.png').then((r) => r.blob());

// Add first ingredient
await builder.addIngredientFromBlob(
  {
    title: 'background.jpg',
    format: 'image/jpeg',
    instance_id: 'background-001',
    relationship: 'componentOf'
  },
  'image/jpeg',
  background
);

// Add second ingredient
await builder.addIngredientFromBlob(
  {
    title: 'overlay.png',
    format: 'image/png',
    instance_id: 'overlay-002',
    relationship: 'componentOf'
  },
  'image/png',
  overlay
);

const definition = await builder.getDefinition();
console.log(definition.ingredients.length); // 2

await builder.free();
```

#### 创建和再利用构建者档案

使用构建器存档来保存构建器的状态(包括成份)并随后再使用:

```typescript
// Create a builder with ingredients
const builder = await Builder.new(c2pa);

const ingredientBlob = await fetch('source.jpg').then((r) => r.blob());
await builder.addIngredientFromBlob(
  {
    title: 'source.jpg',
    format: 'image/jpeg',
    instance_id: 'source-123'
  },
  'image/jpeg',
  ingredientBlob
);

// Save as an archive
const archive = await builder.toArchive();
await builder.free();

// Later, recreate the builder from the archive
const restoredBuilder = await Builder.fromArchive(c2pa, new Blob([archive]));

// The ingredients are preserved
const definition = await restoredBuilder.getDefinition();
console.log(definition.ingredients); // Contains the ingredient

await restoredBuilder.free();
```

#### 添加归档为元素

A 类 `.c2pa` 归档( 通过 `toArchive`)可以添加成份到另一个使用 `addIngredientFromBlob` 带有格式 `application/c2pa`。如果您想要将前一个建筑商的出处历史作为新明细表的成分,则这样做是有用的.

```typescript
// Step 1: Create a builder and archive it
const originalBuilder = await Builder.new(c2pa);
const archive = await originalBuilder.toArchive();
await originalBuilder.free();

// Step 2: Create a new builder and add the archive as an ingredient
const newBuilder = await Builder.new(c2pa);
await newBuilder.setIntent('edit');

await newBuilder.addIngredientFromBlob(
  {
    title: 'previous-work.c2pa',
    relationship: 'parentOf'
  },
  'application/c2pa', // Format for .c2pa archives
  new Blob([archive])
);

// The archive's provenance is now an ingredient in the new builder
const definition = await newBuilder.getDefinition();
console.log(definition.ingredients); // Contains the archived ingredient

await newBuilder.free();
```

您也可以添加一个 `.c2pa` 从 URL 或文件输入中装入的文件 :

```typescript
// Load a .c2pa archive from a URL
const response = await fetch('path/to/ingredient.c2pa');
const archiveBlob = await response.blob();

const builder = await Builder.new(c2pa);
await builder.setIntent('edit');

await builder.addIngredientFromBlob(
  {
    title: 'ingredient.c2pa',
    relationship: 'parentOf'
  },
  'application/c2pa',
  archiveBlob
);
```

#### 成份属性

这个 `Ingredient` 类型支持一些属性,包括:

-   `title`: 成分的可人读取标题.
-   `format`: 成分资产的MIME类型(例如:, `'image/jpeg'`) (中文(简体) ).
-   `instance_id`: 此具体实例的独特标识符.
-   `document_id` (可选):源文档的标识符.
-   `relationship` (可选):与母资产的关系(`'parentOf'`, (中文(简体) ), `'componentOf'`页:1
-   `thumbnail` (可选):成分的缩略语参考.
-   `validation_status` (可选):如果成分有C2PA数据,则验证结果.

完整名单见 [API 参考](https://contentauth.github.io/c2pa-js/interfaces/_contentauth_c2pa-web.index.Ingredient.html)。 。 。 .

## 图书馆发展

关于先决条件,源构建和浏览器测试,见 [向c2pa-web捐款](https://github.com/contentauth/c2pa-js/tree/main/docs/project-contributions.md#contributing-to-c2pa-web)。 。 。 .

## 常见问题

### @contentauth/c2pa-web 是什么？

用于互动的 SDK C2PA 元数据 在网络上\.

### 如何安装 @contentauth/c2pa-web？

在项目目录运行 npm install @contentauth/c2pa-web，或使用 pnpm add / yarn add / bun add。

### @contentauth/c2pa-web 支持 TypeScript 吗？

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

### @contentauth/c2pa-web 支持 ESM 还是 CommonJS？

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

### @contentauth/c2pa-web 可以商用吗？

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

### @contentauth/c2pa-web 的下载量有多少？

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

### @contentauth/c2pa-web 还在维护吗？

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