TON Connect UI

TonConnect UI 是 TonConnect SDK 的 UI 套件。使用它可以通过 TonConnect 协议将您的应用连接到 TON 钱包。

如果您在 dapp 中使用 React，请查看 TonConnect UI React kit。

如果您希望在服务器端使用 TonConnect，请使用 TonConnect SDK。

您可以在文档中找到更多详细信息和协议规范。

最新的 API 文档

github地址

入门指南

使用 CDN 安装

在 HTML 文件中添加以下脚本：

html

<script src="https://unpkg.com/@tonconnect/ui@latest/dist/tonconnect-ui.min.js"></script>

ℹ️ 如果您不希望自动更新库，请传递具体的版本号而不是 latest，例如：

html

<script src="https://unpkg.com/@tonconnect/ui@0.0.9/dist/tonconnect-ui.min.js"></script>

您可以在全局变量 TON_CONNECT_UI 中找到 TonConnectUI，例如：

html

<script>
    const tonConnectUI = new TON_CONNECT_UI.TonConnectUI({
        manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json', 
        buttonRootId: '<YOUR_CONNECT_BUTTON_ANCHOR_ID>'
    });
</script>

创建manifest.json参考： https://docs.ton.org/mandarin/develop/dapps/ton-connect/manifest

使用 npm 安装

shell

npm i @tonconnect/ui

使用方法

创建 TonConnectUI 实例

import TonConnectUI from '@tonconnect/ui'

const tonConnectUI = new TonConnectUI({
    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
    buttonRootId: '<YOUR_CONNECT_BUTTON_ANCHOR_ID>'
});

查看所有可用选项：

TonConnectUiOptionsWithManifest

TonConnectUiOptionsWithConnector

如有需要更改选项

tonConnectUI.uiOptions = {
    language: 'ru', // "en" | "ru"
    uiPreferences: {
        theme: THEME.DARK
    }
};

UI 元素将在分配后重新渲染。您只需传递要更改的选项。传递的选项将与当前 UI 选项合并。请注意，必须传递对象给 tonConnectUI.uiOptions 以保持反应性。

不要这样做：

/* 错误，不会生效 */ tonConnectUI.uiOptions.language = 'ru';

查看所有可用选项

获取钱包列表

const walletsList = await tonConnectUI.getWallets();

/* walletsList 是一个包含以下属性的数组：
{
    name: string;
    imageUrl: string;
    tondns?: string;
    aboutUrl: string;
    universalLink?: string;
    deepLink?: string;
    bridgeUrl?: string;
    jsBridgeKey?: string;
    injected?: boolean; // 如果钱包注入到网页中则为 true
    embedded?: boolean; // 如果 dapp 在钱包的浏览器中打开则为 true
}[] 
 */

或者

const walletsList = await TonConnectUI.getWallets();

打开连接模态窗口

“TonConnect UI 连接按钮”（添加在 buttonRootId 处）自动处理点击并调用连接。但您仍然可以通过编程方式打开“连接模态窗口”，例如在点击自定义连接按钮后。

await tonConnectUI.openModal();

此方法打开模态窗口，并返回一个在模态窗口打开后解析的 Promise。

如果在打开模态窗口时出现错误，将根据情况抛出 TonConnectUIError 或 TonConnectError。

关闭连接模态窗口

tonConnectUI.closeModal();

此方法关闭模态窗口。

获取当前模态窗口状态

此 getter 返回模态窗口的当前状态。状态将是一个包含 status 和 closeReason 属性的对象。status 可以是 'opened' 或 'closed'。如果模态窗口关闭，您可以检查 closeReason 以了解关闭的原因。

const currentModalState = tonConnectUI.modalState;

订阅模态窗口状态变化

要订阅模态窗口状态的变化，可以使用 onModalStateChange 方法。它返回一个函数，该函数必须在取消订阅时调用。

const unsubscribeModal = tonConnectUI.onModalStateChange(
    (state: WalletsModalState) => {
        // 更新状态/反应变量以在 UI 中显示更新
        // state.status 将是 'opened' 或 'closed'
        // 如果 state.status 是 'closed'，您可以检查 state.closeReason 以了解原因
    }
);

