Web3Modal

支持版本: >=v2 支持日期: 2023.10.18

开发示例


import { createWeb3Modal } from "@web3modal/wagmi/react";
import { http, createConfig, WagmiProvider } from "wagmi";
import { mainnet, arbitrum } from "viem/chains";
import { walletConnect, coinbaseWallet } from "wagmi/connectors";
 
// 1. 在 https://cloud.walletconnect.com 获取 projectId
const projectId = 'YOUR_PROJECT_ID';
if (!projectId) throw new Error("Project ID is undefined");
 
// 2. 创建 wagmiConfig
const metadata = {
  name: "Web3Modal",
  description: "Web3Modal Example",
  url: "https://web3modal.com",
  icons: ["https://avatars.githubusercontent.com/u/37784886"],
};
 
// 定义链
const chains = [mainnet, arbitrum] as const
 
const wagmiConfig = createConfig({
  chains, // 在这里使用定义的链
  transports: {
    [mainnet.id]: http(),
    [arbitrum.id]: http(),
  },
  connectors: [
    walletConnect({ projectId, metadata, showQrModal: false }),
    coinbaseWallet({
      appName: metadata.name,
      appLogoUrl: metadata.icons[0],
    }),
  ],
});
 
// 3. 创建模态框
createWeb3Modal({ wagmiConfig, projectId });
 
ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <WagmiProvider config={wagmiConfig}>
      <w3m-button />
    </WagmiProvider>
  </React.StrictMode>
);

安装


npm install @web3modal/wagmi wagmi viem @tanstack/react-query

基础配置

1. 获取项目 ID

访问 WalletConnect Cloud 注册并获取项目 ID。

2. 创建配置


import { createWeb3Modal } from '@web3modal/wagmi/react'
import { defaultWagmiConfig } from '@web3modal/wagmi/react/config'
import { WagmiProvider } from 'wagmi'
import { arbitrum, mainnet } from 'wagmi/chains'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 
// 1. 获取项目ID
const projectId = 'YOUR_PROJECT_ID'
 
// 2. 创建wagmiConfig
const metadata = {
  name: '我的DApp',
  description: '我的DApp描述',
  url: 'https://myapp.com',
  icons: ['https://myapp.com/icon.png'],
}
 
const chains = [mainnet, arbitrum] as const
const config = defaultWagmiConfig({
  chains,
  projectId,
  metadata,
})
 
// 3. 创建模态框
createWeb3Modal({
  wagmiConfig: config,
  projectId,
  enableAnalytics: true, // 可选 - 默认为你的Cloud配置
})
 
export function Web3ModalProvider({ children }) {
  const queryClient = new QueryClient()
 
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </WagmiProvider>
  )
}

3. 包装应用


import { Web3ModalProvider } from './config'
 
function App() {
  return <Web3ModalProvider>{/* 您的应用组件 */}</Web3ModalProvider>
}

连接钱包

使用连接按钮


import { useWeb3Modal } from '@web3modal/wagmi/react'
import { useAccount } from 'wagmi'
 
function ConnectButton() {
  const { open } = useWeb3Modal()
  const { address, isConnected } = useAccount()
 
  if (isConnected) {
    return <div>已连接: {address}</div>
  }
 
  return <button onClick={() => open()}>连接钱包</button>
}

使用预构建组件


import { W3mConnectButton, W3mAccountButton } from '@web3modal/wagmi/react'
 
function WalletButtons() {
  return (
    <div>
      <W3mConnectButton />
      <W3mAccountButton />
    </div>
  )
}

自定义主题

设置主题模式


import { createWeb3Modal } from '@web3modal/wagmi/react'
 
createWeb3Modal({
  wagmiConfig: config,
  projectId,
  themeMode: 'dark', // 'light' | 'dark'
})

自定义主题变量


createWeb3Modal({
  wagmiConfig: config,
  projectId,
  themeVariables: {
    '--w3m-color-mix': '#00DCFF',
    '--w3m-color-mix-strength': 20,
    '--w3m-font-family': 'Roboto, sans-serif',
    '--w3m-border-radius-master': '10px',
  },
})

网络切换


import { useWeb3Modal } from '@web3modal/wagmi/react'
import { useAccount, useSwitchChain } from 'wagmi'
 
function NetworkSwitcher() {
  const { open } = useWeb3Modal()
  const { chain } = useAccount()
  const { switchChain } = useSwitchChain()
 
  return (
    <div>
      <p>当前网络: {chain?.name}</p>
      <button onClick={() => open({ view: 'Networks' })}>切换网络</button>
    </div>
  )
}

获取连接状态


import { useWeb3ModalState } from '@web3modal/wagmi/react'
 
function ConnectionStatus() {
  const { open, selectedNetworkId } = useWeb3ModalState()
 
  return (
    <div>
      <p>模态框打开: {open ? '是' : '否'}</p>
      <p>选中网络: {selectedNetworkId}</p>
    </div>
  )
}

事件监听


