1.4.2 • Published 9 months ago

@okxconnect/ui v1.4.2

Weekly downloads
-
License
Apache-2.0
Repository
-
Last release
9 months ago

UI

在 SDK 的基础上,我们也提供了 UI 界面。如果选择通过UI接入,若DApp运营在 Telegram内,则用户可以选择停留在Telegram并唤起移动端App钱包或者唤起欧易 Mini 钱包。

通过npm安装

npm install @okxconnect/ui

初始化

连接钱包之前,需要先创建一个对象,用于后续连接钱包、发送交易等操作。

new OKXTonConnectUI(dappMetaData, buttonRootId, actionsConfiguration, uiPreferences, language, restoreConnection)

请求参数

  • metaData - object
    • name - string: 应用名称,不会作为唯一表示
    • icon - string: 应用图标的 URL。必须是 PNG、ICO 等格式,不支持 SVG 图标。最好传递指向 180x180px PNG 图标的 url。
  • buttonRootId - string: 用于附加钱包连接按钮的 HTML 元素 ID。如果没有传递,则不会出现按钮;
  • actionsConfiguration - object
    • modals - ('before' | 'success' | 'error')[] | 'all' 交易过程中的提醒界面展示模式。
    • returnStrategy -string 'none' | ${string}://${string}; 指定当用户签署/拒绝请求时深层链接的返回策略,如果是在tg中,可以配置tg://resolve
    • tmaReturnUrl -string 'back' | 'none' | ${string}://${string}; Telegram Mini Wallet 钱包中,用户签署/拒绝请求时深层链接的返回策略,一般配置back,表示签名后关闭钱包,会自动展示出dapp;none 表示签名后不做处理;默认为back;
  • uiPreferences -object
    • theme - Theme 可以是:THEME.DARK, THEME.LIGHT, "SYSTEM"
  • language - 'en_US' | 'ru_RU' | 'zh-CN', 目前支持英文/俄文/简体中文,默认为en_US
  • restoreConnection?: boolean - 是否自动回复之前的连接;

返回值

  • OKXTonConnectUI

示例

import { OKXTonConnectUI } from "@okxconnect/ui";

const okxTonConnectUI = new OKXTonConnectUI({
  dappMetaData: {
    name: "application name",
    icon: "application icon url"
  },
  buttonRootId: 'button-root',
  actionsConfiguration:{
    returnStrategy:'none',
    tmaReturnUrl:'back'
  },
  uiPreferences: {
    theme: THEME.LIGHT
  },
  language: 'en_US',
  restoreConnection: true
});

连接钱包

连接钱包去获取钱包地址,作为标识符和用于签名交易的必要参数, “连接按钮”(添加于buttonRootId)会自动处理点击并调用连接, 如果没有添加buttonRootId 的话,需要调用此方法。

await okxTonConnectUI.openModal();

示例

okxTonConnectUI.openModal();

设置tonProof

添加连接签名参数, 如果需要设置tonProof,请在准备好tonProof 参数之前,设置state:'loading', 在准备好之后,将state设置为 'ready'并添加value; 也可以通过设置setConnectRequestParameters(null) 移除掉loading 状态;

示例

okxtonConnectUI.setConnectRequestParameters({ state: 'loading' });

const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
  okxtonConnectUI.setConnectRequestParameters(null);
} else {
  okxtonConnectUI.setConnectRequestParameters({
    state: "ready",
    value: { tonProof: tonProofPayload }
  });
}

关闭连接弹窗

示例

okxTonConnectUI.closeModal();

获取当前连接的Wallet和WalletInfo

获取当前是否有连接钱包,以及已连接的钱包的相关信息;

示例

const currentWallet  = okxTonConnectUI.wallet;
const currentAccount = okxTonConnectUI.account;
const isConnected    = okxTonConnectUI.connected;

断开钱包连接

示例

okxTonConnectUI.disconnect();

监听钱包状态变化

钱包状态有:连接成功、恢复连接成功、断开连接等,都可以用此方法获取状态。 方法详情同OKXTonConnect.onStatusChange

示例

import { Wallet } from "@okxconnect/ui";

const unsubscribe = okxTonConnectUI.onStatusChange((walletInfo: Wallet | null) => {
          console.log('Connection status:', walletInfo);
        }, (err: OKXConnectError) => {
          console.log('Connection status:', err);
        }
)
unsubscribe()

