在 SDK 之外，OKX 还提供了一套完整的 UI 界面解决方案，帮助开发者更便捷地集成钱包连接功能。通过 UI 连接方式，当 DApp 在 Telegram 环境中运行时，用户可以选择打开移动端 App 钱包，或直接使用内置的 OKX Mini Wallet，享受流畅的无缝体验。
无论您之前使用过 Ton Connect 还是 OKX Connect，都能快速上手本方案，有效降低开发成本，并支持同时处理多网络请求。
环境安装与初始化
通过 npm 安装
推荐使用 npm 进行安装，以便更好地管理依赖和版本更新。
初始化连接对象
在连接钱包之前，需要先创建 OKXTonConnectUI 对象，该对象将用于后续的 wallet 连接、交易发送等操作。
new OKXTonConnectUI(dappMetaData, buttonRootId, actionsConfiguration, uiPreferences, language, restoreConnection)请求参数说明
metaData - 对象类型，包含应用基本信息：
name- 字符串，应用名称（不用于唯一标识）。icon- 字符串，应用图标的 URL 地址。注意：仅支持 PNG、ICO 等格式，不支持 SVG；建议使用 180x180px 的 PNG 图标。
- buttonRootId - 字符串，用于绑定钱包连接按钮的 HTML 元素 ID。若不传递此参数，则不显示连接按钮。
actionsConfiguration - 对象，配置操作行为：
modals- 数组或字符串，定义交易过程中弹窗的显示时机，可选值：'before'、'success'、'error'或'all'。returnStrategy- 字符串，定义用户签名或拒绝请求后的深度链接返回策略。在 Telegram 中可配置为tg://resolve。tmaReturnUrl- 字符串，Telegram Mini Wallet 的返回策略，通常设为'back'（签名后自动返回 DApp），或'none'（无操作）。
uiPreferences - 界面偏好设置：
theme- 主题设置，可选THEME.DARK、THEME.LIGHT或'SYSTEM'。
- language - 语言设置，支持多种语言如
'zh_CN'（简体中文）、'en_US'（英文）等，默认为'en_US'。 - restoreConnection - 布尔值，是否自动恢复之前的连接。
返回值
- 返回
OKXTonConnectUI实例对象。
核心功能使用详解
监听钱包状态变化
钱包状态包括连接成功、恢复连接成功、断开连接等。您可以通过监听状态变化，及时获取最新状态。
const unsubscribe = okxTonConnectUI.onStatusChange((wallet) => {
if (wallet) {
// 连接成功
} else {
// 断开连接
}
});
// 取消监听
unsubscribe();连接钱包
连接钱包的目的是获取用户的钱包地址，该地址将作为用户标识和交易签名的必要参数。
如果初始化时设置了 buttonRootId，则连接按钮会自动处理点击事件；否则，需要手动调用连接方法：
await okxTonConnectUI.openModal();设置 tonProof 参数
若需要设置 tonProof 签名参数，可在参数准备期间将状态设为 'loading'，准备好后更新为 'ready' 并传入具体数值。也可通过 setConnectRequestParameters(null) 移除加载状态。
获取当前连接的钱包信息
通过以下方法可获取当前是否已连接钱包，以及连接的钱包详细信息：
const walletInfo = okxTonConnectUI.wallet;断开连接
await okxTonConnectUI.disconnect();发送交易
使用 sendTransaction 方法向钱包发送交易请求：
const result = await okxTonConnectUI.sendTransaction(transaction, actionConfigurationRequest);请求参数
transaction- 交易对象，具体参数与OKXTonConnect.sendTransaction相同。actionConfigurationRequest- 操作配置：modals- 弹窗显示模式，默认为'before'。returnStrategy- 深度链接返回策略。tmaReturnUrl- Telegram Mini Wallet 返回策略。
返回值
- 返回 Promise，解析结果为
{ boc: string }形式的签名结果。
设置 UI 配置项
支持动态修改主题、语言等配置，也可在初始化时直接设置：
okxTonConnectUI.setUIConfiguration({ theme: THEME.DARK, language: 'zh_CN' });事件监听与错误处理
事件监听
OKX Ton Connect UI 提供多种事件通知，DApp 可根据需要监听并处理相应逻辑：
| 事件名称 | 触发时机 |
|---|---|
OKX_UI_CONNECTION_STARTED | 用户开始连接钱包时 |
OKX_UI_CONNECTION_COMPLETED | 用户成功连接钱包时 |
OKX_UI_CONNECTION_ERROR | 用户取消连接或连接过程中出现错误时 |
OKX_UI_CONNECTION_RESTORING_STARTED | DApp 开始恢复连接时 |
OKX_UI_CONNECTION_RESTORING_COMPLETED | DApp 成功恢复连接时 |
OKX_UI_CONNECTION_RESTORING_ERROR | DApp 恢复连接失败时 |
OKX_UI_DISCONNECTION | 用户开始断开钱包连接时 |
OKX_UI_TRANSACTION_SENT_FOR_SIGNATURE | 用户发送交易请求签名时 |
OKX_UI_TRANSACTION_SIGNED | 用户成功签名交易时 |
OKX_UI_TRANSACTION_SIGNING_FAILED | 用户取消签名或签名过程中出现错误时 |
示例代码
okxTonConnectUI.on('OKX_UI_CONNECTION_COMPLETED', (data) => {
// 处理连接成功逻辑
});错误代码
在连接、交易、断开连接等过程中，可能会抛出以下异常：
| 错误代码 | 描述 |
|---|---|
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR | 未知错误 |
OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR | 钱包已连接 |
OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR | 钱包未连接 |
OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR | 用户拒绝操作 |
OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED | 方法不支持 |
OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED | 链不支持 |
OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED | 钱包不支持 |
OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR | 连接错误 |
常见问题
如何选择使用 SDK 还是 UI 方案？
UI 方案提供了现成的界面组件，适合快速集成和标准化需求；SDK 则提供更多自定义灵活性。如果您的 DApp 在 Telegram 内运行，UI 方案能直接支持 OKX Mini Wallet，体验更佳。
是否支持多链同时连接？
是的，OKX Ton Connect UI 支持同时处理多个网络请求，您可以在初始化时配置相应的参数。
用户断开连接后，如何重新连接？
系统会自动处理连接状态的恢复，您也可以通过设置 restoreConnection: true 实现自动重连。
交易过程中用户取消签名，会抛出什么错误？
用户取消签名时，系统会抛出 OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR 错误，您可以通过捕获该异常进行相应处理。
如何自定义连接按钮的样式？
如果使用内置连接按钮，可以通过 CSS 覆盖默认样式； alternatively，您可以不设置 buttonRootId，然后自定义按钮并手动调用 openModal() 方法。
是否支持深色模式？
是的，通过设置 uiPreferences: { theme: THEME.DARK } 即可启用深色模式，也支持跟随系统主题。
通过本指南，您应能全面了解 OKX Ton Connect UI 的集成与使用方法。无论是初次接触还是从其他方案迁移，都能快速实现安全、高效的钱包连接功能。