📦 安装

npm install @agent-widget/react
# 或
yarn add @agent-widget/react
# 或
pnpm add @agent-widget/react

🚀 基本使用方法

1. 最简单的使用

import { AgentProvider, ChatWidget } from '@agent-widget/react';
import '@agent-widget/react/styles'; // 导入编译好的样式（必须）

function App() {
  return (
    <AgentProvider appRuntimeUrl="http://your-api-endpoint.com/api/v1/chat/stream">
      <ChatWidget />
    </AgentProvider>
  );
}

2. 完整配置使用

import { AgentProvider, ChatWidget } from '@agent-widget/react';
import '@agent-widget/react/styles';

function App() {
  return (
    <AgentProvider appRuntimeUrl="http://your-api-endpoint.com/api/v1/chat/stream">
      <ChatWidget
        locale="cn"        // 语言：'cn' | 'en'
        theme="dark"       // 主题：'dark' | 'light'
        floating={true}    // 是否悬浮模式
        width="800px"      // 宽度（悬浮模式）
        height="90vh"      // 高度（悬浮模式）
        welcomeMessage="您好！我是您的AI助手" // 欢迎消息
        suggestedPrompts={[  // 建议提示词
          { tag: "查询代币", text: "查询SOL价格" },
          { tag: "查看余额", text: "显示我的钱包余额" }
        ]}
        context={{         // 上下文数据
          walletAddress: "0x..."
        }}
      />
    </AgentProvider>
  );
}

3. 非悬浮模式（嵌入到容器中）

function App() {
  return (
    <div style={{ width: '100%', height: '600px' }}>
      <AgentProvider appRuntimeUrl="http://your-api-endpoint.com/api/stream">
        <ChatWidget floating={false} />
      </AgentProvider>
    </div>
  );
}

🎯 事件系统

组件库提供了完整的双向事件系统，允许你监听组件内部事件，也可以向组件发送事件来控制其行为。

可监听的组件事件

这些是组件内部触发的事件，你可以监听它们来响应用户操作：

1. crypto_trade - 加密货币交易事件

crypto_trade 事件在用户提交交易表单时触发，支持买入和卖出操作。

import { useEffect } from 'react';
import { useAgent } from '@agent-widget/react';

function TradeHandler() {
  const { eventEmitter } = useAgent();

  useEffect(() => {
    const handleCryptoTrade = (data) => {
      console.log('交易请求:', {
        trade_action: data.trade_action,    // 'buy' 或 'sell'
        target_token: data.target_token,    // 目标代币地址
        chain: data.chain,                  // 链名称
        amount: data.amount,                // 交易数量
        slippage: data.slippage,            // 滑点
        priority_fee: data.priority_fee,    // 优先级费用
        tip_fee: data.tip_fee,              // 小费
        auto_fee: data.auto_fee,            // 是否自动费用
        max_auto_fee: data.max_auto_fee,    // 最大自动费用
        is_anti_mev: data.is_anti_mev,      // 是否防MEV
        custom_rpc: data.custom_rpc         // 自定义RPC
      });
      // 执行交易逻辑...
    };

    eventEmitter.on('crypto_trade', handleCryptoTrade);
    return () => eventEmitter.off('crypto_trade', handleCryptoTrade);
  }, [eventEmitter]);

  return null;
}

数据类型：

interface CryptoTradeEventData {
  trade_action: 'buy' | 'sell';     // 交易动作
  target_token: string;             // 目标代币地址
  chain: string;                    // 链名称
  amount: string;                   // 交易数量
  slippage: string;                 // 滑点容忍度
  priority_fee: number;             // 优先级费用
  tip_fee: number;                  // 小费
  auto_fee: 0 | 1;                  // 是否自动费用
  max_auto_fee: string;             // 最大自动费用
  is_anti_mev: 0 | 1 | 2;           // 是否防MEV
  custom_rpc?: string;              // 自定义RPC URL
}

2. token_info - 代币详情事件

token_info 事件在用户点击代币卡片或查询代币详情时触发。