发送交易

向钱包发送消息的方法:

sendTransaction(transaction, actionConfigurationRequest): Promise<SendTransactionResponse>

请求参数

  • transaction - object, 参数同OKXTonConnect.sendTransaction的transaction

  • actionConfigurationRequest - object

    • modals : ('before' | 'success' | 'error')[] | 'all' 交易过程中的提醒界面展示模式,默认为'before'
    • tmaReturnUrl -string 'back' | 'none' | ${string}://${string}; Telegram Mini Wallet 钱包中,用户签署/拒绝请求时深层链接的返回策略,一般配置back,表示签名后关闭钱包,会自动展示出dapp;none 表示签名后不做处理;默认为back;

返回值

  • Promise - {boc: string}: 签名结果

示例

import { OKXConnectError, OKX_CONNECT_ERROR_CODES } from "@okxconnect/core";

let transactionRequest = {
  "validUntil": Date.now() / 1000 + 360,
  "from": "0:348bcf827469c5fc38541c77fdd91d4e347eac200f6f2d9fd62dc08885f0415f",
  "messages": [
    {
      "address": "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F",
      "amount": "20000000",
      "stateInit": "base64bocblahblahblah==" //deploy contract
    },
    {
      "address": "0:E69F10CC84877ABF539F83F879291E5CA169451BA7BCE91A37A5CED3AB8080D3",
      "amount": "60000000",
      "payload": "base64bocblahblahblah==" //transfer nft to new deployed account 0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F
    }
  ]
}

okxTonConnectUI.sendTransaction(transactionRequest, {
  modals: 'all',
  tmaReturnUrl: 'back'
}).then((result) => {
  let boc = result.boc
}).catch((error) => {
  if (error instanceof OKXConnectError && error.code == OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR) {
    //userReject;
  } else {
    //other error;
  }
})

设置ui配置项

支持修改主题,文字语言设置,也可以在初始化的时候添加这些配置;

示例

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

监听事件

在以下事件发生时,会发送对应事件通知,Dapp可以根据需要添加监听,来处理对应的逻辑;

event事件

事件名称触发时机
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当用户取消交易签名或签名过程中出现错误时

示例

import { OKX_UI_CONNECTION_AND_TRANSACTION_EVENT } from "@okxconnect/ui";

window.addEventListener(OKX_UI_CONNECTION_AND_TRANSACTION_EVENT.OKX_UI_CONNECTION_STARTED, (event) => {
  if (event instanceof CustomEvent) {
    console.log('Transaction init', event.detail);
  }
});
1.4.2

9 months ago

1.4.1

9 months ago

1.4.0

9 months ago

1.3.9

9 months ago

1.3.8

9 months ago

1.3.7

9 months ago

1.3.6

9 months ago

0.4.0-beta.11

9 months ago

1.3.3

9 months ago

1.3.2

9 months ago

0.3.0-beta.8

9 months ago

0.3.0-beta.7

9 months ago

0.4.0-beta.1

9 months ago

0.4.0-beta.2

9 months ago

0.4.0-beta.3

9 months ago

0.4.0-beta.4

9 months ago

0.4.0-beta.5

9 months ago

0.4.0-beta.6

9 months ago

0.4.0-beta.7

9 months ago

0.4.0-beta.8

9 months ago

1.3.1

9 months ago

1.3.0

9 months ago

0.3.0-beta.2

9 months ago

0.3.0-beta.3

9 months ago

0.3.0-beta.1

9 months ago

0.3.0-beta.4

9 months ago

1.2.8

9 months ago

1.2.0

10 months ago

0.1.12

10 months ago

1.1.9

10 months ago

1.2.7

9 months ago

1.1.8

10 months ago

1.2.6

9 months ago

1.1.7

10 months ago

1.2.5

9 months ago

1.1.6

10 months ago

1.1.5

10 months ago

1.1.4

10 months ago

1.2.2

10 months ago

1.1.3

10 months ago

1.2.1

10 months ago

0.1.10

10 months ago

0.1.11

10 months ago

0.1.8

10 months ago

0.1.7

10 months ago

0.1.9

10 months ago

0.1.4

10 months ago

0.1.6

10 months ago

0.1.5

10 months ago

0.1.3

10 months ago

0.1.2

10 months ago

0.1.1

10 months ago

1.1.2

10 months ago

1.1.1

10 months ago

1.1.0

10 months ago