稍后调用 unsubscribeModal() 以在不需要监听更新时节省资源。

钱包模态窗口控制

tonConnectUI 提供了用于管理模态窗口的方法，如 openModal()、closeModal() 和其他方法，这些方法旨在易于使用并涵盖大多数用例。

typescript

const { modal } = tonConnectUI;

// 打开和关闭模态窗口
await modal.open();
modal.close();

// 获取当前模态窗口状态
const currentState = modal.state;

// 订阅和取消订阅模态窗口状态变化
const unsubscribe = modal.onStateChange(state => { /* ... */ });
unsubscribe();

虽然 tonConnectUI 内部将这些调用委托给 modal，但建议使用 tonConnectUI 方法以获得更直接和一致的体验。modal 公开了模态窗口的状态和行为的直接访问，但除非必要，否则应避免使用。

打开特定钱包

本节描述的方法标记为实验性，未来版本可能会发生变化。

要为特定钱包打开模态窗口，请使用 openSingleWalletModal() 方法。此方法接受钱包的 app_name 作为参数（请参阅 wallets-list.json），并打开相应的钱包模态窗口。它返回一个在模态窗口成功打开后解析的 Promise。

typescript

await tonConnectUI.openSingleWalletModal('wallet_identifier');

要关闭当前打开的特定钱包模态窗口，请使用 closeSingleWalletModal() 方法：

typescript

tonConnectUI.closeSingleWalletModal();

要订阅特定钱包模态窗口状态的变化，请使用 onSingleWalletModalStateChange((state) => {}) 方法。它接受一个回调函数，该回调函数将使用当前模态窗口状态调用。

typescript

const unsubscribe = tonConnectUI.onSingleWalletModalStateChange((state) => {
    console.log('Modal state changed:', state);
});

// 当您希望停止监听状态变化时调用 `unsubscribe`
unsubscribe();

要获取特定钱包模态窗口的当前状态，请使用 singleWalletModalState 属性：

typescript

const currentState = tonConnectUI.singleWalletModalState;
console.log('Current modal state:', currentState);

获取当前连接的钱包和钱包信息

您可以使用特殊的 getters 来读取当前的连接状态。请注意，此 getter 仅表示当前值，因此它们不是反应性的。要响应和处理钱包变化，请使用 onStatusChange 方法。

const currentWallet = tonConnectUI.wallet;
const currentWalletInfo = tonConnectUI.walletInfo;
const currentAccount = tonConnectUI.account;
const currentIsConnectedStatus = tonConnectUI.connected;

订阅连接状态变化

要订阅连接状态的变化，可以使用 onStatusChange 方法。它返回一个函数，该函数必须在取消订阅时调用。

const unsubscribe = tonConnectUI.onStatusChange(
    walletAndwalletInfo => {
        // 更新状态/反应变量以在 UI 中显示更新
    }
);

稍后调用 unsubscribe() 以在不需要监听更新时节省资源。

断开钱包连接

调用以断开钱包连接。

await tonConnectUI.disconnect();

发送交易

在调用 sendTransaction 时钱包必须已连接。否则，将抛出错误。

const transaction = {
    validUntil: Math.floor(Date.now() / 1000) + 60, // 60 秒
    messages: [
        {
            address: "EQBBJBB3HagsujBqVfqeDUPJ0kXjgTPLWPFFffuNXNiJL0aA",
            amount: "20000000",
         // stateInit: "base64bocblahblahblah==" // 仅为示例。替换为您的交易 initState 或删除
        },
        {
            address: "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn",
            amount: "60000000",
         // payload: "base64bocblahblahblah==" // 仅为示例。替换为您的交易 payload 或删除
        }
    ]
}

try {
    const result = await tonConnectUI.sendTransaction(transaction);

    // 您可以使用签名的 boc 查找交易
    const someTxData = await myAppExplorerService.getTransaction(result.boc);
    alert('交易已成功发送', someTxData);
} catch (e) {
    console.error(e);
}

sendTransaction 将自动渲染信息模态窗口和通知。您可以更改其行为：

