@ckb-ccc/connector

@ckb-ccc/connector 提供一个原生 Web Component，无需任何 JavaScript 框架即可渲染 CCC 的钱包选择界面。@ckb-ccc/connector-react 以此包为基础构建。

适用场景

在纯 HTML 页面、原生 JS 项目，或 React 以外的框架中需要钱包连接能力时，使用 @ckb-ccc/connector。如果你正在开发 React 应用，建议使用 @ckb-ccc/connector-react——它在本包基础上封装了 React 绑定。

安装

@ckb-ccc/connector npm downloads per week

npm install @ckb-ccc/connector

`WebComponentConnector` 类

核心导出是 ccc.WebComponentConnector——自定义元素的底层类。将元素注册并添加到 DOM 后，即可渲染钱包选择界面。

import { ccc } from "@ckb-ccc/connector";

// connector 元素
const connector: ccc.WebComponentConnector;

connector.client;       // 当前 ccc.Client
connector.wallet;       // 已连接的 ccc.Wallet | undefined
connector.signer;       // ccc.SignerInfo | undefined

connector.disconnect(); // 断开当前钱包连接
connector.setClient(newClient); // 切换网络

选择交易费率

连接钱包后的界面会在 Manage 上方显示 Fee Rate 入口，应用无需额外设计触发按钮。点击后会在同一个弹窗内进入费率选择页，并提供经济、自动和自定义费率。选择会立即生效，点击左上角返回连接页。目前选择结果只保存在 connector UI 状态中。

在纯 HTML 中使用

<!doctype html>
<html>
  <head>
    <script type="module">
      import { ccc } from "https://esm.sh/@ckb-ccc/connector";

      const connector = document.getElementById("ccc-connector");

      document.getElementById("open-btn").addEventListener("click", () => {
        connector.style.display = "";
      });

      connector.addEventListener("close", () => {
        connector.style.display = "none";
      });

      connector.addEventListener("willUpdate", () => {
        if (connector.signer) {
          connector.signer.signer.getRecommendedAddress().then((addr) => {
            document.getElementById("address").textContent = addr;
          });
        }
      });
    </script>
  </head>
  <body>
    <button id="open-btn">连接钱包</button>
    <p id="address"></p>

    <ccc-connector
      id="ccc-connector"
      style="display: none; z-index: 999;"
    ></ccc-connector>
  </body>
</html>

配合打包工具使用（原生 JS/TS）

import { ccc } from "@ckb-ccc/connector";

// 导入本包后，自定义元素会自动注册。
const connector = document.querySelector("ccc-connector") as ccc.WebComponentConnector;

// 显示钱包选择界面
connector.style.display = "";

// 监听事件
connector.addEventListener("close", () => {
  connector.style.display = "none";
});

connector.addEventListener("willUpdate", () => {
  console.log("已连接钱包：", connector.wallet?.name);
  console.log("Signer：", connector.signer);
});

// 切换至主网
connector.setClient(new ccc.ClientPublicMainnet());

使用 CSS 自定义属性调整样式

在 <ccc-connector> 上设置 CSS 自定义属性，即可定制内置界面的主题。下表列出了 Web Component 使用的全部变量；其中默认值来自 @ckb-ccc/connector-react 提供的浅色主题。

自定义属性	React 默认值	控制内容
`--background`	`#fff`	弹窗及输入框的基础背景
`--divider`	`#eee`	分隔线
`--btn-primary`	`#f8f8f8`	主要按钮背景
`--btn-primary-hover`	`#efeeee`	主要按钮 hover 及选中状态背景
`--btn-secondary`	`#ddd`	次要胶囊按钮背景
`--btn-secondary-hover`	`#ccc`	次要胶囊按钮 hover 背景
`--btn-color`	`color`（`#1e1e1e`）	按钮文字、SVG 图标及内嵌输入框文字
`--btn-color-hover`	`--btn-color`	按钮 hover 或选中状态下的内容颜色
`--icon-primary`	`#1E1E1E`	主要图标
`--icon-secondary`	`#666666`	次要图标
`--tip-color`	`#666`	辅助及提示文字
`--tip-color-hover`	`--tip-color`	可交互提示文字 hover 或选中状态的颜色

Connector 的普通文字继承标准 CSS color 属性。未指定时， --btn-color 同样继承 color，--btn-color-hover 回退到 --btn-color，--tip-color-hover 回退到 --tip-color。

<ccc-connector
  style="
    color: #e6eef2;
    --background: #11181c;
    --divider: #28343a;
    --btn-primary: #171d21;
    --btn-primary-hover: #5bcefa;
    --btn-color: #e6eef2;
    --btn-color-hover: #070a0c;
    --tip-color: #76858d;
    --tip-color-hover: #31515f;
  "
></ccc-connector>

与 `@ckb-ccc/connector-react` 的对比

特性	`@ckb-ccc/connector`	`@ckb-ccc/connector-react`
框架依赖	无（Web Component）	React
集成方式	DOM 事件	`Provider` + `useCcc()` Hook
状态管理	手工监听 DOM 事件	React Context，响应式
Peer 依赖	—	`react >= 16`

@ckb-ccc/connector-react 使用 @lit/react 对本 Web Component 进行封装。所有钱包集成（JoyID、MetaMask、Nostr、BTC 系钱包等）均通过同一底层 connector 元素接入。

@ckb-ccc/connector

On this page