ts-sdk-wallet-adapter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript SDK: Wallet Adapter (React)

TypeScript SDK：钱包适配器（React）

Purpose

用途

Guide wallet connection and frontend transaction submission in React using

@aptos-labs/wallet-adapter-react

. End users sign transactions via their browser wallet (Petra, Nightly, etc.) — never via raw private keys.

指导你使用

@aptos-labs/wallet-adapter-react

在React中实现钱包连接和前端交易提交功能。终端用户通过其浏览器钱包（Petra、Nightly等）对交易签名，永远不需要使用原始私钥。

ALWAYS

必须遵守的规则

Use
@aptos-labs/wallet-adapter-react
for frontend wallet integration — this is the standard React adapter.
Wrap your app root with
AptosWalletAdapterProvider
— all
```
useWallet()
```
calls require this context.
Use
useWallet()
hook to access wallet functions in React components.
Use the wallet adapter's
signAndSubmitTransaction
(from
```
useWallet()
```
) in frontend — NOT the SDK's direct
```
aptos.signAndSubmitTransaction
```
.
Always call
aptos.waitForTransaction({ transactionHash })
after submit — the wallet returns when the tx is accepted, not committed.

前端钱包集成请使用
@aptos-labs/wallet-adapter-react
—— 这是标准的React适配器。
使用
AptosWalletAdapterProvider
包裹你的应用根组件 —— 所有
```
useWallet()
```
调用都需要这个上下文。
使用
useWallet()
钩子在React组件中访问钱包功能。
在前端使用钱包适配器提供的
signAndSubmitTransaction
（来自
useWallet()
） —— 不要直接使用SDK的
```
aptos.signAndSubmitTransaction
```
。
提交后务必调用
aptos.waitForTransaction({ transactionHash })
—— 钱包会在交易被接受时返回，而非交易被确认时。

NEVER

禁止操作

Do not use
Account.generate()
or raw private keys in browser/frontend — use wallet adapter for end users.
Do not use the SDK's
aptos.signAndSubmitTransaction
in React components — use the wallet adapter's version from
```
useWallet()
```
.
Do not hardcode wallet names — use the
```
wallets
```
array from
```
useWallet()
```
for a dynamic list.

不要在浏览器/前端中使用
Account.generate()
或原始私钥 —— 面向终端用户请使用钱包适配器。
不要在React组件中使用SDK的
aptos.signAndSubmitTransaction
—— 请使用
```
useWallet()
```
返回的钱包适配器版本。
不要硬编码钱包名称 —— 请使用
```
useWallet()
```
返回的
```
wallets
```
数组生成动态列表。

Installation

安装

bash

npm install @aptos-labs/wallet-adapter-react

Modern AIP-62 standard wallets (Petra, Nightly, etc.) are autodetected and do NOT require additional packages. Legacy wallets need their plugin package installed separately.

bash

npm install @aptos-labs/wallet-adapter-react

符合AIP-62标准的现代钱包（Petra、Nightly等）会被自动检测，不需要额外安装包。旧版钱包需要单独安装对应的插件包。

Provider setup

Provider配置

Wrap your app root with

AptosWalletAdapterProvider

tsx

// main.tsx or App.tsx
import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
import { Network } from "@aptos-labs/ts-sdk";

function App() {
  return (
    <AptosWalletAdapterProvider
      autoConnect={true}
      dappConfig={{
        network: Network.TESTNET,
      }}
      onError={(error) => console.error("Wallet error:", error)}
    >
      <YourApp />
    </AptosWalletAdapterProvider>
  );
}

使用

AptosWalletAdapterProvider

包裹应用根组件：

tsx

// main.tsx or App.tsx
import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
import { Network } from "@aptos-labs/ts-sdk";

function App() {
  return (
    <AptosWalletAdapterProvider
      autoConnect={true}
      dappConfig={{
        network: Network.TESTNET,
      }}
      onError={(error) => console.error("Wallet error:", error)}
    >
      <YourApp />
    </AptosWalletAdapterProvider>
  );
}

useWallet() hook

useWallet()钩子

tsx

import { useWallet } from "@aptos-labs/wallet-adapter-react";

function MyComponent() {
  const {
    account,                  // Current connected account { address, publicKey }
    connected,                // Boolean: is wallet connected?
    wallet,                   // Current wallet info { name, icon, url }
    wallets,                  // Array of available wallets
    connect,                  // (walletName) => Promise<void>
    disconnect,               // () => Promise<void>
    signAndSubmitTransaction, // Submit entry function calls (use THIS in frontend)
    signTransaction,          // Sign without submitting
    submitTransaction,        // Submit a signed transaction
    signMessage,              // Sign an arbitrary message
    signMessageAndVerify,     // Sign and verify a message
    changeNetwork,            // Switch networks (not all wallets support this)
    network,                  // Current network info
  } = useWallet();
}

tsx

import { useWallet } from "@aptos-labs/wallet-adapter-react";

function MyComponent() {
  const {
    account,                  // 当前连接的账户 { address, publicKey }
    connected,                // 布尔值：钱包是否已连接？
    wallet,                   // 当前钱包信息 { name, icon, url }
    wallets,                  // 可用钱包数组
    connect,                  // (walletName) => Promise<void>
    disconnect,               // () => Promise<void>
    signAndSubmitTransaction, // 提交入口函数调用（前端请使用这个）
    signTransaction,          // 仅签名不提交
    submitTransaction,        // 提交已签名的交易
    signMessage,              // 对任意消息签名
    signMessageAndVerify,     // 签名并验证消息
    changeNetwork,            // 切换网络（并非所有钱包都支持）
    network,                  // 当前网络信息
  } = useWallet();
}