const result = await tonConnectUI.sendTransaction(defaultTx, {
    modals: ['before', 'success', 'error'],
    notifications: ['before', 'success', 'error']
});

默认配置是：

const defaultBehaviour = {
    modals: ['before'],
    notifications: ['before', 'success', 'error']
}

您还可以使用 uiOptions setter 修改所有操作调用的行为：

tonConnectUI.uiOptions = {
        actionsConfiguration: {
            modals: ['before', 'success', 'error'],
            notifications: ['before', 'success', 'error']
        }
    };

通用链接重定向问题（iOS）

某些操作系统，尤其是 iOS，对通用链接的使用有一些限制。例如，如果您尝试在 iOS 设备上通过 window.open 打开一个通用链接，您可能会遇到以下问题：移动浏览器不会将用户重定向到钱包应用，而是会打开备用选项卡。这是因为通用链接只能在浏览器中同步打开用户操作（按钮点击/……）后打开。这意味着您不能在用户点击 dapp 中的操作按钮后执行任何异步请求，或者您无法在某些设备上将用户重定向到连接的钱包。

因此，默认情况下，如果用户的操作系统是 iOS，在 dapp 调用 tonConnectUI.sendTransaction 后，他们不会自动重定向到钱包。您可以使用 skipRedirectToWallet 选项更改此行为：

const result = await tonConnectUI.sendTransaction(defaultTx, {
    modals: ['before', 'success', 'error'],
    notifications: ['before', 'success', 'error'],
    skipRedirectToWallet: 'ios' //'ios'（默认），或 'never'，或 'always'
});

您可以使用 `uiOptions` setter 全局设置它，并将其应用于所有操作（发送交易/……）。

tonConnectUI.uiOptions = {
        actionsConfiguration: {
            skipRedirectToWallet: 'ios'
        }
    };

如果在操作按钮的点击处理程序中没有任何异步调用，请使用选项 `'never'`。

// 使用 skipRedirectToWallet: 'never' 以获得更好的用户体验
const onClick = async ()  => {
    const txBody = packTxBodySynchrone();
    tonConnectUI.sendTransaction(txBody, { skipRedirectToWallet: 'never' });

    const myApiResponse = await notifyBackend();
    //...
}

// 不要使用 skipRedirectToWallet: 'never'，应使用 skipRedirectToWallet: 'ios'
const onClick = async ()  => {
    const myApiResponse = await notifyBackend();
    
    const txBody = packTxBodySynchrone();
    tonConnectUI.sendTransaction(txBody, { skipRedirectToWallet: 'ios' });
    //...
}

添加返回策略

返回策略（可选）指定用户签署/拒绝请求时 deeplink 的返回策略。

'back'（默认）表示返回到初始化 deeplink 跳转的应用（例如浏览器、本地应用等）， 'none' 表示用户操作后没有跳转；一个 URL：钱包将在完成用户操作后打开此 URL。请注意，如果是网页应用，您不应传递应用的 URL。此选项应用于本地应用，以解决 'back' 选项可能出现的操作系统特定问题。

您可以使用 uiOptions setter 全局设置它，并将其应用于连接请求和所有后续操作（发送交易/……）。

tonConnectUI.uiOptions = {
        actionsConfiguration: {
            returnStrategy: 'none'
        }
    };

或者您可以在发送交易时直接设置它（仅适用于此交易请求）

const result = await tonConnectUI.sendTransaction(defaultTx, {
    returnStrategy: '<protocol>://<your_return_url>' // 请注意，如果是网页应用，您不应传递应用的 URL。
     // 此选项应用于本地应用，以解决 'back' 选项可能出现的操作系统特定问题。
});

在 TMA（Telegram Mini Apps）中使用

TonConnect UI 在 TMA 中的工作方式与在常规网站中相同！基本上，dApp 开发人员无需进行更改。您唯一需要设置的是动态返回策略。

目前，TMA 钱包无法像本地钱包应用那样重定向回之前打开的 TMA dApp。这意味着您需要指定返回策略为指向您的 TMA 的链接，该链接仅在 dApp 以 TMA 模式打开时应用。

