# @cardano-sdk/web-extension 中文文档

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

版本：0\.39\.46
npm 元数据更新时间：2026-09-25T13:54:04.659Z
中文译文更新时间：2026-11-09T04:23:06.244Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.2 MB，408 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：17 个
- 首次发布：2022-06-24T05:45:20.216Z
- 最新版本发布：2026-09-25T13:54:04.474Z
- 近 30 天下载量：28200（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：275（近 12 个月 9 个）

## 中文简介

网络扩展钱包工具

## 安装

```sh
npm install @cardano-sdk/web-extension
```

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

## README

# Cardano JS SDK 网页扩展

## 关于软件包名称

**网络扩展** 可以指“浏览器扩展”或Web-Extension浏览器API;之所以选择它,是因为软件包与这个API相接.

## 导言

本文件介绍《公约》实施情况 **网络扩展** 软件包,用于构建基于浏览器的加密货币钱包,详细说明其架构、组件及其相互作用.

在本文件中,我们将涵盖:

-   **系统概览 :** 提供网络扩展包及其在钱包开发中的作用的高级别视角.
    
-   **组件描述 :** 刻入网络扩展包内组件的细节,包括来自此SDK内其他包的相关组件.
    
-   **图表 :** 讨论这些组件如何在网页浏览器扩展内与可视化表示进行互动,以帮助理解互动的结构和流动.
    

## 系统概览

这个 **网络扩展** 软件包提供了在浏览器网页扩展上下文中处理钱包管理相关操作的组件。 它汇集了自己的专门组件,并进一步利用其他SDK软件包中的其他组件,特别是: **可观察 钱包** 来自“wallet”软件包和“wallet”软件包的界面 **证人** 界面.

### 网页扩展包的组件

-   **钱包管理员:** 管理可观测钱包的生命周期,包括激活和停用,并负责创建证人实例.
    
-   **钱包仓库 :** 处理扩展环境中钱包数据的存储、检索和管理.
    
-   **签名协调员 :** 为交易和数据签名提供便利.
    

### “ Wallet” 软件包的组件

-   **可观察的Wallet 接口 :** 一个全面的钱包管理解决方案处理交易,地址管理,余额跟踪等钱包操作. 提供钱包状态的实时可观察性,对响应用户界面至关重要.

### 来自“钥匙管理”的组件 软件包

-   **证人界面 :** 这个接口是一个抽象的,旨在将可观察的Wallet执行从KeyAgent中解开,为交易签名提供便利. 此接口将签名协调员与钱包功能连接起来,并为实施多签名和共享钱包铺平道路.

### 组件位置: 服务工作者和UI脚本

在网络扩展环境中,组件在服务人员、UI和内容脚本中战略性地分布。 这个 **钱包管理员**, (中文(简体) ), **钱包仓库**,以及 **可观察 钱包** 居住于服务人员,而 **签名协调员** 位于UI脚本.

这个 **钱包管理员**, (中文(简体) ), **钱包仓库**,以及 **可观察 钱包** 实例出于性能、一致性和安全原因位于服务人员中;这也使钱包通过CIP-30连接而无需钱包UI继续打开。 这种设置确保了用户的应答体验,因为服务人员独立于UI脚本处理密集任务,防止了任何阻塞. 此外,同时具有弹出和全屏UI功能的浏览器钱包,这些组件在一个单一的服务工作者中运行,提供了一个统一的真理源,确保这些不同的用户界面之间的一致性和同步性.

这个 **钱包管理员** 使用 **签名协调员** (从UI脚本到服务员)创建 **证人** 实例,然后提供给 **可观察 钱包** 在他们创造的时候, 联合国 **证人** 在服务工作者和 **签名协调员** 在 ui 脚本中,网页扩展的邮件系统为方便.

设置 **签名协调员** 在UI脚本中,需要硬件钱包交互和用户确认(设备连接必须通过用户手势启动,根据默认浏览器安全政策),允许直接处理密码输入和秘密访问等敏感操作.

记忆中的关键代理在技术上可以活在服务工人身上,但保留在UI上下文使得设计更加简单(所有类型的钱包都一样). 它在签名时也具有安全优势:它应该减少密码句作为敏感数据保存在记忆中的时间,因为它不需要传递到不同的javascript语上下文,并且减少攻击表面,因为它不需要通过扩展消息API.

这种安排还确保用户提示和交易确认有一个更安全、孤立的环境。 因此,钱包扩展组件在服务人员和UI脚本中分配如下:

