@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.khieRelayAddress; // 可选的 Khie 默认 Relay multiaddr
connector.hideKhie; // 默认 false；隐藏 Khie 连接入口
connector.wallet;       // 已连接的 ccc.Wallet | undefined
connector.signer;       // ccc.SignerInfo | undefined

connector.disconnect(); // 断开当前钱包连接
connector.addEventListener("select-client", (event) => {
  connector.client = (event as ccc.SelectClientEvent).client;
});

Web Component 要求传入 client 且只借用它，不会创建或释放 Client。必须在元素加入文档前完成赋值；只要元素仍可能使用该 Client，就应保持其 owner 存活，并由应用生命周期负责释放 owner。网络和 fee-rate 选择都会抛出可穿透 Shadow DOM、可冒泡的 select-client 事件；应用决定是否将候选 Client 写回 client 属性。

选择交易费率

连接钱包后的界面会在 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.createElement("ccc-connector");
      const clientOwner = ccc.ClientPublicTestnet.open();
      connector.client = clientOwner.value;
      connector.style.cssText = "display: none; z-index: 999;";
      let connectionOwner;

      window.addEventListener(
        "pagehide",
        () => {
          void connectionOwner?.dispose();
          void clientOwner.dispose();
        },
        { once: true },
      );

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

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

      connector.addEventListener("select-client", (event) => {
        connector.client = event.client;
      });

      connector.addEventListener("connection", (event) => {
        event.stopPropagation();
        const owner = event.connectionOwner?.map((connection) => connection);
        const previous = connectionOwner;
        connectionOwner = owner;
        void previous?.dispose();

        if (owner) {
          owner.value.signerInfo.signer.getRecommendedAddress().then((addr) => {
            document.getElementById("address").textContent = addr;
          });
        }
      });

      // `client` 必须在元素连接到文档前赋值。
      document.body.append(connector);
    </script>
  </head>
  <body>
    <button id="open-btn">连接钱包</button>
    <p id="address"></p>

  </body>
</html>

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

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

// 导入本包后，自定义元素会自动注册。
const connector = document.createElement(
  "ccc-connector",
) as ccc.WebComponentConnector;
const clientOwner = ccc.ClientPublicTestnet.open();
connector.client = clientOwner.value; // Connector 仅借用该 Client。
connector.khieRelayAddress = "/dns4/relay.example/tcp/443/wss";
connector.hideKhie = true;

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

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

// Connector 只请求变更；Client 由应用控制。
connector.addEventListener("select-client", (event) => {
  connector.client = (event as ccc.SelectClientEvent).client;
});

let connectionOwner: ccc.Owner<ccc.ConnectorConnection> | undefined;
connector.addEventListener("connection", (event) => {
  event.stopPropagation();
  const owner = (event as ccc.ConnectorConnectionEvent).connectionOwner?.map(
    (connection) => connection,
  );
  const previous = connectionOwner;
  connectionOwner = owner;
  void previous?.dispose();

  console.log("已连接钱包：", owner?.value.wallet.name);
  console.log("Signer：", owner?.value.signerInfo);
});

// `client` 必须在元素连接到文档前赋值。
document.body.append(connector);

// 确认不再使用这些资源后，由调用方释放：
// await connectionOwner?.dispose();
// await clientOwner.dispose();

使用 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