tonConnectUI.uiOptions = {
    twaReturnUrl: 'https://t.me/durov'
};

换句话说，TonConnect UI 将根据环境自动处理返回策略。以下伪代码演示了 TonConnect UI 内部的返回策略处理逻辑：

请注意，您不需要将此代码添加到您的 dApp。这只是一个示例，展示了 TonConnect UI 如何内部处理返回策略。

let finalReturnStrategy;

// 确定提供的链接是否打开 Telegram（使用协议 tg:// 或域 t.me）。
if (isLinkToTelegram('https://example.com')) {
    // 在 Telegram Mini Apps 环境中，
    if (isInTWA()) {
        // 优先使用 'twaReturnUrl'，
        finalReturnStrategy = actionsConfiguration.twaReturnUrl;

        // 如果未设置，则回退到 'returnStrategy'。
        if (!finalReturnStrategy) {
            finalReturnStrategy = actionsConfiguration.returnStrategy;
        }
    }
    // 如果不在 TMA 环境中，
    else {
        // 返回策略设置为 'none'。
        finalReturnStrategy = 'none';
    }
}
// 当链接不打开 Telegram 时，
else {
    // 使用预定义的 'returnStrategy'。
    finalReturnStrategy = actionsConfiguration.returnStrategy;
}

// 现在，'finalReturnStrategy' 包含了基于链接目标和 dApp 环境的正确策略。

检测连接恢复过程的结束

在恢复之前连接的钱包之前，TonConnect 必须设置与桥的 SSE 连接，因此您需要等待一段时间以恢复连接。如果您需要根据连接是否恢复来更新 UI，可以使用 tonConnectUI.connectionRestored promise。

Promise 在连接恢复过程结束后解析（promise 将在 onStatusChange 之后触发，因此在 promise 解析后您可以获取关于钱包和会话的实际信息）。解析值 true/false 表示会话是否成功恢复。

tonConnectUI.connectionRestored.then(restored => {
    if (restored) {
        console.log(
            'Connection restored. Wallet:',
            JSON.stringify({
                ...tonConnectUI.wallet,
                ...tonConnectUI.walletInfo
            })
        );
    } else {
        console.log('Connection was not restored.');
    }
});

UI 自定义

TonConnect UI 提供了一个界面，当用户在使用各种应用时应该熟悉和可识别。然而，应用开发人员可以对该界面进行更改，以保持与应用界面的一致性。

使用 tonconnectUI.uiOptions 自定义 UI

所有此类更新都是反应性的——更改 tonconnectUI.uiOptions，更改将立即应用。

查看所有可用选项

更改边框半径

有三种边框半径模式：'m'、's' 和 'none'。默认是 'm'。您可以通过 tonconnectUI.uiOptions 更改它，或在创建 tonConnectUI 实例时设置：

/* 传递给构造函数 */
const tonConnectUI = new TonConnectUI({
    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
    uiPreferences: {
        borderRadius: 's'
    }
});

/* 或动态更新 */
tonConnectUI.uiOptions = {
    uiPreferences: {
        borderRadius: 's'
    }
};

注意，uiOptions 是一个 setter，它会将新选项与以前的选项合并。因此，您不需要显式合并它。只需传递更改的选项。

/* 不要这样做。请参阅上面的描述 */
tonConnectUI.uiOptions = {
    ...previousUIOptions,
    uiPreferences: {
        borderRadius: 's'
    }
};

/* 只需传递更改的属性 */
tonConnectUI.uiOptions = {
    uiPreferences: {
        borderRadius: 's'
    }
};

更改主题

您可以设置固定主题：'THEME.LIGHT' 或 'THEME.DARK'，或使用系统主题。默认主题是系统主题。

import { THEME } from '@tonconnect/ui';

tonConnectUI.uiOptions = {
    uiPreferences: {
        theme: THEME.DARK
    }
};

您也可以设置 'SYSTEM' 主题：

tonConnectUI.uiOptions = {
    uiPreferences: {
        theme: 'SYSTEM'
    }
};

如果需要，您可以在构造函数中设置主题：

