Sui 生态 DApp 接入指南：通过 UI 组件连接钱包与执行交易

本文详细介绍了如何利用官方提供的 UI 组件，为你的 Sui 生态去中心化应用（DApp）快速集成钱包连接、消息签名及交易广播等功能。无论你的 DApp 运行在 Telegram 内还是独立 Web 环境，均可通过简洁的界面与用户钱包安全交互。

前置准备

在开始接入前，请确保用户的 OKX App 已更新至 6.90.1 或更高版本，这是使用 UI 组件功能的最低要求。

若你选择通过 npm 集成，可使用以下方式安装 OKX Connect 依赖。

初始化 UI 组件

首先需创建一个 UI 界面对象，用于后续发起连接、签名及交易等操作。初始化方法如下：

OKXUniversalConnectUI.init(dappMetaData, actionsConfiguration, uiPreferences, language)

初始化参数说明

• dappMetaData (object): 你的 DApp 基本信息

  • name (string): 应用名称（非唯一标识）
  • icon (string): 应用图标 URL。推荐使用 180x180px 的 PNG 格式，不支持 SVG。

• actionsConfiguration (object): 交互行为配置

  • modals (array | 'all'): 交易提醒界面模式，可选 'before'（操作前）、'success'（成功时）、'error'（出错时），默认为 'before'
  • returnStrategy (string): 针对 App 钱包，指定用户签署或拒绝请求后的返回策略。在 Telegram 环境中可设为 tg://resolve
  • tmaReturnUrl (string): Telegram Mini Wallet 的返回策略，可选 'back'（关闭钱包并返回 DApp）、'none'（无操作），默认为 'back'

• uiPreferences (object): 界面显示偏好

  • theme: 主题模式，可选 THEME.DARK、THEME.LIGHT 或 "SYSTEM"（跟随系统）
• language (string): 界面语言，支持中英等二十余种选项，默认为 "en_US"

初始化完成后，将返回一个 OKXUniversalConnectUI 实例供后续使用。

连接钱包

获取用户钱包地址是标识身份和签名交易的基础。通过以下方法打开连接模态框：

okxUniversalConnectUI.openModal(connectParams);

连接参数详解

• connectParams (object): 连接参数对象

  • namespaces (object): 必选的命名空间信息。Sui 对应的 key 为 "sui"。若任一请求的链不被支持，连接将被拒绝。

    • chains (string[]): 链 ID 列表

  • optionalNamespaces (object): 可选的命名空间信息。Sui 的 key 同样为 "sui"，即使某些链不支持，连接仍可继续。

    • chains (string[]): 链 ID 列表

  • sessionConfig (object): 会话配置

    • redirect (string): 连接成功后的跳转链接。Telegram Mini App 中可设置为 "tg://resolve"

该方法返回一个 Promise，解析后包含会话主题、账户地址、支持的链与方法等详细信息。

👉 查看完整的链 ID 列表和支持方法

连接并签名

此方法可在连接钱包的同时请求对数据进行签名，签名结果将通过 "connect_signResponse" 事件回调。

其请求参数与普通连接基本一致，但需额外传递一个 signRequest 数组（最多支持一个方法），用于指定签名方法（Sui 支持 "sui_signMessage" 和 "sui_signPersonalMessage"）及相关参数。

连接状态管理与交易准备

检查连接状态

使用内置方法可判断当前是否有已连接的钱包，返回一个布尔值。

断开连接

断开当前钱包连接并删除会话。若需切换钱包，请先执行断开操作。

创建交易提供者

在进行交易操作前，需创建一个 OKXSuiProvider 对象，并将之前初始化的 okxUniversalConnectUI 实例传入构造函数。

账户与签名操作

获取账户信息

通过 suiProvider.getAccount() 可获取当前连接账户的地址和公钥（需要 App 6.92.0+ 支持）。

签名消息

Sui 支持两种消息签名方法：

• 签名 Message (sui_signMessage): 接收 Uint8Array 格式消息，返回签名及原始消息字节。
• 签名 Personal Message (sui_signPersonalMessage): 同样接收 Uint8Array，返回签名及字节。

签名与广播交易

• 签名交易：返回交易的签名和字节数据。
• 签名并广播交易：在签名的同时将交易广播上链，返回交易哈希、字节及本地执行确认状态。

事件与错误处理

UI 组件的事件系统与错误码体系同 EVM 兼容链保持一致，具体可参考相关文档。

常见问题

问：我的 DApp 在 Telegram 中运行时，用户可以选择哪些钱包？

答：在 Telegram 环境中，用户可选择唤起手机上的 OKX App 钱包，或直接使用内置的 Telegram Mini 钱包进行连接和操作，体验无缝流畅。

问：初始化时图标不显示该怎么办？

答：请确保提供的图标 URL 指向的是 PNG 或 ICO 格式的图片，且尺寸推荐为 180x180px。SVG 格式目前不被支持。

问：如何处理用户拒绝连接或签名的情况？

答：所有拒绝操作都会通过模态框或事件回调返回错误信息，开发者可根据错误码做相应的用户提示和流程处理。

问：可以同时请求连接多条链吗？

答：可以。通过在 namespaces 或 optionalNamespaces 的 chains 数组中添加多个链 ID，即可同时请求连接多条链。

问：交易广播后如何获取确认结果？

答：签交易并广播上链 方法返回的 Promise 会解析出包含交易摘要 (digest) 的对象，你可通过区块链浏览器查询该交易的确认状态。

通过以上步骤，你应该已经掌握了使用 UI 组件为 Sui DApp 集成钱包功能的核心流程。👉 获取更多高级配置和最佳实践