import { useWeb3ModalEvents } from '@web3modal/wagmi/react'
 
function EventListener() {
  const events = useWeb3ModalEvents()
 
  useEffect(() => {
    console.log('Web3Modal事件:', events)
  }, [events])
 
  return <div>查看控制台以获取事件</div>
}

高级配置

自定义钱包列表


import { createWeb3Modal } from '@web3modal/wagmi/react'
 
createWeb3Modal({
  wagmiConfig: config,
  projectId,
  featuredWalletIds: [
    'c57ca95b47569778a828d19178114f4db188b89b763c899ba0be274e97267d96', // MetaMask
    'fd20dc426fb37566d803205b19bbc1d4096b248ac04548e3cfb6b3a38bd033aa', // Bitget Wallet
  ],
  includeWalletIds: [
    'c57ca95b47569778a828d19178114f4db188b89b763c899ba0be274e97267d96',
    'fd20dc426fb37566d803205b19bbc1d4096b248ac04548e3cfb6b3a38bd033aa',
  ],
  excludeWalletIds: ['some-wallet-id-to-exclude'],
})

自定义令牌


createWeb3Modal({
  wagmiConfig: config,
  projectId,
  tokens: {
    1: {
      address: '0xA0b86a33E6441c41bf2d68dC6AF6C344CC22b4Ad',
      image: 'token_image_url',
    },
    42161: {
      address: '0x912CE59144191C1204E64559FE8253a0e49E6548',
      image: 'arbitrum_token_image_url',
    },
  },
})

使用 Hook

钱包信息


import { useWeb3Modal } from '@web3modal/wagmi/react'
import { useAccount, useDisconnect } from 'wagmi'
 
function WalletInfo() {
  const { open } = useWeb3Modal()
  const { address, connector, isConnected } = useAccount()
  const { disconnect } = useDisconnect()
 
  if (!isConnected) {
    return <button onClick={() => open()}>连接钱包</button>
  }
 
  return (
    <div>
      <p>钱包: {connector?.name}</p>
      <p>地址: {address}</p>
      <button onClick={() => disconnect()}>断开连接</button>
      <button onClick={() => open({ view: 'Account' })}>账户详情</button>
    </div>
  )
}

余额和交易


import { useBalance, useSendTransaction } from 'wagmi'
import { parseEther } from 'viem'
 
function WalletActions() {
  const { address } = useAccount()
  const { data: balance } = useBalance({ address })
  const { sendTransaction } = useSendTransaction()
 
  const handleSend = () => {
    sendTransaction({
      to: '0x...',
      value: parseEther('0.01'),
    })
  }
 
  return (
    <div>
      <p>
        余额: {balance?.formatted} {balance?.symbol}
      </p>
      <button onClick={handleSend}>发送 0.01 ETH</button>
    </div>
  )
}

完整示例


import { createWeb3Modal } from '@web3modal/wagmi/react'
import { defaultWagmiConfig } from '@web3modal/wagmi/react/config'
import { WagmiProvider } from 'wagmi'
import { mainnet, arbitrum } from 'wagmi/chains'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { useAccount, useBalance } from 'wagmi'
import { W3mConnectButton, W3mAccountButton } from '@web3modal/wagmi/react'
 
// 配置
const projectId = 'YOUR_PROJECT_ID'
const metadata = {
  name: 'Web3Modal Example',
  description: 'Web3Modal Example',
  url: 'https://web3modal.com',
  icons: ['https://avatars.githubusercontent.com/u/37784886'],
}
 
const chains = [mainnet, arbitrum] as const
const config = defaultWagmiConfig({
  chains,
  projectId,
  metadata,
})
 
createWeb3Modal({
  wagmiConfig: config,
  projectId,
  enableAnalytics: true,
})
 
function DApp() {
  const { address, isConnected } = useAccount()
  const { data: balance } = useBalance({ address })
 
  return (
    <div>
      <W3mConnectButton />
      {isConnected && (
        <div>
          <p>地址: {address}</p>
          <p>
            余额: {balance?.formatted} {balance?.symbol}
          </p>
          <W3mAccountButton />
        </div>
      )}
    </div>
  )
}
 
function App() {
  const queryClient = new QueryClient()
 
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <DApp />
      </QueryClientProvider>
    </WagmiProvider>
  )
}
 
export default App

注意事项

项目 ID: 确保在生产环境中使用有效的 WalletConnect 项目 ID
网络配置: 根据您的 DApp 需求配置支持的网络
主题定制: 利用主题变量匹配您的品牌风格
钱包过滤: 使用 featuredWalletIds 和 excludeWalletIds 控制显示的钱包

Web3Modal

开发示例

安装

基础配置

1. 获取项目 ID

2. 创建配置

3. 包装应用

连接钱包

使用连接按钮

使用预构建组件

自定义主题

设置主题模式

自定义主题变量

网络切换

获取连接状态

事件监听

高级配置

自定义钱包列表

自定义令牌

使用 Hook

钱包信息

余额和交易

完整示例

注意事项

相关资源