const handleTokenInfo = (data) => {
  console.log('代币详情查询:', {
    chain: data.chain,
    token_address: data.token_address
  });
  // 查询并显示代币详细信息...
};

eventEmitter.on('token_info', handleTokenInfo);

数据类型：

interface TokenInfoEventData {
  chain: string;        // 链名称
  token_address: string; // 代币合约地址
}

3. crypto_send - 代币发送事件

crypto_send 事件在用户提交代币转账表单时触发。

const handleCryptoSend = (data) => {
  console.log('代币转账:', {
    chain: data.chain,
    token_address: data.token_address,
    to_wallet_address: data.to_wallet_address,
    amount: data.amount
  });
  // 执行转账逻辑...
};

eventEmitter.on('crypto_send', handleCryptoSend);

数据类型：

interface CryptoSendEventData {
  chain: string;           // 链名称
  token_address: string;   // 代币合约地址
  to_wallet_address: string; // 目标钱包地址
  amount: string;          // 转账数量
}

4. crypto_convert - 代币转换事件

crypto_convert 事件在用户提交代币兑换表单时触发。

const handleCryptoConvert = (data) => {
  console.log('代币兑换:', {
    chain: data.chain,
    from_token_address: data.from_token_address,
    to_token_address: data.to_token_address,
    amount: data.amount
  });
  // 执行代币兑换逻辑...
};

eventEmitter.on('crypto_convert', handleCryptoConvert);

数据类型：

interface CryptoConvertEventData {
  chain: string;              // 链名称
  from_token_address: string; // 源代币地址
  to_token_address: string;   // 目标代币地址
  amount: string;             // 兑换数量
}

5. my_wallet - 钱包事件

my_wallet 事件在用户点击钱包详情按钮时触发。

const handleMyWallet = (data) => {
  console.log('钱包详情:', {
    chain: data.chain,
    wallet_address: data.wallet_address
  });
  // 显示钱包详细信息...
};

eventEmitter.on('my_wallet', handleMyWallet);

数据类型：

interface MyWalletEventData {
  chain: string;        // 链名称
  wallet_address: string; // 钱包地址
}

💼 WalletBalancesCard 功能

钱包余额卡片提供了丰富的交互功能：

点击代币行查看详情

用户可以点击任意代币行来触发 token_info 事件，获取该代币的详细信息。

复制代币地址

每个代币行左侧都有一个复制按钮，点击可复制代币合约地址到剪贴板。

钱包详情按钮

卡片底部的钱包图标按钮用于触发 my_wallet 事件，获取完整的钱包信息。

// 监听钱包余额卡片的交互
function WalletMonitor() {
  const { eventEmitter } = useAgent();

  useEffect(() => {
    // 监听代币信息查询
    const handleTokenInfo = (data: TokenInfoEventData) => {
      console.log('查看代币详情:', data);
      // 跳转到代币详情页面或显示详细信息
    };

    // 监听钱包详情查询
    const handleMyWallet = (data: MyWalletEventData) => {
      console.log('查看钱包详情:', data);
      // 显示钱包的完整信息和交易历史
    };

    eventEmitter.on('token_info', handleTokenInfo);
    eventEmitter.on('my_wallet', handleMyWallet);

    return () => {
      eventEmitter.off('token_info', handleTokenInfo);
      eventEmitter.off('my_wallet', handleMyWallet);
    };
  }, [eventEmitter]);

  return null;
}

可发送给组件的事件

这些是你可以向组件发送的事件，用于控制组件行为或更新状态：

1. trade_status - 更新交易状态

用于通知组件交易的执行结果（成功或失败）。

import { useAgent } from '@agent-widget/react';