import { THEME } from '@tonconnect/ui';

const tonConnectUI = new TonConnectUI({
    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
    uiPreferences: {
        theme: THEME.DARK
    }
});

更改颜色方案

您可以重新定义每个主题的所有颜色方案或更改某些颜色。只需传递您想要更改的颜色。

tonConnectUI.uiOptions = {
    uiPreferences: {
        colorsSet: {
            [THEME.DARK]: {
                connectButton: {
                    background: '#29CC6A'
                }
            }
        }
    }
};

您可以同时更改两个主题的颜色：

tonConnectUI.uiOptions = {
    uiPreferences: {
        colorsSet: {
            [THEME.DARK]: {
                connectButton: {
                    background: '#29CC6A'
                }
            },
            [THEME.LIGHT]: {
                text: {
                    primary: '#FF0000'
                }
            }
        }
    }
};

如果需要，您可以在构造函数中设置颜色方案：

import { THEME } from '@tonconnect/ui';

const tonConnectUI = new TonConnectUI({
    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
    uiPreferences: {
        colorsSet: {
            [THEME.DARK]: {
                connectButton: {
                    background: '#29CC6A'
                }
            }
        }
    }
});

查看所有可用选项

组合选项

可以同时更改所有需要的选项：

tonConnectUI.uiOptions = {
    uiPreferences: {
        theme: THEME.DARK,
        borderRadius: 's',
        colorsSet: {
            [THEME.DARK]: {
                connectButton: {
                    background: '#29CC6A'
                }
            },
            [THEME.LIGHT]: {
                text: {
                    primary: '#FF0000'
                }
            }
        }
    }
};

直接 CSS 自定义

不推荐通过 CSS 自定义 TonConnect UI 元素，因为这可能会混淆用户在寻找已知和熟悉的 UI 元素（如连接按钮/模态窗口）时的体验。然而，如果需要，您可以为 UI 元素指定的选择器添加 CSS 样式。请参阅下表中的选择器列表：

UI 组件：

元素	选择器	元素描述
连接钱包模态窗口容器	`[data-tc-wallets-modal-container="true"]`	打开“连接钱包”按钮时显示的模态窗口的容器。
移动端通用模态页面内容	`[data-tc-wallets-modal-universal-mobile="true"]`	通用移动模态页面的内容，带有水平列表。
桌面端通用模态页面内容	`[data-tc-wallets-modal-universal-desktop="true"]`	通用桌面模态页面的内容，带有 QR 码。
移动端选定钱包的模态页面	`[data-tc-wallets-modal-connection-mobile="true"]`	移动端选定钱包的模态页面的内容。
桌面端选定钱包的模态页面	`[data-tc-wallets-modal-connection-desktop="true"]`	桌面端选定钱包的模态页面的内容。
钱包列表模态页面	`[data-tc-wallets-modal-list="true"]`	显示所有可用钱包列表的模态页面的内容（桌面和移动）。
信息模态页面	`[data-tc-wallets-modal-info="true"]`	“什么是钱包信息”模态页面的内容。
操作模态容器	`[data-tc-actions-modal-container="true"]`	调用 `sendTransaction` 或其他操作时显示的模态窗口的容器。
确认操作模态内容	`[data-tc-confirm-modal="true"]`	请求确认操作的模态窗口的内容。
“交易已发送”模态内容	`[data-tc-transaction-sent-modal="true"]`	通知交易成功发送的模态窗口的内容。
“交易已取消”模态内容	`[data-tc-transaction-canceled-modal="true"]`	通知交易未发送的模态窗口的内容。
“连接钱包”按钮	`[data-tc-connect-button="true"]`	“连接钱包”按钮元素。
钱包菜单加载按钮	`[data-tc-connect-button-loading="true"]`	在恢复连接过程中显示的按钮元素，替代“连接钱包”和下拉菜单按钮。
钱包菜单下拉按钮	`[data-tc-dropdown-button="true"]`	钱包菜单按钮——下拉钱包菜单的主机（复制地址/断开连接）。
钱包菜单下拉容器	`[data-tc-dropdown-container="true"]`	点击带有 ton 地址的“钱包菜单”按钮时显示的下拉菜单的容器。
钱包菜单下拉内容	`[data-tc-dropdown="true"]`	点击带有 ton 地址的“钱包菜单”按钮时显示的下拉菜单的内容。
通知容器	`[data-tc-list-notifications="true"]`	操作通知的容器。
确认通知	`[data-tc-notification-confirm="true"]`	确认通知元素。
交易已发送通知	`[data-tc-notification-tx-sent="true"]`	交易已发送通知元素。
取消的交易通知	`[data-tc-notification-tx-cancelled="true"]`	取消的交易通知元素。

