React Hooks

认证钩子

useB3

用于访问全局账户认证状态和操作的主要钩子。

import { useB3 } from "@b3dotfun/sdk/global-account/react";

function AuthComponent() {
  const { 
    account,           // 当前全局账户
    isAuthenticated,   // 认证状态
    isLoading,         // 加载状态
    signOut,           // 登出函数
    refreshAccount     // 刷新账户数据
  } = useB3();

  return (
    <div>
      {isLoading && <p>Loading...</p>}
      
      {isAuthenticated ? (
        <div>
          <h3>Welcome, {account?.displayName}!</h3>
          <p>Account ID: {account?.id}</p>
          <p>Email: {account?.email}</p>
          <button onClick={signOut}>Sign Out</button>
        </div>
      ) : (
        <p>Please sign in to continue</p>
      )}
    </div>
  );
}

返回值

属性	类型	描述
`account`	`GlobalAccount \| null`	当前认证的账户
`isAuthenticated`	`boolean`	用户是否已认证
`isLoading`	`boolean`	是否正在进行认证检查
`signOut`	`() => Promise<void>`	登出当前用户的函数
`refreshAccount`	`() => Promise<void>`	刷新账户数据的函数

useAccountWallet

访问已认证账户的钱包信息。

import { useAccountWallet } from "@b3dotfun/sdk/global-account/react";

function WalletComponent() {
  const { 
    wallet,       // 钱包信息
    isConnected,  // 连接状态
    connect,      // 连接钱包函数
    disconnect    // 断开钱包连接函数
  } = useAccountWallet();

  return (
    <div>
      {isConnected ? (
        <div>
          <p>Address: {wallet?.address}</p>
          <p>Chain: {wallet?.chainId}</p>
          <p>Balance: {wallet?.balance} ETH</p>
          <button onClick={disconnect}>Disconnect</button>
        </div>
      ) : (
        <button onClick={connect}>Connect Wallet</button>
      )}
    </div>
  );
}

权限钩子

usePermissions

管理和检查会话密钥权限。

import { usePermissions } from "@b3dotfun/sdk/global-account/react";

function PermissionsComponent() {
  const { 
    permissions,      // 当前权限
    hasPermissions,   // 用户是否有活动权限
    isExpired,        // 权限是否已过期
    checkPermission   // 检查特定权限
  } = usePermissions();

  const canInteractWithContract = checkPermission("0x...");

  return (
    <div>
      <h3>Permission Status</h3>
      
      {hasPermissions ? (
        <div>
          <p>✅ Active Permissions</p>
          <p>Expires: {permissions?.endDate.toLocaleDateString()}</p>
          <p>Contracts: {permissions?.approvedTargets.length}</p>
          
          {isExpired && <p>⚠️ Permissions expired</p>}
          
          <div>
            <p>Can interact with contract: {canInteractWithContract ? '✅' : '❌'}</p>
          </div>
        </div>
      ) : (
        <p>No active permissions</p>
      )}
    </div>
  );
}

useRequestPermissions

为会话密钥请求新权限。

import { useRequestPermissions } from "@b3dotfun/sdk/global-account/react";

function RequestPermissionsComponent() {
  const { 
    requestPermissions, 
    isLoading, 
    error,
    reset 
  } = useRequestPermissions();

  const handleRequest = async () => {
    try {
      const result = await requestPermissions({
        chain: { id: 8333, name: "B3" },
        sessionKeyAddress: "0x...",
        permissions: {
          approvedTargets: ["0x..."],
          startDate: new Date(),
          endDate: new Date(Date.now() + 24 * 60 * 60 * 1000),
          nativeTokenLimitPerTransaction: 0.01,
        },
      });

      if (result.success) {
        console.log("Permissions granted!");
      }
    } catch (err) {
      console.error("Permission request failed:", err);
    }
  };

  return (
    <div>
      <button 
        onClick={handleRequest}
        disabled={isLoading}
      >
        {isLoading ? "Requesting..." : "Request Permissions"}
      </button>
      
      {error && (
        <div className="error">
          Error: {error.message}
          <button onClick={reset}>Retry</button>
        </div>
      )}
    </div>
  );
}

