OKX Connect UI 开发指南：从安装到高级功能全解析

·

OKX Connect UI 是一个强大的软件开发工具包（SDK），旨在帮助开发者轻松地将去中心化应用（DApp）与 OKX 钱包进行连接和交互。本文将详细介绍其安装、初始化、核心功能及常见问题，助你快速上手。

安装与初始化

通过 npm 安装

要开始使用 OKX Connect UI，首先需要通过 npm 安装依赖包。确保你的开发环境已配置好 Node.js 和 npm。

npm install @okxconnect/ui

初始化配置

安装完成后，在连接钱包之前，你需要初始化一个对象，用于后续的钱包连接和交易发送等操作。

OKXUniversalConnectUI.init(DAppMetaData, actionsConfiguration, uiPreferences, language, restoreConnection)

参数说明

返回值

示例代码

import { OKXUniversalConnectUI } from "@okxconnect/ui";
const universalUi = await OKXUniversalConnectUI.init({
  DAppMetaData: {
    icon: "https://example.com/icon.png",
    name: "My DApp"
  },
  actionsConfiguration: {
    returnStrategy: 'tg://resolve',
    modals: 'all',
    tmaReturnUrl: 'back'
  },
  language: "en_US",
  uiPreferences: {
    theme: THEME.LIGHT
  },
});

核心功能详解

连接钱包

连接钱包的目的是获取钱包地址作为标识符，以及用于签名交易的必要参数。

await universalUi.openModal(connectParams: ConnectParams);

参数说明

返回值

示例代码

var session = await universalUi.openModal({
  namespaces: {
    eip155: {
      chains: ["eip155:1", "eip155:137"],
      defaultChain: "1",
      rpcMap: {
        "137": "https://polygon.drpc.org"
      }
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ["eip155:43114"]
    }
  }
})

连接并签名

此方法用于连接钱包并同时签名数据，结果将在 'connect_signResponse' 事件中回调。

await universalUi.openModalAndSign(connectParams: ConnectParams, signRequest: RequestParams[]);

参数说明

返回值

示例代码

universalUi.on("connect_signResponse", (signResponse) => {
  console.log(signResponse);
});
var session = await universalUi.openModalAndSign({
  namespaces: {
    eip155: {
      chains: ["eip155:1", "eip155:137"],
      defaultChain: "1",
      rpcMap: {
        "137": "https://polygon.drpc.org"
      }
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ["eip155:43114"]
    }
  }
}, [{
  method: "personal_sign",
  chainId: "eip155:1",
  params: [
    "0x4d7920656d61696c206973206a6f686e40646f652e636f6d202d2031373237353937343537313336",
  ],
}])

👉 查看实时钱包连接状态与工具

发送交易与签名

使用 request 方法向钱包发送消息，支持签名和交易操作。

universalUi.request(requestArguments, chain, actionConfigurationRequest);

参数说明

返回值

示例代码

let chain = 'eip155:1'
var data = {
  "method": "personal_sign",
  "params": [
    "0x506c65617365207369676e2074686973206d65737361676520746f20636f6e6669726d20796f7572206964656e746974792e",
    "0x4B0897b0513FdBeEc7C469D9aF4fA6C0752aBea7"
  ]
}
var personalSignResult = await universalUi.request(data, chain, 'all')

使用 RPC 扩展功能

当标准的 EVM 请求方法无法满足需求时，可以通过配置 RPC 实现更多功能。在连接钱包的 openModal 或 openModalAndSign 方法中，通过 rpcMap 配置 RPC。

示例代码

// 查询交易哈希详情
let rpcData = {
  method: "eth_getTransactionByHash",
  params: ["0xd62fa4ea3cf7ee3bf6f5302b764490730186ed6a567c283517e8cb3c36142e1a"],
};
let result = await universalUi.request(rpcData, "eip155:137")

高级功能与事件处理

设置默认网络

在多网络环境下，如果开发者未指定当前操作所在的网络，交互将通过默认网络进行。

universalUi.setDefaultChain('eip155:1')

断开钱包连接

universalUi.disconnect();

事件监听

OKX Connect UI 提供了多种事件监听，帮助开发者处理连接状态变化、签名响应等。

// 生成通用链接
universalUi.on("display_uri", (uri) => {
  console.log(uri);
});

// 会话信息更新（如添加自定义链）
universalUi.on("session_update", (session) => {
  console.log(JSON.stringify(session));
});

// 断开连接事件
universalUi.on("session_delete", ({topic}) => {
  console.log(topic);
});

// 连接并签名响应事件
universalUi.on("connect_signResponse", (signResponse) => {
  console.log(signResponse);
});

// OKX 扩展钱包切换账户事件
universalUi.on("accountChanged", (session) => {
  if (session){
    console.log(`accountChanged `, JSON.stringify(session));
  }
});

错误代码说明

在连接、交易和断开连接过程中，可能会抛出以下异常：

错误代码描述
UNKNOWN_ERROR未知错误
ALREADY_CONNECTED_ERROR钱包已连接
NOT_CONNECTED_ERROR钱包未连接
USER_REJECTS_ERROR用户拒绝操作
METHOD_NOT_SUPPORTED方法不支持
CHAIN_NOT_SUPPORTED链不支持
WALLET_NOT_SUPPORTED钱包不支持
CONNECTION_ERROR连接错误

👉 获取进阶开发方法与策略

常见问题

如何检查钱包是否已连接？

使用内置方法可以获取当前钱包的连接状态。

示例代码

const isConnected = universalUi.isConnected();
console.log(isConnected); // 返回布尔值

支持哪些语言和主题？

OKX Connect UI 支持多种语言（如英文、中文、俄文等）和主题（深色、浅色、系统默认），可在初始化或运行时通过 uiOptions 设置。

示例代码

universalUi.uiOptions = {
  language: 'zh_CN',
  uiPreferences: {
    theme: THEME.DARK
  }
};

如何处理用户拒绝签名的情况？

当用户拒绝签名时，会抛出 USER_REJECTS_ERROR 错误代码。开发者可以通过监听错误事件或使用 try-catch 块来处理。

示例代码

try {
  await universalUi.openModalAndSign(connectParams, signRequest);
} catch (error) {
  if (error.code === OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR) {
    console.log("用户拒绝签名");
  }
}

如何自定义交易过程中的弹窗？

通过 actionsConfiguration 中的 modals 参数，可以配置交易过程中显示提示的模式，例如在交易前、成功或失败时显示弹窗。

示例代码

actionsConfiguration: {
  modals: ['before', 'success', 'error'] // 或直接使用 'all'
}

是否支持多链操作？

是的，OKX Connect UI 支持多链操作。在连接参数中，通过 namespaces 和 optionalNamespaces 配置所需的链信息，钱包会返回支持的链列表。

如何添加自定义网络？

如果钱包不支持某个自定义网络，可以在 optionalNamespaces 中添加请求。如果钱包已支持该网络，会话结果中将返回自定义链信息；否则，可以通过再次调用 wallet_addEthereumChain 方法添加。

示例代码

optionalNamespaces: {
  eip155: {
    chains: ["eip155:999"] // 自定义链 ID
  }
}

通过以上指南，你应该能够全面了解 OKX Connect UI 的功能和使用方法。无论是简单的钱包连接还是复杂的交易签名，这个 SDK 都提供了灵活的配置和强大的事件处理机制，助力你的 DApp 开发。