@sweetxf/web3-connector

轻量级 Web3 钱包连接 SDK，基于 EIP-6963 钱包发现协议。零配置即可使用——开箱即用的 React 组件，自动识别已安装钱包，支持多链切换、ENS 反查、余额展示。

Features

• 🚀 零配置启动：内置 7 条主流链 + 4 家主流钱包 fallback，不传任何 prop 也能直接用
• 🔌 基于 EIP-6963，自动发现并识别已安装的钱包（MetaMask / OKX / Coinbase / Phantom 等）
• 🧱 内置 ConnectButton、WalletModal、ChainModal 组件，UI 即插即用
• 🔗 多链支持，内置切链 / 加链交互（wallet_switchEthereumChain / wallet_addEthereumChain）
• 🔁 默认开启 autoConnect，刷新后自动恢复上次连接
• 🪪 ENS 反查（vitalik.eth 替代裸地址）
• 💰 实时余额订阅（useBalance）
• 🧩 提供 useWallet、useEip6963Wallets 等 Hooks 便于自定义 UI
• 📦 ESM / CJS / UMD 三种产物，附带完整 TypeScript 类型

Install

npm i @sweetxf/web3-connector ethers
# 或
yarn add @sweetxf/web3-connector ethers
# 或
pnpm add @sweetxf/web3-connector ethers

react、react-dom、ethers 是 peerDependencies，请确保你的项目已经安装。 支持 React 18 / 19，ethers 6.x。

Quick Start

1. 在应用入口引入样式（只需一次）

在 main.tsx / App.tsx / _app.tsx 顶部加上：

import '@sweetxf/web3-connector/style.css';

⚠️ 不引入这一行组件会没有样式。整个 React 应用只需要引入一次。

2. 最简使用（零配置）

import { WalletProvider, ConnectButton } from '@sweetxf/web3-connector';
import '@sweetxf/web3-connector/style.css';

export default function App() {
  return (
    <WalletProvider>
      <ConnectButton />
    </WalletProvider>
  );
}

就这么几行就能跑了——chains 自动用内置的 7 条主流链，wallets 按用户浏览器情况智能选择，autoConnect 默认开启，showBalance 默认显示。

默认行为对照

| 用户浏览器情况 | Modal 内显示 | 点击行为 | |---|---|---| | 装了钱包扩展（EIP-6963 能发现） | 仅显示已装的钱包 | 直接连接 | | 一个钱包扩展都没装 | 显示 4 家 fallback（MetaMask / OKX / Coinbase / Phantom） | 跳转到对应官网下载页 |

3. 自定义链与钱包（按需）

如果默认链/钱包不满足需求，可以传入自定义配置：

import {
  WalletProvider,
  ConnectButton,
  defaultFallbackChains,
  defaultFallbackWallets,
} from '@sweetxf/web3-connector';
import type { Chain } from '@sweetxf/web3-connector';
import '@sweetxf/web3-connector/style.css';

// 在默认链基础上追加自定义链
const myChain: Chain = {
  id: 5000,
  name: 'Mantle',
  rpcUrl: 'https://rpc.mantle.xyz',
  currency: { name: 'Mantle', symbol: 'MNT', decimals: 18 },
  blockExplorer: { name: 'Mantle Explorer', url: 'https://explorer.mantle.xyz' },
};

const chains = [...defaultFallbackChains, myChain];

export default function App() {
  return (
    <WalletProvider chains={chains} wallets={defaultFallbackWallets} autoConnect={false}>
      <ConnectButton showBalance={false} />
    </WalletProvider>
  );
}

4. 在任意子组件中使用 Hooks

import { useWallet, useBalance } from '@sweetxf/web3-connector';

function Profile() {
  const { address, ensName, chainID, isConnected, disconnect, switchChain } = useWallet();
  const { balance, symbol } = useBalance();

  if (!isConnected) return <p>未连接</p>;

  return (
    <div>
      <p>地址：{ensName ?? address}</p>
      <p>当前链 ID：{chainID}</p>
      <p>余额：{balance} {symbol}</p>
      <button onClick={() => switchChain(56)}>切换到 BSC</button>
      <button onClick={disconnect}>断开</button>
    </div>
  );
}

API

Components

<WalletProvider>

全局状态提供者，必须包裹在应用根部。所有 props 均为可选，零配置即可使用。

