跳到主要内容

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文档

示例​