基本 UI 元素：

元素	选择器
按钮	`[data-tc-button="true"]`
图标按钮	`[data-tc-icon-button="true"]`
模态窗口	`[data-tc-modal="true"]`
通知	`[data-tc-notification="true"]`
选项卡栏	`[data-tc-tab-bar="true"]`
H1	`[data-tc-h1="true"]`
H2	`[data-tc-h2="true"]`
H3	`[data-tc-h3="true"]`
文本	`[data-tc-text="true"]`
钱包项	`[data-tc-wallet-item="true"]`

自定义显示的钱包列表

您可以自定义显示的钱包列表：更改顺序、排除钱包或添加自定义钱包。

扩展钱包列表

传递自定义钱包数组以扩展钱包列表。传递的钱包将被添加到原始钱包列表的末尾。

您可以通过 jsBridgeKey（钱包为浏览器扩展或有钱包 dapp 浏览器）或 bridgeUrl 和 universalLink 对（用于 http 连接兼容的钱包）定义自定义钱包，或传递所有这些属性。

import { UIWallet } from '@tonconnect/ui';

const customWallet: UIWallet = {
    name: '<CUSTOM_WALLET_NAME>',
    imageUrl: '<CUSTOM_WALLET_IMAGE_URL>',
    aboutUrl: '<CUSTOM_WALLET_ABOUT_URL>',
    jsBridgeKey: '<CUSTOM_WALLET_JS_BRIDGE_KEY>',
    bridgeUrl: '<CUSTOM_WALLET_HTTP_BRIDGE_URL>',
    universalLink: '<CUSTOM_WALLET_UNIVERSAL_LINK>'
};

tonConnectUI.uiOptions = {
    walletsListConfiguration: {
        includeWallets: [customWallet]
    }
}

添加连接请求参数（ton_proof）

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

此函数接受一个参数：

在等待来自后端的响应时，将状态设置为“loading”。如果用户此时打开连接钱包模态窗口，他将看到一个加载器。

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

或

将状态设置为“ready”并定义 tonProof 值。传递的参数将应用于连接请求（QR 和通用链接）。

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

或

如果之前通过 state: 'loading' 启用了加载器（例如，您收到错误而不是来自后端的响应），则移除加载器。连接请求将不包含任何附加参数。

tonConnectUI.setConnectRequestParameters(null);

如果您的 tonProof 有限的生命周期，您可以多次调用 tonConnectUI.setConnectRequestParameters（例如，您可以每 10 分钟刷新连接请求参数）。

// 启用 UI 加载器
tonConnectUI.setConnectRequestParameters({ state: 'loading' });

// 从后端获取您的 tonProofPayload
const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
    // 移除加载器，连接请求将不包含任何附加参数
    tonConnectUI.setConnectRequestParameters(null);
} else {
    // 将 tonProof 添加到连接请求
    tonConnectUI.setConnectRequestParameters({
        state: "ready",
        value: { tonProof: tonProofPayload }
    });
}

当钱包连接时，您可以在 wallet 对象中找到 ton_proof 结果：

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

故障排除

Android 返回按钮处理

如果您遇到 Android 返回按钮处理的问题，例如按返回按钮时模态窗口无法正常关闭，或者如果您在应用中手动处理浏览器历史记录时与 history.pushState() 冲突，您可以通过将 enableAndroidBackHandler 设置为 false 来禁用返回按钮处理：

const tonConnectUI = new TonConnectUI({
    // ...
    enableAndroidBackHandler: false
});