useRevokePermissions

撤销现有权限。

import { useRevokePermissions } from "@b3dotfun/sdk/global-account/react";

function RevokePermissionsComponent() {
  const { revokePermissions, isLoading, error } = useRevokePermissions();

  const handleRevoke = async () => {
    try {
      await revokePermissions({
        sessionKeyAddress: "0x...",
        chain: { id: 8333, name: "B3" },
      });
      console.log("Permissions revoked successfully");
    } catch (err) {
      console.error("Failed to revoke permissions:", err);
    }
  };

  return (
    <button 
      onClick={handleRevoke}
      disabled={isLoading}
    >
      {isLoading ? "Revoking..." : "Revoke Permissions"}
    </button>
  );
}

资产管理钩子

useAccountAssets

检索和管理用户的数字资产。

import { useAccountAssets } from "@b3dotfun/sdk/global-account/react";

function AssetsComponent() {
  const { 
    assets,        // 用户的资产
    isLoading,     // 加载状态
    error,         // 错误状态
    refreshAssets  // 刷新资产函数
  } = useAccountAssets();

  if (isLoading) return <div>Loading assets...</div>;
  if (error) return <div>Error loading assets: {error.message}</div>;

  return (
    <div>
      <h3>Your Assets</h3>
      <button onClick={refreshAssets}>Refresh</button>
      
      {assets?.map((asset) => (
        <div key={asset.id} className="asset-item">
          <img src={asset.imageUrl} alt={asset.name} />
          <h4>{asset.name}</h4>
          <p>{asset.description}</p>
          <p>Value: {asset.value} {asset.currency}</p>
        </div>
      ))}
    </div>
  );
}

模态管理钩子

useModal

以编程方式控制 B3 模态。

import { useModal } from "@b3dotfun/sdk/global-account/react";

function ModalControlComponent() {
  const { 
    openModal, 
    closeModal, 
    isModalOpen,
    currentModal 
  } = useModal();

  const handleOpenAuth = () => {
    openModal('authentication', {
      provider: { strategy: 'google' },
      partnerId: 'your-partner-id'
    });
  };

  const handleOpenPermissions = () => {
    openModal('permissions', {
      sessionKeyAddress: '0x...',
      permissions: {
        approvedTargets: ['0x...'],
        nativeTokenLimitPerTransaction: 0.01
      }
    });
  };

  return (
    <div>
      <p>Current modal: {currentModal || 'None'}</p>
      <p>Modal open: {isModalOpen ? 'Yes' : 'No'}</p>
      
      <button onClick={handleOpenAuth}>Open Auth Modal</button>
      <button onClick={handleOpenPermissions}>Open Permissions Modal</button>
      <button onClick={closeModal}>Close Modal</button>
    </div>
  );
}

导航钩子

useNavigation

处理 B3 应用内的导航。

import { useNavigation } from "@b3dotfun/sdk/global-account/react";

function NavigationComponent() {
  const { 
    navigate, 
    canGoBack, 
    goBack,
    currentPath 
  } = useNavigation();

  return (
    <div>
      <p>Current path: {currentPath}</p>
      
      <button onClick={() => navigate('/dashboard')}>
        Go to Dashboard
      </button>
      
      <button onClick={() => navigate('/profile')}>
        Go to Profile
      </button>
      
      {canGoBack && (
        <button onClick={goBack}>
          Go Back
        </button>
      )}
    </div>
  );
}

配置钩子

useB3Config

访问 B3 配置和环境设置。

import { useB3Config } from "@b3dotfun/sdk/global-account/react";