![Location of instances within the web extension](https://npmcn.com/package/%40cardano-sdk/web-extension/img/fig1.png)

## 构成部分说明

### 签名协调员

这个 **签名协调员** 组件在网络扩展的UI脚本中运行,这是利用直接用户交互能力的战略选择,对于涉及硬件钱包的操作尤为重要.

从本质上讲 **签名协调员** 负责管理交易和数据的签署。 它旨在处理各类签名请求,包括交易证人请求和数据签名请求. 例如,当交易需要签名时 **签名协调员** 将交易细节连同上下文和提供的选项,并进行处理以生成必要的签名。 这一过程可能涉及与硬件钱包或用户输入的交互,在UI脚本环境中处理.

这个 **签名协调员** 还可以灵活处理不同的钱包类型,如InMemory,Ledger,和Trezor钱包等. 这种灵活性对于旨在支持广泛的用户偏好和硬件能力的网络扩展至关重要.

### 钱包管理员

这个 **钱包管理员** 负责组织各种与钱包有关的操作。 它处理钱包的生命周期,包括其创建、初始化、激活、去功能化和网络切换。 这些钱包是 **可观察 钱包** 这些实例提供了钱包的实时更新和状态,包括余额跟踪、交易历史等等。 这个 **钱包管理员** 有效保存这些情况的记录,确保钱包易于取用.

报告的另一个重要方面是: **钱包管理员** 它与 **签名协调员** 通过创建 **证人** 实例。 这个 **钱包管理员** 杠杆 **签名协调员**以方便签署过程。 它提供必要的 **证人** 实例 **可观察 钱包**,使它们能够进行加密操作,如交易签名.

这个 **证人** 通过管理各类证人对UTXO支出进行论证. 对于标准的UTXOs,它生成加密签名. 在处理由脚本控制的UTXOs时,它会提供交易验证所需的必要的脚本和任何附加组件,如数据及赎回器等.

### 钱包仓库

这个 **钱包仓库** 作用是管理钱包数据的存储和检索,作为中央存储库,确保钱包信息的完整性和可获取性.

这个 **钱包仓库** 处理与钱包数据管理有关的各种操作。 这包括添加新的钱包,更新钱包元数据,以及根据需要去除钱包或账户.

《公约》的主要特点之一 **钱包仓库** 它有能力管理数据操作过程中可能出现的冲突。 例如,在添加一个新的钱包时,它会检查潜在的冲突,例如具有相同标识符的现有钱包,以防止数据重复或不一致. 这种冲突管理确保了寄存器内的钱包数据保持一致.

这个 **钱包仓库** 还处理与账户有关的功能。 它提供了在现有钱包中添加新账户,更新账户元数据以及去除账户的方法.

### 可观察 钱包

这个 **可观察 钱包**虽然网络扩展软件包不是直接的组成部分,但在这个设计中发挥着关键作用,由于它在系统架构中的核心地位,值得简要概述.

这个 **可观察 钱包** 它被设计为一个全面的界面,提供各种钱包状态和属性的实时可观察性。 这包括跟踪钱包的余额,授权状态,UTxO集,交易历史等关键数据点. 除了国家追踪之外 **可观察 钱包** 提供交易构建(通过通用TxBuilder)、数据签名和交易提交等基本功能.

## 一体化和交流流动

网络扩展包组件在UI脚本和网络扩展环境的背景脚本(服务员)之间相互作用. 脚本使用消息传递进行通信,这使得服务工作者和UI脚本可以互相收听对方的消息并在同一频道进行响应.

## 启动

当网页扩展应用程序启动时,它会在合适的地方创建所需的实例,并通过网页扩展消息系统将其曝光.

### UI 脚本

在UI脚本中,应用程序创建 **签名协调员** 网络扩展软件包会输出一个功能

```javascript
exposeApi(
  {
    api$: of(signingCoordinator),
    baseChannel: signingCoordinatorApiChannel,
    properties: signingCoordinatorApiProperties
  },
  dependencies
);
```

此函数会曝光 **签名协调员** 到代码运行 在服务员。 此外,UI脚本必须订阅 **交易窗口请求美元** 财务报告和审定财务报表 **签名数据请求元** 观测到 **签名协调员** 这样它就可以处理由 **可观察 钱包** 住在服务员。 这是网页扩展应用程序如何启动 **签名协调员**数字 :

```javascript
ui.ts;

// Instantiate the SigningCoordinator
const signingCoordinator = new SigningCoordinator(
  {
    hwOptions: {
      communicationType: CommunicationType.Web,
      manifest: {
        appUrl: 'https://web-extension.app',
        email: 'e2e@web-extension.app'
      }
    }
  },
  {
    keyAgentFactory: createKeyAgentFactory({
      getBip32Ed25519: Crypto.SodiumBip32Ed25519.create,
      logger
    }),
    logger
  }
);

// Subscribe to sign request observables
merge(signingCoordinator.signDataRequest$, signingCoordinator.transactionWitnessRequest$).subscribe((req) => {
  logger.info('Sign request', req);
  if (req.walletType === WalletType.InMemory) {
    void req.sign(new Uint8Array(passphraseByteArray));
  } else {
    void req.sign();
  }
  logger.info('Signed', req);
});

// Expose signer coordinator to service worker
exposeSigningCoordinatorApi(
  {
    signingCoordinator
  },
  { logger, runtime }
);
```

UI 脚本还创建了代理对象, 用于来自 **钱包仓库**, (中文(简体) ), **钱包管理员** 财务报告和审定财务报表 **可观察 钱包**数字 :

```javascript
ui.ts;

// Consume remote objects.
const walletManager = consumeRemoteApi(
  { baseChannel: walletManagerChannel(walletName), properties: walletManagerProperties },
  { logger, runtime }
);

const repository = consumeRemoteApi(
  { baseChannel: repositoryChannel(walletName), properties: walletRepositoryProperties },
  { logger, runtime }
);

// This remote ObservableWallet object does not change when wallets are activated/deactivated. Instead, its observable properties emit from the currently active wallet.
const wallet = consumeRemoteApi(
  { baseChannel: walletChannel(walletName), properties: observableWalletProperties },
  { logger, runtime }
);
```

这个 **消耗 RemoteApi**, (中文(简体) ), **钱包管理频道**, (中文(简体) ), **仓库频道** 财务报告和审定财务报表 **钱包通道** 是所有从网络扩展包导出的工具函数.

### 服务工作者

在服务人员中,申请即时通知 **钱包仓库** 财务报告和审定财务报表 **钱包管理员** 并透过网络扩展讯息系统曝光:

```javascript
serviceWorker.ts;

const walletRepository =
  new WalletRepository() <
  Metadata >
  {
    logger,
    store: new storage.InMemoryCollectionStore()
  };

const signingCoordinatorApi = consumeRemoteApi(
  {
    baseChannel: signingCoordinatorApiChannel,
    properties: signingCoordinatorApiProperties
  },
  dependencies
);

const walletManager =
  new WalletManager() <
  Metadata >
  ({ name: walletName },
  {
    logger,
    managerStorage: WebExtensionStorage.local,
    runtime,
    signingCoordinatorApi,
    storesFactory,
    walletFactory,
    walletRepository
  });

exposeApi(
  {
    api$: of(walletRepository),
    baseChannel: repositoryChannel(walletName),
    properties: walletRepositoryProperties
  },
  { logger, runtime }
);

exposeApi(
  {
    api$: of(walletManager),
    baseChannel: walletManagerChannel(walletName),
    properties: walletManagerProperties
  },
  { logger, runtime }
);
```

你会注意到我们创造了一个代理对象 **签名协调员** 服务工作者中 **签名协调员** 属于 **钱包管理员**。 。 。 .

此外,我们将揭露目前活跃的 **可观察 钱包** 转到 UI 脚本 :

```javascript
exposeApi(
  {
    api$: walletManager.activeWallet$.asObservable(),
    baseChannel: walletChannel(walletName),
    properties: observableWalletProperties
  },
  { logger, runtime }
);
```

这样,UI脚本就可以使用这个代理对象并订阅其可观察到的属性,即使在钱包被切换后也能收到更新.

## 图表

### 钱包管理员

这个 **钱包管理员**住在服务人员,负责即时处理 **可观察 钱包** 配置以跟踪给定的证书、网络和账户(如果适用).

当用户界面脚本通过网络、账户甚至钱包证书全部切换触发钱包切换时 **钱包管理员** 获取请求的钱包数据 **钱包仓库**,构建一个新的 **证人** 使用 **签名协调员** (这是来自 UI 脚本的代理对象)并创建新 **可观察 钱包** 实例,此新活动钱包通过 **活动钱包元** 可观测 :

![UML Sequence diagram of the switching wallet use case](https://npmcn.com/package/%40cardano-sdk/web-extension/img/fig7.png)

### 签名协调员

在收到联合王国的签名请求后 **证人** 由 **可观察 钱包** 在服务人员背景下运行 **签名协调员** 在 UI 脚本中发布请求。 这一过程涉及在必要时与硬件钱包进行交互,或处理用户输入以确认交易.

一旦签署过程完成 **签名协调员** 将签名发回 **证人**数字 :

![UML Sequence diagram of the sign request use case](https://npmcn.com/package/%40cardano-sdk/web-extension/img/fig8.png)

### 钱包仓库

这个 **钱包仓库**,也生活在服务工作者,独立运作,处理钱包数据的存储和检索. 它不直接参与交易签名的通信流程,但对于维护和提供钱包数据访问至关重要. 当网络扩展应用程序想要添加新的钱包或账户时 它首先在 **钱包仓库** 代理对象。 然后使用 **钱包管理员** 激活已注册钱包的代理对象 :

![UML Sequence diagram of the add new wallet and activate wallet](https://npmcn.com/package/%40cardano-sdk/web-extension/img/fig9.png)

### 类图

![UML Class diagram of the relevant classes](https://npmcn.com/package/%40cardano-sdk/web-extension/img/fig10.png)

### 活动图

![UML Activity diagram of the relevant actions](https://npmcn.com/package/%40cardano-sdk/web-extension/img/fig11.png)

## 常见问题

### @cardano-sdk/web-extension 是什么？

网络扩展钱包工具

### 如何安装 @cardano-sdk/web-extension？

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

### @cardano-sdk/web-extension 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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