这将禁用 Android 上的自定义返回按钮行为，您可以在应用中手动处理返回按钮按下操作。

虽然我们不预见 Android 返回按钮处理会出现任何问题，但如果您发现自己需要因某个问题而禁用它，请在 GitHub Issues 上描述问题，以便我们进一步协助您。

动画不工作

如果您在环境中遇到动画不工作的问题，可能是由于缺少对 Web Animations API 的支持。要解决此问题，您可以使用 web-animations-js polyfill。

使用 npm

要安装 polyfill，请运行以下命令：

shell

npm install web-animations-js

然后，在您的项目中导入 polyfill：

typescript

import 'web-animations-js';

使用 CDN

或者，您可以通过 CDN 包含 polyfill，添加以下脚本标签到您的 HTML：

html

<script src="https://www.unpkg.com/web-animations-js@latest/web-animations.min.js"></script>

这两种方法都将提供 Web Animations API 的回退实现，应能解决您遇到的动画问题。

Next.js 中的 'encoding' 模块警告

如果您在使用 Next.js 时看到类似以下的警告：

 ⚠ ./node_modules/node-fetch/lib/index.js
Module not found: Can't resolve 'encoding' in '.../node_modules/node-fetch/lib'

Import trace for requested module:
./node_modules/node-fetch/lib/index.js
./node_modules/@tonconnect/isomorphic-fetch/index.mjs
./node_modules/@tonconnect/sdk/lib/esm/index.mjs
./node_modules/@tonconnect/ui/lib/esm/index.mjs

请注意，这只是一个警告，不会影响您的应用功能。如果您希望抑制警告，您有两个选项：

（推荐）等待我们在未来版本中移除对 @tonconnect/isomorphic-fetch 的依赖。当我们停止支持 Node.js 低于 18 版本时将移除此依赖。
（可选）安装 encoding 包，以解决警告：

shell

npm install encoding

TON Connect UI ​

入门指南 ​

使用 CDN 安装 ​

使用 npm 安装 ​

使用方法 ​

创建 TonConnectUI 实例 ​

如有需要更改选项 ​

获取钱包列表 ​

打开连接模态窗口 ​

关闭连接模态窗口 ​

获取当前模态窗口状态 ​

订阅模态窗口状态变化 ​

钱包模态窗口控制 ​

打开特定钱包 ​

获取当前连接的钱包和钱包信息 ​

订阅连接状态变化 ​

断开钱包连接 ​

发送交易 ​

通用链接重定向问题（iOS） ​

添加返回策略 ​

在 TMA（Telegram Mini Apps）中使用 ​

检测连接恢复过程的结束 ​

UI 自定义 ​

使用 tonconnectUI.uiOptions 自定义 UI ​

更改边框半径 ​

更改主题 ​

更改颜色方案 ​

组合选项 ​

直接 CSS 自定义 ​

自定义显示的钱包列表 ​

扩展钱包列表 ​

添加连接请求参数（ton_proof） ​

故障排除 ​

Android 返回按钮处理 ​

动画不工作 ​

使用 npm ​

使用 CDN ​

Next.js 中的 'encoding' 模块警告 ​

TON Connect UI

入门指南

使用 CDN 安装

使用 npm 安装

使用方法

创建 TonConnectUI 实例

如有需要更改选项

获取钱包列表

打开连接模态窗口

关闭连接模态窗口

获取当前模态窗口状态

订阅模态窗口状态变化

钱包模态窗口控制

打开特定钱包

获取当前连接的钱包和钱包信息

订阅连接状态变化

断开钱包连接

发送交易

通用链接重定向问题（iOS）

添加返回策略

在 TMA（Telegram Mini Apps）中使用

检测连接恢复过程的结束

UI 自定义

使用 tonconnectUI.uiOptions 自定义 UI

更改边框半径

更改主题

更改颜色方案

组合选项

直接 CSS 自定义

自定义显示的钱包列表

扩展钱包列表

添加连接请求参数（ton_proof）

故障排除

Android 返回按钮处理

动画不工作

使用 npm

使用 CDN

Next.js 中的 'encoding' 模块警告