> ## Documentation Index > Fetch the complete documentation index at: https://docs.ckbccc.com/llms.txt - append ".md" to any page URL for its Markdown source. > Use this file to discover all available pages before exploring further. --- # @ckb-ccc/connector URL: https://docs.ckbccc.com/zh/docs/packages/core-packages/connector Source: https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/dev/packages/docs/content/docs/packages/core-packages/connector.zh.mdx > 用于钱包连接的 Web Component——框架无关。 `@ckb-ccc/connector` 提供一个原生 [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)，无需任何 JavaScript 框架即可渲染 CCC 的钱包选择界面。`@ckb-ccc/connector-react` 以此包为基础构建。 ## 适用场景 [#适用场景] 在纯 HTML 页面、原生 JS 项目，或 React 以外的框架中需要钱包连接能力时，使用 `@ckb-ccc/connector`。如果你正在开发 React 应用，建议使用 [`@ckb-ccc/connector-react`](./connector-react.mdx)——它在本包基础上封装了 React 绑定。 ## 安装 [#安装] ```bash npm install @ckb-ccc/connector ``` ```bash yarn add @ckb-ccc/connector ``` ```bash pnpm add @ckb-ccc/connector ``` ## `WebComponentConnector` 类 [#webcomponentconnector-类] 核心导出是 `ccc.WebComponentConnector`——自定义元素的底层类。将元素注册并添加到 DOM 后，即可渲染钱包选择界面。 ```typescript 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 中使用 [#在纯-html-中使用] ```html

``` ## 配合打包工具使用（原生 JS/TS） [#配合打包工具使用原生-jsts] ```typescript 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 | 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 自定义属性调整样式 [#使用-css-自定义属性调整样式] 在 `` 上设置 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`。 ```html ``` ## 与 `@ckb-ccc/connector-react` 的对比 [#与-ckb-cccconnector-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 元素接入。