Wagmi React API Hooks 完整文档（v2+ 适配版）

说明

本文档基于 Wagmi v2+ 版本整理，已替换所有过期 API：

• 原 useContractRead → 替换为 useReadContract
• 原 useContractWrite → 替换为 useWriteContract
• 原 useContractEvent → 替换为 useWatchContractEvent

所有 Hooks 按功能分类，统一包含「功能、参数、示例、使用场景」，确保代码可直接复用且类型安全。

目录

1. 账户与连接管理
2. 合约交互（核心更新）
3. 区块与交易信息
4. ENS 相关
5. Gas 与费用管理
6. 工具与配置
7. 实验性 API
8. 参考链接

1. 账户与连接管理

1.1 useAccount

功能

获取当前连接的账户信息（地址、连接状态等），并监听连接/断开事件。

参数

示例

import { useAccount } from 'wagmi';

function AccountStatus() {
  const { 
    address,       // 账户地址（未连接时为undefined）
    isConnected,   // 是否已连接
    isConnecting,  // 是否正在连接中
    connector      // 当前连接的钱包连接器
  } = useAccount({
    onConnect: (data) => console.log('已连接账户:', data.address),
    onDisconnect: () => console.log('已断开连接'),
  });

  if (isConnecting) return <div>连接中...</div>;
  if (!isConnected) return <div>请连接钱包</div>;

  return (
    <div>
      <p>当前账户: {address.slice(0, 6)}...{address.slice(-4)}</p>
      <p>钱包: {connector?.name}</p>
    </div>
  );
}

使用场景

• 展示当前账户状态、钱包类型。
• 基于连接状态控制 UI 显示（如连接后显示转账按钮）。

1.2 useAccountEffect

功能

仅监听账户连接/断开状态变化，无 UI 依赖（适合日志记录、状态重置）。

参数

同 useAccount 的 onConnect 和 onDisconnect。

示例

import { useAccountEffect } from 'wagmi';

function AccountEffectListener() {
  useAccountEffect({
    onConnect: (data) => {
      console.log('账户连接:', data.address);
      // 加载用户数据（如持仓、订单）
    },
    onDisconnect: () => {
      console.log('账户断开');
      // 重置应用状态（如清空余额缓存）
    },
  });
  return null; // 无 UI 渲染
}

1.3 useConnect

功能

处理钱包连接逻辑，支持多连接器（如 MetaMask、WalletConnect）。

参数

示例

import { useConnect } from 'wagmi';
import { InjectedConnector } from 'wagmi/connectors/injected';

function WalletConnectButtons() {
  const { 
    connect,        // 触发连接的函数
    connectors,     // 所有配置的连接器列表
    isLoading,      // 是否正在连接
    error           // 连接错误信息
  } = useConnect();

  return (
    <div>
      {connectors.map((connector) => (
        <button
          key={connector.uid}
          onClick={() => connect({ connector })}
          disabled={!connector.ready || isLoading}
          style={{ margin: '0 8px', padding: '8px 16px' }}
        >
          连接 {connector.name}
          {isLoading && ' (连接中...)'}
        </button>
      ))}
      {error && <div style={{ color: 'red', marginTop: 8 }}>{error.message}</div>}
    </div>
  );
}

1.4 useDisconnect

功能

断开当前钱包连接。

参数

示例

import { useDisconnect, useAccount } from 'wagmi';

function DisconnectButton() {
  const { isConnected } = useAccount();
  const { disconnect, isLoading } = useDisconnect({
    onSuccess: () => alert('已断开钱包连接'),
  });

  if (!isConnected) return null;

  return (
    <button 
      onClick={disconnect} 
      disabled={isLoading}
      style={{ color: 'red', padding: '8px 16px' }}
    >
      {isLoading ? '断开中...' : '断开连接'}
    </button>
  );
}

1.5 其他连接管理 Hooks

2. 合约交互（核心更新）

2.1 useReadContract（替代 useContractRead）

功能

调用合约只读方法（获取链上数据，不消耗 Gas），支持实时监听。

参数

示例（查询 ERC20 余额）

import { useReadContract } from 'wagmi';
import { erc20Abi } from 'wagmi/abi'; // 内置 ERC20 ABI

// 固定地址用 as const 确保类型安全
const DAI_ADDRESS = '0x6B175474E89094C44Da98b954EedeAC495271d0F' as const;
const USER_ADDRESS = '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e' as const;

function TokenBalance() {
  const { 
    data: balance,    // 方法返回结果（uint256 类型，单位 wei）
    isLoading,        // 加载中状态
    isError,          // 错误状态
    error             // 错误信息
  } = useReadContract({
    address: DAI_ADDRESS,
    abi: erc20Abi,
    functionName: 'balanceOf', // 只读方法名
    args: [USER_ADDRESS],      // 参数：查询目标账户
    watch: true,               // 实时更新余额
  });

  if (isLoading) return <div>加载中...</div>;
  if (isError) return <div>错误: {error.message}</div>;

  // 格式化余额（18 小数位转换为可读格式）
  const formatted = balance ? (Number(balance) / 10 ** 18).toFixed(4) : '0';

  return <div>DAI 余额: {formatted} DAI</div>;
}

