EVM 兼容链 UI 接入指南：一步集成 DEX 钱包与 Mini 钱包

Web3 时代，用户期待的是无摩擦的链上体验。本指南围绕“EVM 兼容链、DEX API、Web3 钱包、Mini 钱包以及 Telegram Mini App”六大关键词，手把手演示如何通过官方 UI 套件，把完整的 连接钱包、签名、交易 流程嵌入 DApp 或 Telegram Mini App。无须重复造轮子，最快 10 分钟，让你的前端拥有专业级 Web3 交互。

快速开始：npm 安装

打开终端，切入项目根目录，一行命令即可：

npm install @okx/web3-connect-ui

安装完成后，所有 UI 弹窗、签名页、交易确认动画都由 SDK 接管，你只需关注业务逻辑。

核心对象初始化

初始化是“扫清障碍”的关键一步。DAppMetaData、ActionsConfiguration、uiPreferences、language 四个配置项决定整个交互风格。

最小可运行示例

import { OKXUniversalConnectUI, THEME } from '@okx/web3-connect-ui';

const universalUi = new OKXUniversalConnectUI({
  DAppMetaData: {
    name: 'MyNFTMarket',       // 应用名称
    icon: 'https://example.com/icon180x180.png' // 仅支持 PNG/ICO，推荐 180x180
  },
  actionsConfiguration: {
    modals: ['before', 'success'], // 在“交易确认、成功”两步弹窗
    returnStrategy: 'none',        // Deep-link 返回策略
    tmaReturnUrl: 'back'           // Telegram Mini App 专用：签名完返回应用
  },
  uiPreferences: {
    theme: THEME.SYSTEM            // DARK | LIGHT | SYSTEM
  },
  language: 'zh_CN',
  restoreConnection: true           // 自动恢复上一次会话
});

👉 查看生产级配置示例与 5 分钟上手指南

连接钱包

调用 openModal() 弹出可选钱包列表，用户点一下即可授权，返回值包含地址、链、会话 ID 等全部后续所需信息。

必需参数

namespaces.eip155 — 面向 EVM 兼容链的专属字段
chains — 链 ID 数组，例：["eip155:1", "eip155:56"]
rpcMap — 节点 RPC 地址映射，例：{"1":"https://eth.llamarpc.com"}

完整呼叫方式

await universalUi.openModal({
  namespaces: {
    eip155: {
      chains: ['eip155:1', 'eip155:137'],
      defaultChain: 'eip155:1',
      rpcMap: {
        '1': 'https://eth.llamarpc.com',
        '137': 'https://poly.llamarpc.com'
      }
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ['eip155:10'], // 作为可选网络，用户钱包没有也能连接
      rpcMap: { '10': 'https://opt.llamarpc.com' }
    }
  }
});

成功后 SDK 会返回 topic、chains、accounts、methods、defaultChain 等字段，可直接缓存到 localStorage 里，后续请求即可免填链参数。

👉 获取极速集成模板，复制就上线

一步到位：连接并签名

如果你想把“连接 + 签名”压缩成一次交互，调用 openModalAndSign() 即可。场景举例：用户首次登录就顺带完成「Sign‐In with Ethereum」。

const res = await universalUi.openModalAndSign(
  {
    namespaces: {
      eip155: {
        chains: ['eip155:1'],
        defaultChain: 'eip155:1'
      }
    }
  },
  [
    {
      method: 'personal_sign',
      chainId: 'eip155:1',
      params: ['0x48656C6C6F2057656233', '0xYourAddress']
    }
  ]
);

签名结果透传 connect_signResponse 事件，可直接取出 signature。

交易流程拆分：预签名 + 发送

大部分 DeFi 或 GameFi 交易分两步：

Trx 预处理：主线程准备交易体
钱包弹窗：用户在钱包确认签名并广播

SDK 把这两步封装成：

const txHash = await universalUi.request({
  chain: 'eip155:137',
  method: 'eth_sendTransaction',
  params: [
    {
      from: '0xSigner',
      to: '0xReceiver',
      data: '0x...'
    }
  ]
});

若只需签名不上链，把 method 换成 eth_signTransaction 即可。

多语言、主题即时切换

已经初始化的实例同样支持动态更新：

universalUi.setTheme(THEME.DARK);
universalUi.setLanguage('zh_CN');

两秒生效，无需刷新页面。

断点重连与会话守护

restoreConnection: true — 页面刷新后自动续上旧会话
getSession() — 轮询获取当前会话
disconnect() — 显式清理本地 & 钱包端会话

这样用户做二次进入或重新授权时，体验不会有割裂感。

监听与错误处理

SDK 提供标准事件体系：

connectionStatusChange — 监听连接态
connect_signResponse — 监听签名完成
OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR — 用户拒绝弹窗

示例：

universalUi.on('connectionStatusChange', connected => {
  console.log('钱包连接状态：', connected);
});

常见错误码速查

错误码	含义
UNKNOWN_ERROR	未知故障
ALREADY_CONNECTED_ERROR	重复连接
CHAIN_NOT_SUPPORTED	当前链不被钱包支持
WALLET_NOT_SUPPORTED	钱包类型不在白名单

FAQ

Q1：Telegram Mini App 能否直接使用桌面钱包？
能！当用户设备没装手机 App 时，SDK 还会弹出浏览器插件或钱包扩展选项。

Q2：自定义网络不在官方列表怎么办？
把 "wallet_addEthereumChain" 写进 optionalNamespaces 并配置 rpcMap，首次会提示用户添加新链。

Q3：可以同时支持以太坊主网与 BSC 吗？
只要在 chains 数组里写 "eip155:1" 与 "eip155:56"，SDK 会自动聚合全签。

Q4：如何彻底移除监听？
调出 universalUi.removeAllListeners() 即可。

Q5：为什么 tmaReturnUrl: back 设置无效？
确认 DApp 是否为 Telegram Mini App；如果指向的地址非 HTTPS，部分 WebView 会拦截 Deep-Link。

Q6：升级 SDK 会破坏存量会话吗？
不会，但建议用户主动调用一次 disconnect 再重连，以充分享受新版本特性。

端到端小结

npm install 完毕
new OKXUniversalConnectUI() 一次配置
openModal() or openModalAndSign() 一步完成连接（含签名）
request() 按需发交易
监听、主题、多语言、自定义网络 — 随时掌控

按此路径，开发者就能把 DApp、DeFi、DEX 或 GameFi 产品，在手机 App、桌面钱包、Telegram Mini App 三大场景里实现 统一 UI、一致体验、同步会话 的 Web3 钱包接入。