移动端与桌面端

ONE SDK (@one_deploy/sdk v1.1.0) 提供两个入口，具有不同的组件可用性。两个平台共享相同的 hook 和 engine client，但 UI 组件在 Web 和 React Native 之间有显著差异。

平台入口

入口	导入路径	平台
Web	`@one_deploy/sdk`	浏览器 (React DOM)
React Native	`@one_deploy/sdk/react-native`	iOS / Android (React Native)

Web 组件

Web 入口导出完整的预构建 widget 组件集：

// 全部可从 '@one_deploy/sdk' 获取
import {
  // Wallet
  OneConnectButton,
  OneConnectButtonSimple,
  OneConnectButtonFull,
  OneWalletBalance,
  OneBalanceDisplay,
  OneSendWidget,
  OneSendETHWidget,
  OneSendUSDCWidget,
  OneReceiveWidget,
  OneTransactionButton,
  OneSendETHButton,
  OneApproveButton,

  // Payments
  OnePayWidget,
  OneOnrampWidget,
  OneOfframpWidget,
  OneSwapWidget,
} from '@one_deploy/sdk';

Web 组件完整列表

分类	组件	描述
连接	`OneConnectButton`	支持社交登录的钱包连接
	`OneConnectButtonSimple`	极简连接按钮预设
	`OneConnectButtonFull`	功能完整的连接按钮预设
余额	`OneWalletBalance`	实时钱包余额显示
	`OneBalanceDisplay`	基于数据的静态余额显示
发送	`OneSendWidget`	完整的发送表单
	`OneSendETHWidget`	ETH 发送预设
	`OneSendUSDCWidget`	USDC 发送预设
接收	`OneReceiveWidget`	二维码和地址显示
按钮	`OneTransactionButton`	通用交易执行器
	`OneSendETHButton`	ETH 发送按钮
	`OneApproveButton`	ERC-20 授权按钮
支付	`OnePayWidget`	统一支付 widget
	`OneOnrampWidget`	法币转加密货币入金
	`OneOfframpWidget`	加密货币转法币出金
	`OneSwapWidget`	代币兑换 widget

React Native 组件

React Native 入口仅导出 AI 交易和外汇组件。钱包和支付 widget 在 React Native 上不可用。

// 可从 '@one_deploy/sdk/react-native' 获取
import {
  // AI Trading
  OneAITradingDashboard,
  OneAgentCatalog,
  OneTradingPairSelector,
  OneBotConsole,

  // Forex
  OneForexDashboard,
  OneForexPoolCard,
  OneForexCapitalSplit,
  OneForexConsoleView,
  OneForexPairSelector,
  OneForexTradeHistory,

  // 工具函数（非组件）
  parseQRCode,
  generateShareContent,
} from '@one_deploy/sdk/react-native';

React Native 组件列表

分类	组件	描述
AI 交易	`OneAITradingDashboard`	投资组合和代理概览
	`OneAgentCatalog`	浏览和选择交易代理
	`OneTradingPairSelector`	选择交易对
	`OneBotConsole`	实时机器人活动控制台
外汇	`OneForexDashboard`	外汇投资概览
	`OneForexPoolCard`	单个资金池展示
	`OneForexCapitalSplit`	资金分配视图
	`OneForexConsoleView`	外汇交易控制台
	`OneForexPairSelector`	货币对选择
	`OneForexTradeHistory`	交易历史列表
工具函数	`parseQRCode`	解析二维码数据
	`generateShareContent`	生成可分享的钱包内容

两个平台共享的功能

Hook 和 engine client 在 Web 和 React Native 上的工作方式完全相同。

Hook

// 可从 '@one_deploy/sdk' 和 '@one_deploy/sdk/react-native' 获取
import {
  useOneClient,
  useWalletBalance,
  useTokenPrice,
  useAITradingPortfolio,
  useForexPools,
} from '@one_deploy/sdk'; // 或 '@one_deploy/sdk/react-native'

Engine Client

// engine client API 在两个平台上完全相同
import { useOneClient } from '@one_deploy/sdk';

function CrossPlatformExample() {
  const { engineClient } = useOneClient();

  const fetchData = async () => {
    // 这些方法在 Web 和 React Native 上都能工作
    const wallets = await engineClient.getUserWallets();
    const balances = await engineClient.getWalletBalance('0x...');
    const portfolio = await engineClient.getPortfolioSummary('0x...');
    const history = await engineClient.getWalletTransactions('0x...');
    const status = await engineClient.getTransactionStatus('tx-id');

    // sendTransaction 在两个平台上都能工作
    const tx = await engineClient.sendTransaction({
      fromAddress: '0x...',
      toAddress: '0x...',
      chainId: 8453,
      value: '0.1',
      currency: 'ETH',
    });
  };

  return null;
}

为什么要拆分？

ONE SDK 将 Web widget（Connect、Pay、Send、Receive、Swap、Onramp、Offramp）保持为仅限 Web，因为它们依赖于浏览器特定的 API（DOM、window、navigator.share、剪贴板 API）和基于 CSS 的布局。React Native 入口为 AI 交易和外汇提供原生移动组件，这是主要的移动端用例。

