跳到主要内容

TON Connect for React

推荐用于React应用程序的SDK是UI React SDK。它是一个React组件,提供了与TON Connect交互的高级方式。

实现

1. 安装

要开始将TON Connect集成到您的DApp中,您需要安装@tonconnect/ui-react包。您可以使用npm或yarn来实现这一目的:

npm i @tonconnect/ui-react

2. TON Connect初始化

安装包之后,您应该为您的应用程序创建一个manifest.json文件。有关如何创建manifest.json文件的更多信息,请参阅此处

创建manifest文件后,将TonConnectUIProvider导入到您的Mini App的根目录,并传入manifest URL:

import { TonConnectUIProvider } from '@tonconnect/ui-react';

export function App() {
return (
<TonConnectUIProvider manifestUrl="https://<YOUR_APP_URL>/tonconnect-manifest.json">
{ /* Your app */ }
</TonConnectUIProvider>
);
}

3. 连接到钱包

添加TonConnectButton。TonConnect按钮是初始化连接的通用UI组件。连接钱包后,它会变成钱包菜单。建议将其放置在应用程序的右上角。

export const Header = () => {
return (
<header>
<span>My App with React UI</span>
<TonConnectButton />
</header>
);
};

您还可以为按钮添加className和style属性。请注意,您不能给TonConnectButton传递子组件:

<TonConnectButton className="my-button-class" style={{ float: "right" }}/>

此外,您始终可以使用useTonConnectUIhook和connectWallet方法手动初始化连接。

4. 重定向

如果您想在连接钱包后重定向用户至特定页面,您可以使用useTonConnectUIhook和定制您的返回策略

Telegram小程序

如果您想在连接钱包后重定向用户至Telegram Mini App,您可以定制TonConnectUIProvider元素:

      <TonConnectUIProvider
// ... other parameters
actionsConfiguration={{
twaReturnUrl: 'https://t.me/<YOUR_APP_NAME>'
}}
>
</TonConnectUIProvider>

在GitHub上查看示例

5. UI自定义

定制模态窗口的UI,您可以使用useTonConnectUIhook和setOptions函数。详见Hooks部分中关于useTonConnectUIhook的更多信息。

Hooks

如果您想在React应用程序中使用一些低级TON Connect UI SDK的特性,您可以使用@tonconnect/ui-react包中的hook。

useTonAddress

使用它来获取用户当前的ton钱包地址。传递布尔参数isUserFriendly来选择地址的格式。如果钱包未连接,hook将返回空字符串。

import { useTonAddress } from '@tonconnect/ui-react';

export const Address = () => {
const userFriendlyAddress = useTonAddress();
const rawAddress = useTonAddress(false);

return (
userFriendlyAddress && (
<div>
<span>User-friendly address: {userFriendlyAddress}</span>
<span>Raw address: {rawAddress}</span>
</div>
)
);
};

useTonWallet

使用它来获取用户当前的ton钱包。如果钱包未连接,hook会返回null。

查看所有钱包属性

Wallet接口 WalletInfo接口

import { useTonWallet } from '@tonconnect/ui-react';

export const Wallet = () => {
const wallet = useTonWallet();

return (
wallet && (
<div>
<span>Connected wallet: {wallet.name}</span>
<span>Device: {wallet.device.appName}</span>
</div>
)
);
};

useTonConnectUI

使用它来获取TonConnectUI实例和UI选项更新函数的访问权限。

了解更多关于TonConnectUI实例方法

了解更多关于setOptions函数

import { Locales, useTonConnectUI } from '@tonconnect/ui-react';

export const Settings = () => {
const [tonConnectUI, setOptions] = useTonConnectUI();

const onLanguageChange = (lang: string) => {
setOptions({ language: lang as Locales });
};

return (
<div>
<button onClick={() => tonConnectUI.sendTransaction(myTransaction)}>
Send transaction
</button>

<div>
<label>language</label>
<select onChange={e => onLanguageChange(e.target.value)}>
<option value="en">en</option>
<option value="ru">ru</option>
</select>
</div>
</div>
);
};

useIsConnectionRestored

指示连接恢复过程的当前状态。 您可以使用它检测连接恢复过程是否已完成。

import { useIsConnectionRestored } from '@tonconnect/ui-react';

export const EntrypointPage = () => {
const connectionRestored = useIsConnectionRestored();

if (!connectionRestored) {
return <Loader>Please wait...</Loader>;
}

return <MainPage />;
};

使用

让我们来看看如何在实践中使用React UI SDK。

发送交易

向特定地址发送TON币(以nanotons计):

import { useTonConnectUI } from '@tonconnect/ui-react';

const transaction = {
messages: [
{
address: "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F", // destination address
amount: "20000000" //Toncoin in nanotons
}
]

}

export const Settings = () => {
const [tonConnectUI, setOptions] = useTonConnectUI();

return (
<div>
<button onClick={() => tonConnectUI.sendTransaction(transaction)}>
Send transaction
</button>
</div>
);
};

通过哈希理解交易状态

位于支付处理中(使用tonweb)的原理。了解更多

后端的可选检查(tonproof)

提示

了解如何签名和验证消息:签名与验证

使用tonConnectUI.setConnectRequestParameters函数来传递你的连接请求参数。

该函数接受一个参数:

当你在等待来自后端的响应时,设置状态为 ‘loading’。如果用户此刻打开连接钱包modals,他会看到一个加载器。

const [tonConnectUI] = useTonConnectUI();

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

设置状态为 ‘ready’ 并定义 tonProof 值。传递的参数将应用于连接请求(二维码和通用链接)。

const [tonConnectUI] = useTonConnectUI();

tonConnectUI.setConnectRequestParameters({
state: 'ready',
value: {
tonProof: '<your-proof-payload>'
}
});

如果通过 state: 'loading' 启用了加载器(例如,你从后端收到一个错误而不是响应),则移除加载器。连接请求将不包含任何额外参数。

const [tonConnectUI] = useTonConnectUI();

tonConnectUI.setConnectRequestParameters(null);

如果你的tonProof有效载荷的期限是有限的(例如,你可以每10分钟刷新一次连接请求参数),你可以多次调用tonConnectUI.setConnectRequestParameters

const [tonConnectUI] = useTonConnectUI();

// enable ui loader
tonConnectUI.setConnectRequestParameters({ state: 'loading' });

// fetch you tonProofPayload from the backend
const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
// remove loader, connect request will be without any additional parameters
tonConnectUI.setConnectRequestParameters(null);
} else {
// add tonProof to the connect request
tonConnectUI.setConnectRequestParameters({
state: "ready",
value: { tonProof: tonProofPayload }
});
}

当钱包连接时,你可以在wallet对象中找到ton_proof结果:

import {useTonConnectUI} from "@tonconnect/ui-react";

const [tonConnectUI] = useTonConnectUI();

useEffect(() =>
tonConnectUI.onStatusChange(wallet => {
if (wallet.connectItems?.tonProof && 'proof' in wallet.connectItems.tonProof) {
checkProofInYourBackend(wallet.connectItems.tonProof.proof, wallet.account);
}
}), []);

钱包断开

断开钱包的调用:

import { useTonConnectUI } from '@tonconnect/ui-react';

const [tonConnectUI] = useTonConnectUI();

await tonConnectUI.disconnect();

API 文档

最新的API文档

示例