余额显示
ONE SDK 提供了组件和独立 hook，用于在多条链上显示钱包代币余额。
OneWalletBalance 组件
一个即用型组件，为钱包地址渲染格式化的余额视图。
import { OneWalletBalance } from '@one_deploy/sdk';
function WalletView() {
return (
<OneWalletBalance
walletAddress="0x1234...abcd"
chains={[8453, 1, 137]}
autoRefresh
refreshInterval={30000}
/>
);
}
OneBalanceDisplay 组件
一个低级别的显示组件，接受预获取的余额数据。当你需要完全控制数据获取时非常有用。
import { OneBalanceDisplay } from '@one_deploy/sdk';
import type { TokenBalance } from '@one_deploy/sdk';
function CustomBalanceView() {
const balances: TokenBalance[] = [
{
token: 'ETH',
symbol: 'ETH',
name: 'Ethereum',
balance: '1.2345',
balanceUsd: '2469.00',
chainId: 1,
decimals: 18,
contractAddress: null,
logoUri: 'https://assets.one23.io/tokens/eth.png',
},
{
token: 'USDC',
symbol: 'USDC',
name: 'USD Coin',
balance: '500.00',
balanceUsd: '500.00',
chainId: 8453,
decimals: 6,
contractAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
logoUri: 'https://assets.one23.io/tokens/usdc.png',
},
];
return <OneBalanceDisplay balances={balances} />;
}
OneWalletBalance 属性
interface OneWalletBalanceProps {
/** 要显示余额的钱包地址。 */
walletAddress: string;
/** 要获取余额的链 ID 数组。默认为所有支持的链。 */
chains?: number[];
/** 启用自动刷新余额。默认为 false。 */
autoRefresh?: boolean;
/** 刷新间隔（毫秒）。仅在 autoRefresh 为 true 时使用。默认为 30000（30秒）。 */
refreshInterval?: number;
/** 余额加载或更新时触发的回调。 */
onBalancesLoaded?: (balances: TokenBalance[]) => void;
/** 显示零余额的代币。默认为 false。 */
showZeroBalances?: boolean;
/** 额外的 CSS 类名。 */
className?: string;
/** 内联样式。 */
style?: React.CSSProperties;
}
TokenBalance 类型
interface TokenBalance {
/** 代币简称（如 'ETH'、'USDC'）。 */
token: string;
/** 显示符号。 */
symbol: string;
/** 完整的代币名称。 */
name: string;
/** 格式化的余额，以十进制字符串表示。 */
balance: string;
/** 余额的美元等值。 */
balanceUsd: string;
/** 获取此代币余额的链 ID。 */
chainId: number;
/** 代币小数位数。 */
decimals: number;
/** ERC-20 合约地址，原生代币为 null。 */
contractAddress: string | null;
/** 代币 Logo 图片的 URL。 */
logoUri: string;
}
useWalletBalance Hook
useWalletBalance hook 是一个独立的 hook，不需要 provider。你可以在 React 树的任何位置使用它来获取钱包余额。
import { useWalletBalance } from '@one_deploy/sdk';
function BalanceHookExample() {
const {
balances,
totalBalanceUsd,
isLoading,
error,
refetch,
} = useWalletBalance({
walletAddress: '0x1234...abcd',
chains: [8453, 1],
autoRefresh: true,
refreshInterval: 15000,
});
if (isLoading) return <p>Loading balances...</p>;
if (error) return <p>Error: {error.message}</p>;
return (
<div>
<h2>Total: ${totalBalanceUsd}</h2>
<ul>
{balances.map((b) => (
<li key={`${b.chainId}-${b.token}`}>
{b.symbol}: {b.balance} (${b.balanceUsd})
</li>
))}
</ul>
<button onClick={refetch}>Refresh</button>
</div>
);
}
Hook 签名
function useWalletBalance(options: UseWalletBalanceOptions): UseWalletBalanceResult;
interface UseWalletBalanceOptions {
/** 要查询的钱包地址。 */
walletAddress: string;
/** 要获取余额的链 ID。默认为所有支持的链。 */
chains?: number[];
/** 启用自动刷新轮询。默认为 false。 */
autoRefresh?: boolean;
/** 轮询间隔（毫秒）。默认为 30000。 */
refreshInterval?: number;
}
interface UseWalletBalanceResult {
/** 所有请求链上的代币余额数组。 */
balances: TokenBalance[];
/** 所有代币和链的美元总计。 */
totalBalanceUsd: string;
/** 初始获取是否正在进行中。 */
isLoading: boolean;
/** 获取失败时的错误对象，否则为 null。 */
error: OneSDKError | null;
/** 手动触发余额重新获取。 */
refetch: () => Promise<void>;
}
无需 Provider
与 ONE SDK 中的大多数 hook 不同，useWalletBalance 无需将应用包裹在 OneProvider 中即可工作。它直接使用 SDK 的公开 API 端点：
import { useWalletBalance } from '@one_deploy/sdk';
// 这在 OneProvider 外部也能工作
function StandaloneBalance({ address }: { address: string }) {
const { balances, totalBalanceUsd, isLoading } = useWalletBalance({
walletAddress: address,
});
if (isLoading) return <span>...</span>;
return <span>${totalBalanceUsd}</span>;
}
多链余额
使用 chains 属性或选项从特定链获取余额：
import { OneWalletBalance, CHAIN_IDS } from '@one_deploy/sdk';
function MultiChainBalance() {
return (
<OneWalletBalance
walletAddress="0x1234...abcd"
chains={[
CHAIN_IDS.BASE,
CHAIN_IDS.ETHEREUM,
CHAIN_IDS.POLYGON,
CHAIN_IDS.ARBITRUM,
CHAIN_IDS.OPTIMISM,
]}
autoRefresh
refreshInterval={60000}
showZeroBalances={false}
onBalancesLoaded={(balances) => {
console.log(`Loaded ${balances.length} token balances`);
}}
/>
);
}