function ConfigComponent() {
  const { 
    environment,     // 'production' | 'development'
    apiUrl,          // 当前 API URL
    partnerId,       // 您的合作伙伴 ID
    features,        // 可用功能
    updateConfig     // 更新配置
  } = useB3Config();

  return (
    <div>
      <h3>B3 Configuration</h3>
      <p>Environment: {environment}</p>
      <p>API URL: {apiUrl}</p>
      <p>Partner ID: {partnerId}</p>
      
      <h4>Available Features:</h4>
      <ul>
        {features.map(feature => (
          <li key={feature}>{feature}</li>
        ))}
      </ul>
    </div>
  );
}

钩子组合

自定义钩子示例

结合多个钩子实现复杂功能：

import { useB3, usePermissions, useAccountWallet } from "@b3dotfun/sdk/global-account/react";

function useGameAuth() {
  const { account, isAuthenticated } = useB3();
  const { hasPermissions, isExpired } = usePermissions();
  const { wallet, isConnected } = useAccountWallet();

  const isGameReady = isAuthenticated && hasPermissions && !isExpired && isConnected;
  
  const gameAuthStatus = {
    account: !!account,
    permissions: hasPermissions && !isExpired,
    wallet: isConnected,
    ready: isGameReady
  };

  return {
    account,
    wallet,
    isGameReady,
    gameAuthStatus
  };
}

// 使用
function GameComponent() {
  const { isGameReady, gameAuthStatus } = useGameAuth();

  if (!isGameReady) {
    return (
      <div>
        <h3>Setup Required</h3>
        <ul>
          <li>Account: {gameAuthStatus.account ? '✅' : '❌'}</li>
          <li>Permissions: {gameAuthStatus.permissions ? '✅' : '❌'}</li>
          <li>Wallet: {gameAuthStatus.wallet ? '✅' : '❌'}</li>
        </ul>
      </div>
    );
  }

  return <div>🎮 Game Ready!</div>;
}

TypeScript 支持

所有钩子都完全支持 TypeScript：

import type { 
  GlobalAccount, 
  Permissions, 
  WalletInfo 
} from "@b3dotfun/sdk/global-account/types";

// 钩子返回类型完全类型化
const { account }: { account: GlobalAccount | null } = useB3();
const { permissions }: { permissions: Permissions | null } = usePermissions();
const { wallet }: { wallet: WalletInfo | null } = useAccountWallet();

错误处理

使用钩子处理错误的最佳实践：

function ErrorHandlingExample() {
  const { account, isAuthenticated } = useB3();
  const { requestPermissions, error: permissionError } = useRequestPermissions();
  const { assets, error: assetError } = useAccountAssets();

  // 处理特定错误
  useEffect(() => {
    if (permissionError) {
      console.error('Permission error:', permissionError);
      // 显示用户友好的错误信息
    }
    
    if (assetError) {
      console.error('Asset loading error:', assetError);
      // 重试或显示备用 UI
    }
  }, [permissionError, assetError]);

  return (
    <div>
      {/* 您的组件 JSX */}
    </div>
  );
}

下一步

示例

查看使用这些钩子的完整示例。

Overview

Global Accounts

认证钩子

useB3

返回值

useAccountWallet

权限钩子

usePermissions

useRequestPermissions

useRevokePermissions

资产管理钩子

useAccountAssets

模态管理钩子

useModal

导航钩子

useNavigation

配置钩子

useB3Config

钩子组合

自定义钩子示例

TypeScript 支持

错误处理

下一步

示例

Overview

Global Accounts

​认证钩子

​useB3

​返回值

​useAccountWallet

​权限钩子

​usePermissions

​useRequestPermissions

​useRevokePermissions

​资产管理钩子

​useAccountAssets

​模态管理钩子

​useModal

​导航钩子

​useNavigation

​配置钩子

​useB3Config

​钩子组合

​自定义钩子示例

​TypeScript 支持

​错误处理

​下一步

示例

认证钩子

useB3

返回值

useAccountWallet

权限钩子

usePermissions

useRequestPermissions

useRevokePermissions

资产管理钩子

useAccountAssets

模态管理钩子

useModal

导航钩子

useNavigation

配置钩子

useB3Config

钩子组合

自定义钩子示例

TypeScript 支持

错误处理

下一步