Wagmi 使用指南：以 React 快速建立高效區塊鏈應用

你是否覺得在 React 中與以太坊交互複雜又繁瑣？Wagmi 提供直覺的 React Hooks，大幅簡化你的區塊鏈前端開發流程。

Wagmi 的核心優勢

優異的開發者體驗

Wagmi 通過模塊化和可組合的 API、自動類型安全和推斷，以及全面的文檔提供卓越的開發者體驗。它為開發者提供直觀的構建區塊，雖然 Wagmi 的 API 起初可能看起來較為冗長，但這種設計使得其模塊化構建區塊極為靈活，易於移動、更改和移除。

此外，學習使用 Wagmi 是學習如何與以太坊交互的絕佳方式，因為它讓開發者更好地理解以太坊概念以及為什麼某些屬性需要傳遞。Wagmi 提供強類型 API，使開發者能夠通過自動完成、類型推斷和靜態驗證獲得最佳開發體驗。

卓越的性能

Tree Shaking (ChatGPT 4o)

對於任何規模的應用程序，性能都是至關重要的。Wagmi 使用並由 Viem 團隊構建，Viem 是最高性能的生產就緒型以太坊庫。Wagmi 針對樹搖（tree-shaking）和死代碼消除進行了優化，使應用程序能夠最小化包大小，實現快速頁面加載時間。

數據層性能同樣至關重要。緩慢、不必要和手動的數據獲取可能會使應用程序無法使用並導致 RPC 計算單元成本增加。Wagmi 通過 TanStack Query 支持緩存、去重、持久性等功能。

全面的功能覆蓋

Wagmi 提供開箱即用的最流行和常用的以太坊功能，包括 40 多個用於賬戶、錢包、合約、交易、簽名、ENS 等的 React Hooks。Wagmi 還通過官方連接器、EIP-6963 支持和可擴展 API 支持幾乎所有錢包。

如果需要更底層的控制，開發者可以降級到 Wagmi Core 或 Viem，Wagmi 在內部使用這些工具執行區塊鏈操作。Wagmi 還自動管理多鏈支持，使開發者能夠專注於應用程序而非添加自定義代碼。

相關文章：《viem：下一代 Web3 開發的 TypeScript 接口》

穩定可靠

穩定性是 Wagmi 的基本原則。許多大小組織都嚴重依賴 Wagmi，並期望它對用戶和應用程序完全穩定。

Wagmi 的測試套件在分叉的以太坊節點上運行，以確保功能在各個鏈上都能正常工作。測試套件還針對 TypeScript 等對等依賴的不同版本運行類型測試，以確保與其他流行軟件的最新版本兼容。

Wagmi 遵循語義化版本控制，因此開發者可以自信地在版本之間升級。從 Wagmi v2 開始，新功能將採用選擇加入方式，舊功能將與新功能一起被標記為棄用。這意味著升級到最新的主要版本不需要立即更改。

安裝與配置

自動安裝

對於新項目，建議使用 create-wagmi 命令行界面（CLI）設置你的 Wagmi 應用，create-wagmi 是一個專門設計的工具，可以幫助你快速搭建一個完整的 Wagmi 應用環境。

pnpm create wagmi
# 或
npm create wagmi@latest
# 或
yarn create wagmi

手動安裝

要手動將 Wagmi 添加到項目中，安裝所需的包：

pnpm add wagmi viem@2.x @tanstack/react-query
# 或
npm install wagmi viem@2.x @tanstack/react-query
# 或
yarn add wagmi viem@2.x @tanstack/react-query

創建配置

使用 createConfig 創建並導出一個新的 Wagmi 配置：

import { http, createConfig } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
});

在此示例中，Wagmi 配置為使用 Mainnet 和 Sepolia 鏈。

Blockchain Networks

Wagmi 提供了多種常用的區塊鏈網絡配置，可以直接從 wagmi/chains 導入使用。這些預設的鏈配置包括主流的以太坊主網、測試網，以及許多其他流行的 EVM 兼容鏈。例如：

Ethereum Mainnet: mainnet
Goerli 測試網：goerli
Polygon: polygon
Arbitrum: arbitrum

