在开发 Aptos 生态的去中心化应用（DApp）时，选择合适的用户界面（UI）接入方案能极大提升用户体验。本文将详细介绍如何利用现成的 UI 组件，让用户能便捷地连接其 Web3 钱包，无论是移动端 App 还是集成在 Telegram 内的 Mini 钱包，并顺利进行后续的交互操作。
安装与环境初始化
开始之前，请确保您的开发环境已准备就绪。
- 若用户使用 OKX App，请确保其版本为 6.92.0 或更高。
- 您可以通过 npm 包管理器将 OKX Connect 集成到您的 DApp 项目中。
连接钱包前，首要步骤是创建一个 UI 界面对象。该对象将负责后续所有的钱包连接、交易发送等用户交互流程。
核心初始化参数
dappMetaData (object): 用于描述您的 DApp 信息。
name(string): 应用名称，仅用于展示，非唯一标识。icon(string): 应用图标的 URL 地址。建议使用 180x180px 的 PNG 格式图片，不支持 SVG。
actionsConfiguration (object): 配置交互行为。
modals: 定义交易过程中弹窗的展示时机，可选'before','success','error'数组或'all'，默认为'before'。returnStrategy: 针对 App 钱包，设置用户签署或拒绝请求后的返回策略。例如，在 Telegram 环境中可设置为tg://resolve。tmaReturnUrl: 专用于 Telegram Mini Wallet 的返回策略。可选'back'（关闭钱包并返回 DApp）、'none'（无操作）或自定义深度链接，默认为'back'。
uiPreferences (object): 设置 UI 偏好。
theme: 界面主题，可选THEME.DARK,THEME.LIGHT, 或"SYSTEM"（跟随系统）。language: 设置界面语言，支持多种语言代码如"zh_CN"（简体中文）、"en_US"（英文）等，默认为"en_US"。
初始化完成后，您将获得一个 OKXUniversalConnectUI 实例，用于后续操作。
连接钱包并获取账户
此步骤旨在与用户的钱包建立连接，并获取其钱包地址等关键信息，这是进行交易签名等操作的前提。
关键请求参数
namespaces (必需): 指定您要求 DApp 必须连接的区块链命名空间和网络。
- Aptos 生态的 key 为
"aptos"。 chains: 指定链 ID 数组。若钱包不支持其中任何一个链，连接将被拒绝。defaultChain(可选): 设置默认链。
- Aptos 生态的 key 为
- optionalNamespaces (可选): 指定希望连接的可选链信息。即使钱包不支持这些链，连接依然可以建立，参数格式同
namespaces。 sessionConfig: 会话配置。
redirect: 连接成功后的跳转链接。对于 Telegram Mini App，可设置为"tg://resolve"。
成功连接后，返回的 Promise 将解析为一个包含会话主题（topic）、连接的账户地址（accounts）、支持的链和方法等信息的对象。
连接钱包并同步请求签名
您可以在建立连接的同时，直接请求用户对一条消息进行签名，从而在一个流程内完成两项操作。
请求参数
此方法的参数是上述 connectParams 和一个额外的 signRequest 数组的组合。
signRequest: 定义签名请求，一次最多支持一个方法。
method: 指定请求的签名方法，Aptos 链支持"aptos_signMessage"。chainId: 执行此签名操作的链 ID，它必须包含在connectParams的namespaces中。params: 签名方法所需的具体参数。
签名结果将通过 "connect_signResponse" 事件回调返回。
核心功能操作
建立连接后，您可以利用 provider 对象执行一系列区块链交互操作。
检查钱包连接状态
通过调用相关方法，可以获取一个布尔值（boolean），快速判断当前是否有已连接的钱包会话。
获取钱包地址与公钥
传入指定的链 ID（如不传则使用连接的首个 Aptos 链），即可获取该链上当前账户的钱包地址（address）和公钥（publicKey）。
请求消息签名
请求用户对一条消息进行签名。您可以灵活配置签名消息的组成内容。
签名参数
message: 消息对象。
message(string): 需要被签名并展示给用户的核心消息内容。nonce(string): 应由 DApp 生成的随机数，用于防重放。address(boolean): 是否在完整消息中包含账户地址。application(boolean): 是否在完整消息中包含 DApp 的域名。chainId(boolean): 是否在完整消息中包含当前连接的链 ID。
- chain: 执行签名操作的链 ID，强烈建议明确传递此参数，尤其是在连接了多条链时。
成功后将返回签名结果，包含生成的完整消息（fullMessage）、原始消息、签名（signature）等信息。
签署并发送交易
签署单笔交易
传入交易数据对象（transaction）和链 ID，方法将返回一个包含签名结果的 Buffer。
签署并发送多笔交易
传入一个交易对象数组（transactions）和链 ID，方法将代为签署这些交易并将其提交上链，最终返回该笔批量交易的哈希（hash）。
断开钱包连接
当需要切换钱包或登出时，应调用断开连接的方法。此操作会清除当前的会话信息。在尝试连接新钱包前，请务必先断开现有连接。
错误处理与常见事件
在连接、交易、断开连接等过程中，可能会遇到异常情况。以下是一些常见的错误码及其描述：
| 错误码 | 描述 |
|---|---|
| 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.CONNECTION_ERROR | 连接过程发生异常 |
建议您在代码中妥善捕获和处理这些错误，以提供更友好的用户提示。
常见问题
Q1: 用户在使用 Telegram Mini 钱包时，如何设置签名后自动返回我的 DApp？
A1: 在初始化 actionsConfiguration 时，将 tmaReturnUrl 参数设置为 'back'。这样用户在 Telegram Mini Wallet 中完成签名后，钱包界面会自动关闭并返回到您的 DApp。
Q2: 我的 DApp 需要同时支持 Aptos 和 EVM 链（如以太坊），该如何配置连接请求？
A2: 您需要在 connectParams 的 namespaces 或 optionalNamespaces 中同时配置两个命名空间。Aptos 系的 key 为 "aptos"，EVM 系的 key 为 "eip155"，并分别指定它们所支持的链 ID 数组。
Q3: 调用签名方法时，返回“链不支持”错误该如何解决？
A3: 此错误通常意味着您请求签名的 chainId 并未包含在最初连接钱包时指定的 namespaces 中。请检查两点：一是连接时是否请求了该条链，二是调用签名方法时传入的 chain 参数是否正确。
Q4: 如何为我的 DApp 定制 UI 的主题风格？
A4: 在初始化阶段，通过 uiPreferences 对象中的 theme 参数进行设置。您可以选择预置的深色（DARK）、浅色（LIGHT）主题，或直接跟随系统（SYSTEM）的主题设置。
Q5: 用户拒绝连接或签名后，我该如何处理？
A5: 调用相关方法会抛出错误，其错误码为 USER_REJECTS_ERROR。您需要在代码中使用 try-catch 块捕获此错误，并优雅地提示用户操作已取消，而非将其视为应用故障。