TON DEX 钱包 UI 接入指南：用 OKXTonConnectUI 一件集成 App 与 Mini Wallet

想让你的去中心化交易所 (DEX) 在 Telegram 内无需跳出即可连接钱包？或者同时支持打开移动端 App 钱包？
OKXTonConnectUI 为 TON 生态开发者提供了一套即插即用的 UI 方案，只需几句代码即可完成 Ton Connect、OKX Mini Wallet 的多端整合，并自带深色/浅色主题与19种语言切换。

核心特点速览

一键安装：npm 一行命令
零侵入式组件：保留开发者原有交互逻辑
Telegram Mini Wallet & App Wallet 双通路：用户自己选
生命周期完备：连上、断开、恢复连接自动监听
tonProof 无缝支持：绕过签名再次出现
全端事件推送：连接开始、签名完成、交易结束均有回调

1. 三分钟完成安装与初始化

npm install @okxconnect/ton-ui

新建 UI 对象

import { OKXTonConnectUI, THEME } from '@okxconnect/ton-ui';

const okxTonConnectUI = new OKXTonConnectUI(
  {
    name: 'My Awesome TON DEX',
    icon: 'https://example.com/icon-180x180.png' // PNG/ICO 支持，SVG 暂不支持
  },
  'connect-btn', // HTML 按钮 id，可省略
  {
    modals: ['before', 'success', 'error'],
    tmaReturnUrl: 'back' // Telegram Mini Wallet 签完后是否自动返回
  },
  {
    theme: THEME.DARK
  },
  'zh_CN',
  true // restoreConnection：页面刷新后自动恢复
);

<button id="connect-btn">连接钱包</button>

保持 UI 简洁的同时，不丢任何关键安全性——tonProof 与深链接策略均被隐藏在几十行配置里。

2. 状态监听：连接、断开、续接实时感知

OKXTonConnectUI 使用发布-订阅模型，仅需一次订阅即可持续收到事件。

const unsubscribe = okxTonConnectUI.onStatusChange(
  (walletAndWalletInfo) => {
    if (walletAndWalletInfo) {
      console.log('钱包已连接:', walletAndWalletInfo);
    } else {
      console.log('钱包已断开');
    }
  }
);

// 不再监听时
unsubscribe();

如需做 二次引导，你也可以调用：
👉 立即体验零代码连接示例

3. 发起交易：签字一步完成

const transaction = {
  validUntil: Math.floor(Date.now() / 1000) + 600,
  messages: [
    {
      address: 'EQBfBWT7X2BHg9tXAx6z9...', // 合约地址
      amount: '100000000' // 0.1 TON
    }
  ]
};

const result = await okxTonConnectUI.sendTransaction(transaction, {
  modals: 'all',
  returnStrategy: 'none'
});

console.log('交易签名成功, boc:', result.boc);

returnStrategy 决定用户签完是否自动跳回；默认 none，Telegram 场景可改为 tg://resolve
modals 能控制加载/成功/失败的提示弹窗

4. 设置 tonProof：提升安全性

当 DEX 需要链下身份凭证时，可在连接前配置：

okxTonConnectUI.setConnectRequestParameters({
  state: 'ready',
  value: {
    tonProof: 'hex_signature_here'
  }
});

// 取消 loading 或无需签名
// okxTonConnectUI.setConnectRequestParameters(null);

5. 主题与国际化：19 种语言 + 暗黑模式自由切换

无论何时调用，都能动态热切换：

okxTonConnectUI.ui.setTheme(THEME.SYSTEM); // 跟随系统
okxTonConnectUI.ui.setLanguage('vi_VN');   // 越南语上线

6. 错误对照表：异常快速定位

错误码	场景说明
UNKNOWN_ERROR	发生意外
ALREADY_CONNECTED_ERROR	重复调用连接
USER_REJECTS_ERROR	用户取消签名 / 拒绝授权
CHAIN_NOT_SUPPORTED	合约指向非 TON 链
WALLET_NOT_SUPPORTED	用户选中的钱包不在白名单

常见问题 FAQ

Q1：如果我已集成 Ton Connect，还要改多少代码？
A：几乎不改。只要把 SDK 换成本包的 OKXTonConnectUI，参数一一对应即可，逻辑不变。

Q2：能不能让用户永远留在 Telegram 不跳出 App？
A：在初始化配置里把 tmaReturnUrl 设为 none，并在 Telegram Mini Wallet 内完成签名即可全程闭环。

Q3：icon 大小为什么是 180x180？如果我用 512x512 会报错吗？
A：不会报错，但加载更慢。180×180 兼顾清晰度与体积，兼顾核心关键词：TON 轻量级钱包。

Q4：怎样支持夜间模式跟随手机？
A：把 theme: THEME.SYSTEM 传给初始化配置，UI 会自动读取 dark-mode 样式。

Q5：可以监听用户取消签名吗？
A：监听 OKX_UI_TRANSACTION_SIGNING_FAILED 即可获取取消事件。

Q6：恢复连接会影响首屏速度吗？
A：不会。restoreConnection 在后台静默完成，钱包地址返回时才触发回调，无痕体验。

场景案例：从「浏览群聊」到「完成一笔互换」

用户在 Telegram 群内点击 DEX 卡片迷你应用，场景：TON 行情讨论
弹窗双选项「留在 Telegram」或「打开 OKX App Wallet」——共通 UI
保持 tonProof 身份，1秒内返回如愿以偿的授权信息
签名发币：调用 sendTransaction，到账即弹绿色勾 ✅
后续上新币：一句 setLanguage('vi_VN') 适配越南社区

👉 查看完整流程的互动 Demo

小结

OKXTonConnectUI 让你用最少代码、最短路径，实现 TON、DEX、钱包 UI 三位一体的丝滑体验。从安装到上线，全程 30 分钟起跳，欢迎开发者立即对接。