TronWallet Adapter (多钱包适配器)

📘
前置阅读

TronWeb

TronWallet Adapter 是 TRON DApp 连接用户钱包的标准化前端 SDK。有了它，开发者不必为 TronLink、OKX Wallet、Bitget Wallet、WalletConnect 协议钱包、Ledger 硬件钱包逐一编写零碎的接入代码，只需通过适配器接口集成一次，就能支持各类主流钱包；通信协议协商和各家 API 的差异，由适配器层自动处理。

本文简要介绍 TronWallet Adapter。完整的技术规范与开发指南（安装矩阵、全部 React / Vue Hooks 接口、UI 按钮组件清单、事件处理、标准错误码列表）见 walletadapter.org/docs。

适配器架构体系

TronWallet Adapter 是以 @tronweb3/ 命名空间发布的 npm 包族 JavaScript SDK。它统一了“连接（Connect）”“断开（Disconnect）”“签名（Sign）”“交易发送（Send）”的流转控制，DApp 前端只面向同一个抽象接口编程，就能兼容不同的钱包生态。

该 SDK 体系分为以下三个清晰的职责层级：

基础适配器层（@tronweb3/tronwallet-adapters）：为每一个具体的钱包客户端提供对应的适配器实现类（如 TronLinkAdapter、OkxWalletAdapter 等），它们均继承并实现自同一个抽象接口 WalletAdapter。
React / Vue 响应式 Hooks 层（@tronweb3/tronwallet-adapter-react-hooks 或 -vue-hooks）：提供符合框架习惯的 useWallet Hook，自动管理当前激活的适配器实例，并对外暴露 connect、disconnect、address、connected、signTransaction、signMessage 等响应式状态和方法。
开箱即用 UI 组件层（@tronweb3/tronwallet-adapter-react-ui 或 -vue-ui）：提供开箱即用的 WalletConnectButton、WalletSelectButton 按钮和钱包选择模态弹窗。这些组件内部已绑定 Hooks 状态，并支持自定义扩展。

可以按需组合：只用底层适配器库，配合自定义 UI 样式；或者直接用 hooks + UI 组件库，快速接入。

为什么推荐使用该适配器？

单一 API 兼容各类钱包：无需重写业务代码即可引入或移除支持的钱包类型，适配器在统一接口层面处理各家钱包私有 API 的实现差异。
开箱即用的响应式状态管理：Hooks 自动监听网络切换、账户切换、断开连接等事件，实时更新 connected、address 等状态，无需手动编写监听与解绑逻辑。
现成的 UI 组件：内置钱包连接按钮、连接引导模态框等，减少 UI 重复开发。
规范化的异常错误模型：统一抽象 WalletError 错误基类及其下属的具体异常（WalletNotFoundError、WalletDisconnectedError、WalletConnectionError 等），在全局唯一的 onError 回调中统一拦截处理所有异常。

快速上手 (React 最简示例)

以下演示最简的 React DApp 集成流程：安装依赖，用 WalletProvider 容器组件包裹应用，并在子组件中通过 useWallet Hook 读取钱包状态、执行操作。

1. 安装核心依赖

npm install @tronweb3/tronwallet-adapter-react-hooks \
            @tronweb3/tronwallet-abstract-adapter \
            @tronweb3/tronwallet-adapters

2. 编写组件代码

import { WalletProvider, useWallet } from '@tronweb3/tronwallet-adapter-react-hooks';
import { TronLinkAdapter } from '@tronweb3/tronwallet-adapters';
import { useMemo } from 'react';

// 在应用根组件中初始化所支持的钱包适配器数组
function App() {
  const adapters = useMemo(() => [new TronLinkAdapter()], []);
  return (
    <WalletProvider adapters={adapters} onError={(e) => console.error(e)}>
      <Wallet />
    </WalletProvider>
  );
}

// 在子业务组件中调用 Hook 发起交互
function Wallet() {
  const { connect, disconnect, connected, address, signMessage } = useWallet();
  return (
    <div>
      {connected ? (
        <button onClick={disconnect}>断开连接 ({address})</button>
      ) : (
        <button onClick={connect}>连接 TronLink 钱包</button>
      )}
      
      <button disabled={!connected} onClick={() => signMessage('hello tron')}>
        对明文消息签名
      </button>
    </div>
  );
}

以上是一个标准的 TRON 钱包交互生命周期。多钱包切换菜单、自定义主题按钮、链上交易签名、网络变更监听、Vue 版本集成，见完整文档：walletadapter.org/docs。

支持的钱包列表

目前，该适配器套件原生支持以下主流 TRON 客户端：

TronLink：浏览器 Chrome/Firefox 插件，以及移动端内置浏览器环境。
OKX Wallet 钱包插件与 App。
Bitget Wallet 钱包插件与 App。
TokenPocket 钱包。
Bybit Wallet 钱包。
WalletConnect：支持所有兼容 WalletConnect v2 协议标准的多链钱包。
Ledger：通过 WebHID API 连接的硬件钱包。
GateWallet / iToken / TronWeb 注入式通用钱包。

欲查阅最新支持的钱包列表与特定钱包的依赖说明，请访问 walletadapter.org/wallets。

深入技术资源

资源名称	访问 URL
适配器网站	walletadapter.org
完整开发者文档	walletadapter.org/docs
GitHub 开源仓库	github.com/tronweb3/tronwallet-adapter

前置阅读

适配器架构体系

为什么推荐使用该适配器？

快速上手 (React 最简示例)

1. 安装核心依赖

2. 编写组件代码

支持的钱包列表

深入技术资源

相关资源