Frontend transaction pattern

前端交易实现模式

Use typed payloads with

InputTransactionData

tsx

// entry-functions/increment.ts
import { InputTransactionData } from "@aptos-labs/wallet-adapter-react";
import { MODULE_ADDRESS } from "../lib/aptos";

export function buildIncrementPayload(): InputTransactionData {
  return {
    data: {
      function: `${MODULE_ADDRESS}::counter::increment`,
      functionArguments: [],
    },
  };
}

tsx

// components/IncrementButton.tsx
import { useWallet } from "@aptos-labs/wallet-adapter-react";
import { aptos } from "../lib/aptos";
import { buildIncrementPayload } from "../entry-functions/increment";

function IncrementButton() {
  const { signAndSubmitTransaction } = useWallet();

  const handleClick = async () => {
    try {
      const response = await signAndSubmitTransaction(
        buildIncrementPayload(),
      );
      await aptos.waitForTransaction({
        transactionHash: response.hash,
      });
    } catch (error) {
      console.error("Transaction failed:", error);
    }
  };

  return <button onClick={handleClick}>Increment</button>;
}

配合

InputTransactionData

使用类型化负载：

tsx

// entry-functions/increment.ts
import { InputTransactionData } from "@aptos-labs/wallet-adapter-react";
import { MODULE_ADDRESS } from "../lib/aptos";

export function buildIncrementPayload(): InputTransactionData {
  return {
    data: {
      function: `${MODULE_ADDRESS}::counter::increment`,
      functionArguments: [],
    },
  };
}

tsx

// components/IncrementButton.tsx
import { useWallet } from "@aptos-labs/wallet-adapter-react";
import { aptos } from "../lib/aptos";
import { buildIncrementPayload } from "../entry-functions/increment";

function IncrementButton() {
  const { signAndSubmitTransaction } = useWallet();

  const handleClick = async () => {
    try {
      const response = await signAndSubmitTransaction(
        buildIncrementPayload(),
      );
      await aptos.waitForTransaction({
        transactionHash: response.hash,
      });
    } catch (error) {
      console.error("Transaction failed:", error);
    }
  };

  return <button onClick={handleClick}>Increment</button>;
}

Wallet connection UI

钱包连接UI

tsx

import { useWallet } from "@aptos-labs/wallet-adapter-react";

function WalletInfo() {
  const { account, connected, connect, disconnect, wallet, wallets } =
    useWallet();

  if (!connected) {
    return (
      <div>
        {wallets.map((w) => (
          <button key={w.name} onClick={() => connect(w.name)}>
            Connect {w.name}
          </button>
        ))}
      </div>
    );
  }

  return (
    <div>
      <p>Connected: {account?.address}</p>
      <p>Wallet: {wallet?.name}</p>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}

tsx

import { useWallet } from "@aptos-labs/wallet-adapter-react";

function WalletInfo() {
  const { account, connected, connect, disconnect, wallet, wallets } =
    useWallet();

  if (!connected) {
    return (
      <div>
        {wallets.map((w) => (
          <button key={w.name} onClick={() => connect(w.name)}>
            Connect {w.name}
          </button>
        ))}
      </div>
    );
  }

  return (
    <div>
      <p>已连接：{account?.address}</p>
      <p>钱包：{wallet?.name}</p>
      <button onClick={disconnect}>断开连接</button>
    </div>
  );
}

Common mistakes

常见错误

Mistake	Correct approach
Missing `AptosWalletAdapterProvider` wrapper	Wrap app root with the provider
Not waiting for transaction after submit	Always call `aptos.waitForTransaction()`
Using SDK `aptos.signAndSubmitTransaction` in React	Use the wallet adapter's `signAndSubmitTransaction` from `useWallet()`
Using `Account.generate()` in frontend	Use wallet adapter; generate only in server/scripts
Not handling user rejection	Catch and check for rejection-related error messages
Hardcoding wallet names	Use `wallets` array from `useWallet()` for dynamic list

错误做法	正确方案
没有添加 `AptosWalletAdapterProvider` 包裹	使用Provider包裹应用根组件
提交后没有等待交易确认	始终调用 `aptos.waitForTransaction()`
在React中使用SDK的 `aptos.signAndSubmitTransaction`	使用 `useWallet()` 返回的钱包适配器提供的 `signAndSubmitTransaction`
在前端使用 `Account.generate()`	使用钱包适配器；仅在服务端/脚本中生成账户
没有处理用户拒绝操作	捕获并校验拒绝相关的错误信息
硬编码钱包名称	使用 `useWallet()` 返回的 `wallets` 数组生成动态列表

References

参考资料

Wallet Adapter: https://aptos.dev/build/sdks/wallet-adapter/dapp
Pattern: TYPESCRIPT_SDK.md
Related: ts-sdk-transactions, ts-sdk-client, use-ts-sdk

钱包适配器：https://aptos.dev/build/sdks/wallet-adapter/dapp
实现模式：TYPESCRIPT_SDK.md
相关内容：ts-sdk-transactions、ts-sdk-client、use-ts-sdk