本文将告诉你如何将功能强大的欧易 Widget 与你的产品进行整合,让你只需 30 分钟即可搭建一个高效交易界面!
yarn add @okxweb3/dex-widget
// or
npm install @okxweb3/dex-widget
// or
pnpm add @okxweb3/dex-widget
下方的例子将向你演示如何在一个 React 项目中使用 @okxweb3/dex-widget
。你还可以通过此链接查看更多例子。
实际 Demo:https://okx.github.io/dex-widget/
import React, { useRef, useEffect } from 'react';
import ReactDOM from 'react-dom/client';
import { createOkxSwapWidget } from '@okxweb3/dex-widget';
function App() {
const widgetRef = useRef();
useEffect(() => {
const params = {
width: 375,
providerType: 'EVM',
};
const provider = window.ethereum;
const listeners = [
{
event: 'ON_CONNECT_WALLET',
handler: () => {
provider.enable();
},
},
];
const instance = createOkxSwapWidget(widgetRef.current, {
params,
provider,
listeners,
});
return () => {
instance.destroy();
};
}, []);
return <div ref={widgetRef} />;
}
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
<React.StrictMode>
<App />
</React.StrictMode>
);
如果需要连接钱包,你可以从你的应用中传递钱包提供方信息。同时添加 ON_CONNECT_WALLET 事件,即可无缝连接并使用 Widget。
import { createOkxSwapWidget, ProviderType } from '@okxweb3/dex-widget';
const widgetEthInstance = createOkxSwapWidget(
document.getElementById('widget'),
{
params: {
providerType: ProviderType.EVM,
},
provider: window.ethereum, // e.g. window.okexchain
}
);
const widgetSolanaInstance = createOkxSwapWidget(
document.getElementById('widget'),
{
params: {
providerType: ProviderType.SOLANA,
},
provider: window.solana, // window.okexchain.solana
}
);
Rainbow 连接钱包组件的示例可参考这个链接。
下方表格内是对 Params 的描述。
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
width | number | 450 | 用 css 值 (px) 表示的 Widget 宽度。如果未设置宽度,则宽度的展示样式为:>767px 显示为 450 px, <768 px 显示为 100%, < 375 px 则显示为 375 px。 |
theme | THEME | light | 兑换 Widget 提供默认的日间、夜间主题选项。你可以按下方示例来切换 Widget 的主题。 |
lang | string | en_us | 你可以调整 Widget 所使用的语言,请在多语言配置部分了解更多细节信息。 |
tradeType | TradeType | auto | 交易的类型,可以是“swap”、“bridge”,或“auto”。注意:“自动”包含“swap”和“bridge”。 |
chainIds | Array<string> | [] | 承载单链兑换的区块链的 ID,请在 ChainId 配置部分查看你可选的所有网络。 |
feeConfig | IFeeConfig | {} | 你可以选择在 Widget 中为所有交易类型设置一个费率,请在自定义费率部分了解详情。 |
tokenPair | ITokenPair | {} | 你可选择使用默认代币列表中所收录的代币,请在 tokenPair 配置部分了解详情。 |
providerType | ProviderType | ' ' | ProviderType 是和提供方一致的类型参数,例如,如果提供方是 Solana,那么 providerType 就会是 SOLANA。 |
interface IFeeConfig {
[key: string]: {
feePercent?: string | number;
referrerAddress?: {
[key: string]: {
feePercent: string | number;
};
};
};
}
interface ITokenPair {
fromChain: string | number;
toChain: string | number;
fromToken?: string;
toToken?: string;
}
enum ProviderType {
EVM = 'EVM',
SOLANA = 'SOLANA',
WALLET_CONNECT = 'WALLET_CONNECT',
}
enum TradeType {
SWAP = 'swap',
BRIDGE = 'bridge',
AUTO = 'auto',
}
enum THEME {
LIGHT = 'light',
DARK = 'dark',
}
lang | 描述 |
---|---|
en_us | English,默认 |
zh_cn | 简体中文 |
zh_tw | 繁體中文 |
fr_fr | Français (Afrique) |
id_id | Bahasa Indonesia |
ru_ru | Русский |
tr_tr | Türkçe |
vi_vn | Tiếng Việt |
de_de | Deutsch |
it_it | Italiano |
pl_pl | Polski |
pt_pt | Português (Portugal) |
es_es | Español (España) |
pt_br | Português (Brasil) |
es_419 | Español (Latinoamérica) |
cs_cz | Čeština |
ro_ro | Română |
uk_ua | Українська |
ar_eh | العربية |
nl_nl | Nederlands |
网络 | ChainId | 主网币合约地址 |
---|---|---|
Ethereum | 1 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
zkSync Era | 324 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Optimism | 10 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Polygon | 137 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Avalanche C | 43114 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Arbitrum | 42161 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Linea | 59144 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Base | 8453 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Mantle | 5000 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Scroll | 534352 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
X layer | 196 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Blast | 81457 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
BNB Chain | 56 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Solana | 501 | 11111111111111111111111111111111 |
如果没有配置,则单链兑换将默认设置在 Ethereum 网络,且 fromToken
为 ETH,toToken
为 USDC。
跨链兑换将默认设置为从 Ethereum 跨链至 BNB Chain,且 fromToken
为 ETH,toToken
为 BNB。
import React, { useEffect, useRef } from 'react';
import {
OkxSwapWidgetParams,
ProviderType,
TradeType,
} from '@okxweb3/dex-widget';
const provider = window.ethereum;
export function EvmWidget() {
const widgetRef = useRef();
const params = {
chainIds: ['1', '10'],
lang: 'zh_cn',
providerType: ProviderType.EVM,
theme: 'dark',
tradeType: TradeType.SWAP,
tokenPair: {
fromChain: 1, //ETH
toChain: 1, // ETH
fromToken: '0xdac17f958d2ee523a2206206994597c13d831ec7', // USDT
toToken: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee', // ETH
},
};
const initialConfig = {
params,
provider,
listeners: [
{
event: 'ON_CONNECT_WALLET',
handler: (token, preToken) => {
provider.enable();
},
},
],
};
useEffect(() => {
const widgetHandler = createOkxSwapWidget(widgetRef.current, initialConfig);
return () => {
widgetHandler?.destroy();
};
}, []);
return <div ref={widgetRef} />;
}
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
fromChain | String | 1 | fromToken 所属的源链 ID (例如,1:Ethereum,可在 ChainId 配置部分查看所有已支持的网络和对应的链 ID)。 |
fromToken | String | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE | 试图卖出的代币的合约地址,例如 ETH:0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE。如果 fromToken 是某一区块链的主网币,请查看链 ID 以获取合约地址。 |
toChain | String | 1 | toToken 所属的目标链 ID (例如,1:Ethereum,可在 ChainId 配置部分查看所有已支持的网络和对应的链 ID)。 |
toToken | String | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 | 试图卖出的代币的合约地址,例如 USDC:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48.如果 toToken 是某一区块链的主网币,请查看链 ID 以获取合约地址。 |
添加下列参数后,你即可启用 feeConfig 在你的用户在各个网络上执行交易时,通过 Widget 收取手续费:
你需要声明 chainId、feePercent 和 referrerAddress。
在 Ethereum 和其他 EVM 网络,设置 feePercent 和 referrerAddress 即可收取手续费。
在 Solana 网络,SOL 和 SPL 代币的分佣有些不同。SOL 分佣使用的是钱包地址,而 SPL 代币分佣使用的是代币账号。
你可以添加 feePercent 以调整 referrerAddress 所收到的分佣的费率。
// EVM feeConfig example
feeConfig: {
[chainId]: {
referrerAddress: 'xxx',
feePercent: [0-3],
}
}
// Solana feeConfig example
feeConfig: {
[chainId]: {
feePercent: [0-3],
referrerAddress: {
[tokenContractA]: {
referrerAccount: 'account/abc',
feePercent: '1',
},
[tokenContractB]: {
referrerAccount: 'account/abc',
feePercent: '2',
}
}
}
}
// Full Example
feeConfig: {
1: {// Ethereum chainId
feePercent: 3, // The percentage of Fee
referrerAddress: '0x38a3b108eb2b97c307bf5788909f8c12afd0cd6b', // eth address that receives the fee
},
56: { // Bnb Chain chainId
feePercent: 3, //
referrerAddress: '0x38a3b108eb2b97c307bf5788909f8c12afd0cd6b', // bnb address that receives the fee
},
501: { // solana chainId
referrerAddress: {
'11111111111111111111111111111111': { //solana SOL contract address
account: '6rocMMKG1DNg93RDfVL2xVdrA5nbAT8cFMbdvVTHUF4m',
feePercent: 1,
},
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: { //solana USDC contract address
account: 'C6XW7mFvCuVxYFTi9zTQrUcwkvhfGYAvuosXz6pLDZsa', //solana USDC token account that receives the fee
feePercent: 1,
},
JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN: { //solana JUP contract address
account: 'Ezq6jTC3CwnsXDSdtgy8Sa4xi1iA6fxuEeXxWFPLG9sc', //solana JUP token account that receives the fee
feePercent: 1,
},
},
},
8453: {
feePercent: 3,
referrerAddress: '0x38a3b108eb2b97c307bf5788909f8c12afd0cd6b',
},
}
发送给分佣地址的 fromTokenAmount 的百分比。剩余的代币数量将被设置为卖出数量。费率用基点 (BPS) 计算,一个基点等于 0.01% (万分之一)。费率不能超过 3% (300 BPS)。
referrerAddress 是接收手续费的地址。
请确保接收手续费的地址存在于参数表中所定义的对应网络之上。
可更新的属性:theme、lang、width
// 1. Create and initialize the widget
const widgetHandler = createOkxSwapWidget(container, initialConfig);
// 2. Update the widget's parameters (e.g., change theme or size)
widgetHandler.updateParams({
width: 700,
theme: 'light',
lang: 'tr_tr',
});
Widget 支持 EVM 和 Solana。当从 EVM 切换到 Solana 时,请记得更新相应的 Widget 提供方,反之亦然。
如果首次渲染时没有传递提供方信息,并想要 Widget 响应钱包绑定,就需要调用 updateProvider。
// 3. Update the provider if the user connects a different wallet, EVM => SOLANA
widgetHandler.updateProvider(window.solana, ProviderType.SOLANA);
// SOLANA => EVM
// widgetHandler.updateProvider(window.ethereum, ProviderType.EVM);
你可以更新 Widget 监听的事件。
// 4. Modify event listeners to handle new types of events
widgetHandler.updateListeners([
{
event: OkxEvents.ON_FROM_CHAIN_CHANGE,
handler: (payload) => {
//
},
},
]);
当清除 Widget 模块时,调用此方法
const widgetHandler = createOkxSwapWidget(container, initialConfig);
widgetHandler.destory();
Widget 为 ON_CONNECT_WALLET 和 ON_FROM_CHAIN_CHANGE 提供事件监听。
使用方法如下:
import {createOkxSwapWidget, OkxSwapWidgetParams, OkxEventListeners, OkxEvents} from '@cowprotocol/widget-lib'
const params: OkxSwapWidgetParams = {
// ...
}
const listeners: OkxEventListeners = [
{
event: OkxEvents.ON_CONNECT_WALLET,
handler: () => {
// open connect wallet method, eg openConnectModal of the rainbow kit.
window.ethereum.enable()
}
},
{
event: OkxEvents.ON_FROM_CHAIN_CHANGE,
handler: (token) => {
//
}
},
]
const { updateListeners } = createCowSwapWidget(container, { params, listeners, provider })