全面指南：使用 UI 组件快速接入 EVM 兼容链与 Web3 钱包

在 Web3 应用开发中，除了 SDK 之外，提供直观的用户界面（UI）组件可以大幅简化钱包集成流程。本文将详细介绍如何利用 UI 组件，帮助用户无缝连接 App 或 Mini 钱包，并高效接入 EVM 兼容链。

为什么选择 UI 组件接入？

对于运行在 Telegram 等环境内的 DApp，UI 组件提供了更灵活的钱包连接方式：用户既可选择唤起外部 App 钱包，也可直接在 Telegram 内使用 Mini 钱包完成操作。这种方式降低了用户的使用门槛，同时保持了开发的高度可控性。

环境安装与初始化

通过 npm 安装

使用 npm 可以方便地安装所需的 UI 包，具体命令请参照官方文档。

初始化配置

在连接钱包前，需要初始化一个连接对象，用于后续操作。以下是关键配置参数：

• DAppMetaData（对象）：

  • name（字符串）：应用名称，仅用于展示。
  • icon（字符串）：应用图标的 URL，需为 PNG 或 ICO 格式（不支持 SVG），建议尺寸 180x180px。

• actionsConfiguration（对象）：

  • modals：定义交易提醒界面的展示模式，可选 'before'、'success'、'error' 或 'all'，默认为 'before'。
  • returnStrategy：针对 App 钱包，设置用户操作后的返回策略（如 tg://resolve）。
  • tmaReturnUrl：Mini 钱包的返回策略，常用 'back'（操作后关闭钱包并返回 DApp）。

• uiPreferences（对象）：

  • theme：主题设置，支持深色、浅色或系统默认。
  • language：界面语言，默认为英文。
• restoreConnection（布尔值）：是否自动恢复之前的连接。

初始化完成后，将返回一个 OKXUniversalConnectUI 对象，用于后续操作。

连接钱包与签名操作

发起钱包连接

通过 openModal 方法请求连接，获取钱包地址和必要的会话信息：

await universalUi.openModal(connectParams);

参数说明：

• namespaces：必需命名空间，EVM 链使用 "eip155"。若请求链不被支持，连接将被拒绝。
• chains：链 ID 列表（如以太坊为 "eip155:1"）。
• defaultChain：可选默认链。
• rpcMap：RPC 配置，仅支持 EVM 链，且需包含在 chains 中。
• optionalNamespaces：可选命名空间，用于支持自定义网络。

返回值包含会话主题、账户信息、支持方法及默认链等数据。

连接并签名

openModalAndSign 方法可在连接的同时请求签名：

await universalUi.openModalAndSign(connectParams, signRequest);

除连接参数外，需指定签名方法（如 "personal_sign"）和对应参数。

连接状态与交易管理

检查钱包连接状态

使用内置方法可快速判断当前是否有活跃的钱包连接，返回布尔值。

发送交易与签名

通过 request 方法向钱包发送交易或签名请求：

参数包括：

• method：方法名（如交易或签名）。
• params：方法参数。
• chain：执行链（建议显式指定）。
• actionConfigurationRequest：交易提醒和返回策略配置。

返回值与 EVM 兼容链的交易签名结果一致。👉 查看实时交易工具

高级功能与配置

自定义 RPC 调用

若标准方法无法满足需求，可通过配置 rpcMap 实现更灵活的 RPC 调用，仅支持 EVM 系链。

会话与事件管理

• 获取会话信息：查询当前连接的钱包详情。
• 事件监听：监听连接弹窗状态变化，及时更新界面。
• 断开连接：主动终止钱包会话。

UI 与网络设置

• 动态配置：支持运行时修改主题、语言等界面元素。
• 设置默认网络：在多网络环境下指定默认操作链。

错误处理与常见问题

错误码说明

操作中可能返回的错误码包括：

• UNKNOWN_ERROR：未知异常。
• ALREADY_CONNECTED_ERROR：钱包已连接。
• USER_REJECTS_ERROR：用户拒绝请求。
• CHAIN_NOT_SUPPORTED：链不支持。
• 其他常见错误如方法不支持、连接异常等。

常见问题

1. 如何选择适合的返回策略？

• 在 Telegram Mini 钱包中，建议使用 'back' 实现无缝返回；外部 App 可配置自定义深度链接。

2. 支持哪些签名方法？

• EVM 链目前支持 personal_sign，后续将扩展更多方法。

3. 初始化失败可能的原因？

• 检查图标格式（必须为 PNG/ICO）和 RPC 配置的链是否匹配。

4. 如何处理用户拒绝连接？

• 捕获 USER_REJECTS_ERROR 并提示用户授权必要性。

5. 能否同时连接多个链？

• 是的，通过在 chains 数组中指定多链实现。

6. 如何自定义界面语言？

• 初始化或通过 setUiConfiguration 设置 language 字段（如 "zh_CN"）。

结语

通过 UI 组件接入 EVM 兼容链和 Web3 钱包，不仅提升了用户体验，还降低了开发复杂度。合理运用初始化和配置参数，结合高效的错误处理，可以快速构建稳健的 DApp 连接方案。👉 探索更多接入策略