TON Connect for React
推荐用于React应用程序的SDK是UI React SDK。它是一个React组件,提供了与TON Connect交互的高级方式。
实现
1. 安装
要开始将TON Connect集成到您的DApp中,您需要安装@tonconnect/ui-react
包。您可以使用npm或yarn来实现这一目的:
- npm
- Yarn
- pnpm
npm i @tonconnect/ui-react
yarn add @tonconnect/ui-react
pnpm add @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" }}/>
此外,您始终可以使用useTonConnectUI
hook和connectWallet方法手动初始化连接。
4. 重定向
如果您想在连接钱包后重定向用户至特定页面,您可以使用useTonConnectUI
hook和定制您的返回策略。
Telegram小程序
如果您想在连接钱包后重定向用户至Telegram Mini App,您可以定制TonConnectUIProvider
元素:
<TonConnectUIProvider
// ... other parameters
actionsConfiguration={{
twaReturnUrl: 'https://t.me/<YOUR_APP_NAME>'
}}
>
</TonConnectUIProvider>
5. UI自定义
要定制模态窗口的UI,您可以使用useTonConnectUI
hook和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。
查看所有钱包属性
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选项更新函数的访问权限。
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 文档
示例
- TON Hello World 指南 来创建一个简单的DApp与React UI。
- Demo dApp - 使用
@tonconnect/ui-react
的DApp示例。 - ton.vote - 带有TON Connect实现的React网站示例。