@contentauth/c2pa-web

中文文档

0.16.0发布于 2026/11/05MITTypeScriptES Module构建来源已验证近 30 天下载 31万

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

文档目录11 节

安装
文档
导入库
使用单独的 Wasm 二进制
使用内置的瓦斯二进制
配置行为 Context
工厂 API(折旧)
使用图书馆
阅读 C2PA 列表
含有成分的建筑C2PA清单
图书馆发展

c2pa-网络

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

作为一个指导思想, c2pa-web b. 努力严格遵循由《公约》设立的API模式 c2pa-rs。。。 .

安装

npm install @contentauth/c2pa-web

文档

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

关于文件构建和版本列表维护,见构建 API 文档。。。 .

导入库

应付具体要求用于处理 Wasm 模块,有两种方法导入库:

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

使用单独的 Wasm 二进制

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

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

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

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

const c2pa = createC2pa({ wasmSrc });

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

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() API (英语).

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

const c2pa = await createC2pa();

配置行为 `Context`

createC2pa 设置工人和瓦斯姆二进制; Reader 财务报告和审定财务报表 Builder创建方法每个都接受可选 Context (见 c2pa-utilities读取因此,同一个运行的工人可以创造尽可能多的 Reader编号Builder按需要,每个配置独立:

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读取详细情况.

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

工厂 API(折旧)

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

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 参考文件。。。 .

阅读 C2PA 列表

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

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 非编辑改动。作为父母,一定只有一个成分。无法更改父方的散列内容。对可以作出的改变的类型还有额外的限制.

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 规格财务报告和审定财务报表 IPTC 数字源类型词汇。。。 .

关于建造者意图的更详细情况,见 c2pa-rs 构建器文档。。。 .

从 blobs 添加成分

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

// 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();

添加多种成分

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

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();

创建和再利用构建者档案

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

// 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。如果您想要将前一个建筑商的出处历史作为新明细表的成分,则这样做是有用的.

// 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 或文件输入中装入的文件 :

// 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 参考。。。 .

图书馆发展

关于先决条件,源构建和浏览器测试,见向c2pa-web捐款。。。 .

版本与发布记录

@contentauth/c2pa-web 共发布 57 个版本，首次发布于 2025/08/30；过去 12 个月发布了 45 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`0.16.0`latest	2026/11/05	5 天前
`0.15.6`	2026/11/04	6 天前
`0.15.5`	2026/10/27	14 天前
`0.15.4`	2026/10/17	24 天前
`0.15.3`	2026/09/30	1 个月前
`0.15.2`	2026/09/24	1 个月前

关于 @contentauth/c2pa-web 的常见问题