| Prop | 类型 | 必填 | 默认 | 说明 | |---|---|---|---|---| | chains | Chain[] | ❌ | defaultFallbackChains（7 条主流链） | 应用支持的链列表 | | wallets | Wallet[] | ❌ | 智能选择（见下） | 自定义钱包列表 | | autoConnect | boolean | ❌ | true | 是否在加载时自动恢复上次连接 | | children | ReactNode | ✅ | - | 子节点 |

wallets prop 的处理逻辑：

| 是否传 wallets | EIP-6963 状态 | 实际展示 | |---|---|---| | 传了 | 有发现 | 用户配置 + EIP-6963 钱包（按 rdns 去重，EIP-6963 优先） | | 传了 | 没发现 | 用户配置 | | 不传 | 有发现 | 仅 EIP-6963 钱包 | | 不传 | 没发现 | defaultFallbackWallets（4 家官网下载入口） |

内置默认链列表（defaultFallbackChains）：

Sepolia (11155111) · Ethereum (1) · Polygon (137) · Optimism (10) · Arbitrum (42161) · Base (8453) · BSC (56)

<ConnectButton>

连接钱包按钮：未连接显示 "Connect Wallet"，已连接显示当前链 + 余额 + 地址（或 ENS）。

| Prop | 类型 | 默认 | 说明 | |---|---|---|---| | label | string | 'Connect Wallet' | 未连接时按钮文案 | | size | 'sm' \| 'md' \| 'lg' | 'md' | 按钮尺寸 | | className | string | '' | 额外 className（可叠加 Tailwind / 自定义类） | | showBalance | boolean | true | 已连接状态下是否展示余额 | | onConnect | () => void | - | 连接成功回调 | | onDisconnect | () => void | - | 断开连接回调 |

Hooks

useWallet()

返回当前钱包上下文（WalletContextValue）：

const {
  address,        // 当前地址
  chainID,        // 当前链 id
  ensName,        // ENS（仅主网反查）
  isConnected,    // 是否已连接
  isConnecting,   // 是否正在连接
  error,          // 上一次的错误
  chains,         // 支持的链列表
  connect,        // (walletID: string) => Promise<void>
  disconnect,     // () => Promise<void>
  switchChain,    // (chainID: number) => Promise<void>
  openModal,      // 打开钱包选择弹窗
  closeModal,
  openChainModal, // 打开切链弹窗
  closeChainModal,
} = useWallet();

useBalance()

返回当前账户在当前链上的原生币余额（自动随地址、链 ID 变化刷新）：

const { balance, symbol } = useBalance();
// balance: string | null  -> 已格式化（如 "1.2345"）
// symbol:  string         -> 当前链币种符号

useEip6963Wallets()

返回浏览器中通过 EIP-6963 发现的钱包列表，便于你完全自定义 UI：

const wallets = useEip6963Wallets();
// wallets: Eip6963ProviderDetail[]

默认数据导出

import {
  defaultFallbackChains,    // Chain[] 内置 7 条主流链
  defaultFallbackWallets,   // Wallet[] 内置 4 家钱包 fallback
  metamaskFallback,         // 单独的 MetaMask fallback
  okxFallback,              // 单独的 OKX fallback
  coinbaseFallback,         // 单独的 Coinbase fallback
  phantomFallback,          // 单独的 Phantom fallback
} from '@sweetxf/web3-connector';

Types

可直接从根入口导入：

import type {
  Chain,
  Wallet,
  WalletState,
  WalletContextValue,
  WalletProviderProps,
  WalletConnector,
} from '@sweetxf/web3-connector';

FAQ

Q: 引入后页面没样式 / 按钮是裸标签？ A: 检查是否在应用入口 import '@sweetxf/web3-connector/style.css';。

Q: 我的项目也用 Tailwind，会冲突吗？ A: 不会。本库已将 Tailwind 工具类编译到 style.css，与使用方的 Tailwind 配置互不影响。

Q: 用户没装任何钱包会怎样？ A: 不传 wallets 时，自动展示 defaultFallbackWallets（MetaMask / OKX / Coinbase / Phantom），点击会跳转到对应官网下载页。

Q: 想关掉默认行为？ A: 显式传 false：<WalletProvider autoConnect={false}>、<ConnectButton showBalance={false} />。

Q: 支持 SSR / Next.js 吗？ A: 组件依赖 window.ethereum 等浏览器 API，建议在客户端渲染（Next.js 请使用 'use client' 或 dynamic(..., { ssr: false })）。

Q: ENS 反查需要配置 RPC 吗？ A: 不需要。默认走公共主网 RPC https://eth.llamarpc.com。如要自定义，在使用方项目的 .env 里设 VITE_MAINNET_RPC=... 即可。

License

MIT © sweetxf