除了使用預設的鏈配置外，開發者還可以根據需要自定義鏈的配置。這對於支持一些較新的或者不太常見的區塊鏈網絡特別有用。自定義鏈時，需要提供諸如鏈 ID、RPC URL、區塊瀏覽器 URL 等必要信息。

如果需要自定義鏈，可以參考以下示例：

// 自定義鏈配置示例
const myCustomChain = {
  id: 1234,
  name: "My Custom Chain",
  network: "custom",
  nativeCurrency: {
    decimals: 18,
    name: "Custom Coin",
    symbol: "CUST",
  },
  rpcUrls: {
    default: { http: ["https://rpc.mycustomchain.com"] },
    public: { http: ["https://public-rpc.mycustomchain.com"] },
  },
  blockExplorers: {
    default: { name: "CustomScan", url: "https://customscan.com" },
  },
  contracts: {
    multicall3: {
      address: "0xca11bde05977b3631167028862be2a173976ca11",
      blockCreated: 1234567,
    },
  },
};

export const config = createConfig({
  chains: [mainnet, sepolia, myCustomChain],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
    [myCustomChain.id]: http(),
  },
});

這裡的 id 是區塊鏈的唯一識別碼，name 是區塊鏈的名稱，network 是區塊鏈的網絡類型，nativeCurrency 是區塊鏈的原生貨幣，rpcUrls 是區塊鏈的 RPC URL，blockExplorers 是區塊鏈的區塊瀏覽器 URL，contracts 是區塊鏈的合約地址。

值得一提的是，如果區塊鏈支持 multicall3，則可以透過這個智能合約來執行多筆交易，這樣可以減少交易費用和提高效率。

實際應用示例

連接錢包

以下是使用 Wagmi 連接錢包的簡單示例：

import { useAccount, useConnect, useDisconnect } from "wagmi";
import { InjectedConnector } from "wagmi/connectors/injected";

function Profile() {
  const { address, isConnected } = useAccount();
  const { connect } = useConnect({
    connector: new InjectedConnector(),
  });
  const { disconnect } = useDisconnect();

  if (isConnected)
    return (
      <div>
        已連接到 {address}
        <button onClick={() => disconnect()}>斷開連接</button>
      </div>
    );

  return <button onClick={() => connect()}>連接錢包</button>;
}

當用戶點擊連接錢包按鈕時，Wagmi 會使用 InjectedConnector 連接到用戶的錢包。InjectedConnector 會嘗試使用 window.ethereum 作為錢包提供者，如果成功連接，則返回已連接的錢包地址。如果連接失敗，則會顯示錯誤信息。

與智能合約交互

Wagmi 使與智能合約交互變得簡單：

import { useContractRead } from "wagmi";
import { wagmiMintExampleABI } from "../generated";

export function NameNFT() {
  const { data: Name } = useContractRead({
    address: "0xfba3912ca04dd458c843e2ee08967fc04f3579c2",
    abi: wagmiMintExampleABI,
    functionName: "name",
    watch: true,
  });

  return (
    <div>
      <h2>合約名稱：{Name}</h2>
    </div>
  );
}

與其他工具的集成

Wagmi 可以與多種流行的 Web3 工具集成，例如 ConnectKit、RainbowKit、AppKit、Dynamic、Privy 等。這些集成使開發者能夠快速開始，而無需從頭構建所有內容。

例如，與 Magic 的集成允許開發者將 Magic 的無密碼登錄功能與 Wagmi 的區塊鏈交互功能相結合：

import { configureChains, createConfig, WagmiConfig } from "wagmi";
import { mainnet } from "wagmi/chains";
import { publicProvider } from "wagmi/providers/public";
import { DedicatedWalletConnector } from "@magiclabs/wagmi-connector";

const { chains, publicClient, webSocketPublicClient } = configureChains(
  [mainnet],
  [publicProvider()]
);

const config = createConfig({
  autoConnect: true,
  publicClient,
  webSocketPublicClient,
  connectors: [
    new DedicatedWalletConnector({
      chains,
      options: {
        apiKey: "YOUR_MAGIC_API_KEY",
        magicSdkConfiguration: {
          network: {
            rpcUrl: "https://example.com",
            chainId: 1,
          },
        },
      },
    }),
  ],
});