使用场景

• 查询代币余额、NFT 所有者、合约参数（如 totalSupply）。
• 实时展示链上数据（如动态质押收益、价格）。

2.2 useWriteContract（替代 useContractWrite）

功能

调用合约写入方法（发送交易，消耗 Gas，修改链上状态），支持跟踪交易生命周期。

参数

示例（ERC20 转账）

import { useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
import { erc20Abi } from 'wagmi/abi';
import { parseEther } from 'viem'; // 转换单位（18 小数位）

const DAI_ADDRESS = '0x6B175474E89094C44Da98b954EedeAC495271d0F' as const;
const RECIPIENT = '0xBbBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB' as const;

function TokenTransfer() {
  // 1. 初始化写入 Hook
  const {
    writeContract, // 触发交易的函数
    data: txHash,  // 交易哈希（发送成功后返回）
    isLoading: isSending, // 发送中状态
    isError: isSendError, // 发送错误
    error: sendError // 发送错误信息
  } = useWriteContract();

  // 2. 监听交易确认状态（确保上链）
  const {
    isLoading: isConfirming, // 确认中状态
    isSuccess: isTxSuccess   // 交易成功状态
  } = useWaitForTransactionReceipt({ hash: txHash });

  // 触发转账：转 1 DAI
  const handleTransfer = () => {
    writeContract({
      address: DAI_ADDRESS,
      abi: erc20Abi,
      functionName: 'transfer',
      args: [
        RECIPIENT,                // 接收地址
        parseEther('1.0')         // 转账金额（1 DAI → wei）
      ]
    });
  };

  return (
    <div>
      <button 
        onClick={handleTransfer} 
        disabled={isSending || isConfirming}
        style={{ padding: '8px 16px' }}
      >
        {isSending && '发送中...'}
        {isConfirming && '确认中...'}
        {!isSending && !isConfirming && '转账 1 DAI'}
      </button>

      {isSendError && <div style={{ color: 'red' }}>发送失败: {sendError.message}</div>}
      {isTxSuccess && txHash && (
        <div style={{ color: 'green', marginTop: 8 }}>
          转账成功！哈希: <a href={`https://etherscan.io/tx/${txHash}`} target="_blank">
            {txHash.slice(0, 10)}...
          </a>
        </div>
      )}
    </div>
  );
}

使用场景

• 代币转账、NFT 铸造/转账、协议存款/取款等链上状态修改操作。

2.3 useWatchContractEvent（替代 useContractEvent）

功能

实时监听合约指定事件（如 Transfer、Approval），触发自定义逻辑。

参数

示例（监听 ERC20 转账事件）

import { useWatchContractEvent } from 'wagmi';
import { erc20Abi } from 'wagmi/abi';
import { useCallback, useState } from 'react';

const DAI_ADDRESS = '0x6B175474E89094C44Da98b954EedeAC495271d0F' as const;

function TransferMonitor() {
  const [transfers, setTransfers] = useState<Array<{ from: string; to: string; value: string }>>([]);

  // 用 useCallback 确保 listener 引用稳定，避免重复注册
  const handleTransfer = useCallback((from: string, to: string, value: bigint) => {
    const formattedValue = (Number(value) / 10 ** 18).toFixed(4);
    setTransfers(prev => [{ from, to, value: formattedValue }, ...prev].slice(0, 10)); // 保留最新10条
  }, []);

  // 监听 Transfer 事件
  useWatchContractEvent({
    address: DAI_ADDRESS,
    abi: erc20Abi,
    eventName: 'Transfer',
    listener: handleTransfer,
  });

  return (
    <div>
      <h3>最新 DAI 转账（10条）</h3>
      {transfers.length === 0 ? (
        <p>暂无转账记录</p>
      ) : (
        <ul>
          {transfers.map((tx, idx) => (
            <li key={idx}>
              {tx.from.slice(0, 6)}... → {tx.to.slice(0, 6)}... | {tx.value} DAI
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

使用场景

• 实时跟踪合约交互（如 NFT 转账、代币授权）。
• 构建实时通知系统（如“收到转账”弹窗）。

2.4 其他合约交互 Hooks

3. 区块与交易信息

3.1 useBlock

功能

获取指定区块的详细信息（哈希、时间戳、交易列表）。

参数

示例

import { useBlock } from 'wagmi';

function BlockDetails() {
  const { data: block, isLoading } = useBlock({
    blockNumber: 17829139n, // 指定区块号
  });

  if (isLoading) return <div>加载区块信息中...</div>;

  return (
    <div>
      <p>区块号: {block?.number.toString()}</p>
      <p>哈希: {block?.hash}</p>
      <p>时间戳: {new Date(Number(block?.timestamp) * 1000).toLocaleString()}</p>
      <p>交易数: {block?.transactions.length}</p>
    </div>
  );
}

3.2 useBlockNumber

功能

获取当前最新区块号，支持实时监听。

参数

示例

import { useBlockNumber } from 'wagmi';

function LatestBlock() {
  const { data: blockNumber, isLoading } = useBlockNumber({ watch: true });
  if (isLoading) return <div>加载中...</div>;
  return <div>当前区块号: {blockNumber?.toString()}</div>;
}

3.3 useSendTransaction

功能

发送原生代币（如 ETH）转账交易。

参数

示例

import { useSendTransaction, useWaitForTransactionReceipt } from 'wagmi';
import { parseEther } from 'viem';

function SendEth() {
  const {
    sendTransaction,
    data: txHash,
    isLoading: isSending
  } = useSendTransaction();

  const { isSuccess: isTxSuccess } = useWaitForTransactionReceipt({ hash: txHash });

  const handleSend = () => {
    sendTransaction({
      to: '0xBbBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB' as const,
      value: parseEther('0.01') // 0.01 ETH → wei
    });
  };

  return (
    <div>
      <button onClick={handleSend} disabled={isSending}>
        {isSending ? '发送中...' : '发送 0.01 ETH'}
      </button>
      {isTxSuccess && txHash && <div>发送成功！哈希: {txHash.slice(0, 10)}...</div>}
    </div>
  );
}

3.4 其他区块/交易 Hooks

4. ENS 相关

4.1 useEnsAddress

功能

将 ENS 名称解析为以太坊地址（如 vitalik.eth → 地址）。

参数

示例

import { useEnsAddress } from 'wagmi';

function EnsToAddress() {
  const { data: address, isLoading, isError } = useEnsAddress({
    name: 'vitalik.eth',
  });

  if (isLoading) return <div>解析中...</div>;
  if (isError) return <div>解析失败</div>;
  return <div>vitalik.eth → {address || '未找到地址'}</div>;
}

4.2 useEnsName

功能

通过地址反向查询 ENS 名称（如地址 → vitalik.eth）。

参数

示例

import { useEnsName } from 'wagmi';

function AddressToEns() {
  const { data: ensName, isLoading } = useEnsName({
    address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37AA96045' as const, // Vitalik 地址
  });

  if (isLoading) return <div>查询中...</div>;
  return <div>地址 → {ensName || '未设置 ENS'}</div>;
}

4.3 其他 ENS Hooks

5. Gas 与费用管理

5.1 useEstimateFeesPerGas

功能

估算当前 EIP-1559 交易的 Gas 费用（maxFeePerGas 和 maxPriorityFeePerGas）。

参数

无。

示例

import { useEstimateFeesPerGas } from 'wagmi';
import { formatGwei } from 'viem'; // 转换为 Gwei 单位

function GasFees() {
  const { data: fees, isLoading } = useEstimateFeesPerGas();

  if (isLoading || !fees) return <div>估算中...</div>;

  return (
    <div>
      <p>Max Fee: {formatGwei(fees.maxFeePerGas)} Gwei</p>
      <p>Max Priority Fee: {formatGwei(fees.maxPriorityFeePerGas)} Gwei</p>
    </div>
  );
}

5.2 useEstimateGas

功能

估算交易所需 Gas 量（单位：gas）。

参数

示例

import { useEstimateGas } from 'wagmi';
import { parseEther } from 'viem';

function EstimateTxGas() {
  const { data: gas, isLoading } = useEstimateGas({
    to: '0xBbBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB' as const,
    value: parseEther('1.0'), // 转账 1 ETH
  });

  if (isLoading) return <div>估算中...</div>;
  return <div>预估 Gas 量: {gas?.toString()} gas</div>;
}

5.3 其他 Gas Hooks

6. 工具与配置

6.1 useBalance

功能

获取指定地址的原生代币或 ERC20 代币余额（简化版，无需手动写 ABI）。

参数

示例

import { useBalance } from 'wagmi';

function UserBalance() {
  const { data: ethBalance } = useBalance({
    address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e' as const,
    watch: true, // 实时更新 ETH 余额
  });

  const { data: daiBalance } = useBalance({
    address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e' as const,
    token: '0x6B175474E89094C44Da98b954EedeAC495271d0F' as const, // DAI 地址
    watch: true,
  });

  return (
    <div>
      <p>ETH 余额: {ethBalance?.formatted} {ethBalance?.symbol}</p>
      <p>DAI 余额: {daiBalance?.formatted} {daiBalance?.symbol}</p>
    </div>
  );
}

6.2 useChainId

功能

获取当前连接的链 ID。

参数

无。

示例

import { useChainId } from 'wagmi';

function NetworkIndicator() {
  const chainId = useChainId();
  const chainMap = {
    1: '以太坊主网',
    11155111: 'Sepolia 测试网',
    137: 'Polygon 主网',
  };
  const chainName = chainMap[chainId] || '未知网络';

  return <div>当前网络: {chainName} (ID: {chainId})</div>;
}

6.3 其他工具 Hooks

7. 实验性 API

注意：实验性 API 可能不稳定，文档不完善，需谨慎使用。

8. 参考链接

• Wagmi 官方文档
• Viem 工具函数（单位转换、ABI 等）