对于 React Native 上的钱包和支付流程，请直接使用 engine client 方法和 hook 来构建自定义原生 UI。

响应式布局指南

所有 ONE SDK Web 组件渲染为自包含的卡片大小 widget。它们不包含内置的响应式断点。这是有意为之——让你完全控制布局。

// widget 以其固有的卡片尺寸渲染
<OneSendWidget fromAddress="0x..." chainId={8453} />

由你控制容器

将 SDK widget 包裹在你自己的响应式容器中。Widget 会填充其父元素的宽度。

import { OneSendWidget } from '@one_deploy/sdk';

function ResponsiveSendPage() {
  return (
    <div
      style={{
        maxWidth: '480px',
        width: '100%',
        margin: '0 auto',
        padding: '16px',
      }}
    >
      <OneSendWidget
        fromAddress="0xYourWallet..."
        chainId={8453}
        onSuccess={(tx) => console.log(tx.transactionHash)}
      />
    </div>
  );
}

CSS Grid / Flexbox 布局

import {
  OneWalletBalance,
  OneSendWidget,
  OneReceiveWidget,
  CHAIN_IDS,
} from '@one_deploy/sdk';

function WalletDashboard({ address }: { address: string }) {
  return (
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: 'repeat(auto-fit, minmax(360px, 1fr))',
        gap: '24px',
        padding: '24px',
      }}
    >
      <div>
        <h3>Balance</h3>
        <OneWalletBalance
          walletAddress={address}
          chains={[CHAIN_IDS.BASE, CHAIN_IDS.ETHEREUM]}
          autoRefresh
        />
      </div>
      <div>
        <h3>Send</h3>
        <OneSendWidget
          fromAddress={address}
          chainId={CHAIN_IDS.BASE}
        />
      </div>
      <div>
        <h3>Receive</h3>
        <OneReceiveWidget
          walletAddress={address}
          chainId={CHAIN_IDS.BASE}
        />
      </div>
    </div>
  );
}

不内置断点

SDK 有意不提供响应式断点。原因如下：

框架无关 -- 你的应用可能使用 Tailwind、CSS modules、styled-components 或纯 CSS。SDK 不强制使用任何 CSS 框架。
布局控制 -- 由你决定 widget 是出现在侧边栏、弹窗、整页还是卡片网格中。
一致的尺寸 -- Widget 以约 360-480px 的宽度可预测地渲染，便于放置在任何布局中。

如果你需要响应式行为，请在容器层级实现：

/* 你应用的 CSS */
.wallet-widget-container {
  width: 100%;
  max-width: 480px;
  margin: 0 auto;
}

@media (min-width: 768px) {
  .wallet-widget-container {
    max-width: 420px;
  }
}

@media (min-width: 1200px) {
  .wallet-widget-container {
    max-width: 480px;
  }
}

import { OneSendWidget } from '@one_deploy/sdk';

function ResponsiveWrapper() {
  return (
    <div className="wallet-widget-container">
      <OneSendWidget fromAddress="0x..." chainId={8453} />
    </div>
  );
}

平台检测

如果你维护共享代码库，可根据平台条件导入：

// utils/platform.ts
import { Platform } from 'react-native';

export const isWeb = Platform.OS === 'web';
export const isMobile = Platform.OS === 'ios' || Platform.OS === 'android';

// 条件组件渲染
import { isWeb } from './utils/platform';

function WalletView({ address }: { address: string }) {
  if (isWeb) {
    // 动态导入仅限 Web 的组件
    const { OneWalletBalance } = require('@one_deploy/sdk');
    return <OneWalletBalance walletAddress={address} />;
  }

  // 在 React Native 上，直接使用 hook
  const { balances, totalBalanceUsd } = useWalletBalance({
    walletAddress: address,
  });

  return (
    <View>
      <Text>Total: ${totalBalanceUsd}</Text>
      {balances.map((b) => (
        <Text key={`${b.chainId}-${b.token}`}>
          {b.symbol}: {b.balance}
        </Text>
      ))}
    </View>
  );
}

总结

功能	Web	React Native
连接按钮	`OneConnectButton`	使用 engine client
余额显示	`OneWalletBalance`	`useWalletBalance` hook
发送 widget	`OneSendWidget`	`engineClient.sendTransaction()`
接收 widget	`OneReceiveWidget`	`generateShareContent()`
支付 widget	`OnePayWidget`、`OneOnrampWidget` 等	使用 engine client
AI 交易	不可用	`OneAITradingDashboard` 等
外汇	不可用	`OneForexDashboard` 等
Hook	所有 hook	所有 hook
Engine client	完整 API	完整 API
二维码解析	未导出	`parseQRCode()`

下一步

钱包概览 -- 核心钱包概念和 API。
连接按钮 -- 仅限 Web 的连接按钮详情。
二维码扫描 -- React Native 二维码解析工具。

平台入口​

Web 组件​

Web 组件完整列表​

React Native 组件​

React Native 组件列表​

两个平台共享的功能​

Hook​

Engine Client​

为什么要拆分？​

响应式布局指南​

SDK Widget 为卡片尺寸​

由你控制容器​

CSS Grid / Flexbox 布局​

不内置断点​

平台检测​

总结​

下一步​