function TradeController() {
  const { eventEmitter } = useAgent();

  const sendTradeSuccess = () => {
    eventEmitter.emit('trade_status', {
      id: 'trade-123',              // 交易ID
      status: 1,                     // 1=成功, 0=失败
      tradeHash: '0xabc123...',      // 交易哈希
      fromAddress: 'So11111...',     // 源代币地址
      fromName: 'SOL',               // 源代币名称
      fromImageUrl: 'https://...',   // 源代币图标
      toAddress: 'EPjFWd...',        // 目标代币地址
      toName: 'USDC',                // 目标代币名称
      toImageUrl: 'https://...',     // 目标代币图标
      amount: '100',                 // 交易数量
      reason: '交易成功'              // 成功/失败原因
    });
  };

  const sendTradeFailure = () => {
    eventEmitter.emit('trade_status', {
      id: 'trade-456',
      status: 0,                     // 0=失败
      tradeHash: '0xdef456...',
      amount: '50',
      reason: '余额不足'              // 失败原因
    });
  };

  return (
    <div>
      <button onClick={sendTradeSuccess}>模拟成功</button>
      <button onClick={sendTradeFailure}>模拟失败</button>
    </div>
  );
}

数据类型：

interface TradeStatusData {
  id: string;              // 交易唯一ID（必填）
  status: 0 | 1;           // 状态：0=失败, 1=成功（必填）
  tradeHash: string;       // 交易哈希（必填）
  fromAddress?: string;    // 源代币地址
  fromName?: string;       // 源代币名称
  fromImageUrl?: string;   // 源代币图标URL
  toAddress?: string;      // 目标代币地址
  toName?: string;         // 目标代币名称
  toImageUrl?: string;     // 目标代币图标URL
  amount?: string;         // 交易数量
  reason?: string;         // 成功/失败原因说明
}

2. clear_chat - 清空聊天记录

清空所有聊天消息。

import { useAgent } from '@agent-widget/react';

function ClearButton() {
  const { eventEmitter } = useAgent();

  const handleClear = () => {
    eventEmitter.emit('clear_chat');
  };

  return <button onClick={handleClear}>清空聊天</button>;
}

完整示例：监听所有事件

import { useEffect } from 'react';
import { useAgent } from '@agent-widget/react';
import type {
  CryptoTradeEventData,
  TokenInfoEventData,
  CryptoSendEventData,
  CryptoConvertEventData,
  MyWalletEventData
} from '@agent-widget/react';

function EventMonitor() {
  const { eventEmitter } = useAgent();

  useEffect(() => {
    // 1. 监听交易相关事件
    const handleCryptoTrade = (data: CryptoTradeEventData) => {
      console.log('💰 Crypto Trade:', data);
      // 执行交易逻辑
    };

    // 2. 监听代币详情事件
    const handleTokenInfo = (data: TokenInfoEventData) => {
      console.log('ℹ️ Token Info:', data);
      // 查询代币信息
    };

    // 3. 监听代币发送事件
    const handleCryptoSend = (data: CryptoSendEventData) => {
      console.log('📤 Crypto Send:', data);
      // 执行转账逻辑
    };

    // 4. 监听代币转换事件
    const handleCryptoConvert = (data: CryptoConvertEventData) => {
      console.log('🔄 Crypto Convert:', data);
      // 执行兑换逻辑
    };

    // 5. 监听钱包事件
    const handleMyWallet = (data: MyWalletEventData) => {
      console.log('👛 My Wallet:', data);
      // 查询钱包详情
    };

    // 注册事件监听
    eventEmitter.on('crypto_trade', handleCryptoTrade);
    eventEmitter.on('token_info', handleTokenInfo);
    eventEmitter.on('crypto_send', handleCryptoSend);
    eventEmitter.on('crypto_convert', handleCryptoConvert);
    eventEmitter.on('my_wallet', handleMyWallet);

    // 清理函数
    return () => {
      eventEmitter.off('crypto_trade', handleCryptoTrade);
      eventEmitter.off('token_info', handleTokenInfo);
      eventEmitter.off('crypto_send', handleCryptoSend);
      eventEmitter.off('crypto_convert', handleCryptoConvert);
      eventEmitter.off('my_wallet', handleMyWallet);
    };
  }, [eventEmitter]);

  return null;
}