ts-sdk-wallet-adapter

TypeScript SDK：钱包适配器（React）

用途

在 React 中使用 @aptos-labs/wallet-adapter-react 引导钱包连接和前端交易提交。终端用户通过浏览器钱包（Petra、Nightly 等）签署交易，而不是使用原始私钥。

始终遵循

1. 使用 @aptos-labs/wallet-adapter-react 集成前端钱包——这是标准的 React 适配器。
2. 使用 AptosWalletAdapterProvider 包裹应用根节点——所有 useWallet() 调用都需要此上下文。
3. 使用 useWallet() Hook 在 React 组件中访问钱包功能。
4. 在前端使用钱包适配器的 signAndSubmitTransaction（来自 useWallet()）——不要使用 SDK 的直接调用 aptos.signAndSubmitTransaction。
5. 提交后始终调用 aptos.waitForTransaction({ transactionHash })——钱包在交易被接受时返回，而不是在交易提交完成时返回。

绝不

1. 不要在浏览器／前端使用 Account.generate() 或原始私钥——终端用户应使用钱包适配器。
2. 不要在 React 组件中使用 SDK 的 aptos.signAndSubmitTransaction——使用 useWallet() 提供的钱包适配器版本。
3. 不要硬编码钱包名称——使用 useWallet() 中的 wallets 数组生成动态列表。

---

安装

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

现代 AIP-62 标准钱包（Petra、Nightly 等）会自动检测，无需安装其他软件包。旧版钱包需要单独安装其插件软件包。

---

设置 Provider

使用 AptosWalletAdapterProvider 包裹应用根节点：

// 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

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();
}

---

前端交易模式

使用 InputTransactionData 类型化载荷：

// 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: []
    }
  };
}

// 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>;
}

---

钱包连接界面

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>
  );
}

---

常见错误

错误	正确做法
未使用 AptosWalletAdapterProvider 包裹	使用 Provider 包裹应用根节点
提交后未等待交易	始终调用 aptos.waitForTransaction()
在 React 中使用 SDK 的 aptos.signAndSubmitTransaction	使用 useWallet() 提供的钱包适配器 signAndSubmitTransaction
在前端使用 Account.generate()	使用钱包适配器；仅在服务器／脚本中生成
未处理用户拒绝	捕获错误并检查与拒绝相关的错误消息
硬编码钱包名称	使用 useWallet() 中的 wallets 数组生成动态列表

---

参考资料

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