ts-sdk-view-and-query

TypeScript SDK：查看与查询

用途

介绍如何在 @aptos-labs/ts-sdk 中以只读方式访问链上数据：查看函数、余额、账户信息、资源和 模块。

始终

1. 使用 aptos.getBalance({ accountAddress }) 获取 APT 余额——不要使用已弃用的 getAccountCoinAmount / getAccountAPTAmount。
2. 使用 aptos.view() 调用 Move 查看函数——传入 function、functionArguments 和可选的 typeArguments。
3. 使用 bigint 处理 u128/u256 查看函数返回值——当 Move 函数返回 u128/u256 时，将 result[0] 转换为 BigInt(...)。
4. 将地址作为字符串或 AccountAddress 传入——SDK 接受 AccountAddressInput（字符串或 AccountAddress）。

禁止

1. 不要使用已弃用的 getAccountCoinAmount 或 getAccountAPTAmount——请使用 getBalance()。
2. 不要用 number 表示 u128/u256——这会导致精度损失；请使用 bigint。
3. 不要假设查看函数的返回值始终是字符串——类型可能不同（number、bigint、string、boolean、array）。

---

getBalance（APT）

const balance = await aptos.getBalance({
  accountAddress: account.accountAddress
});
// balance is bigint in octas (1 APT = 100_000_000 octas)
const apt = balance / 100_000_000n;
const remainder = balance % 100_000_000n;
console.log(`${apt}.${remainder.toString().padStart(8, "0")} APT`);

---

getAccountInfo

const accountInfo = await aptos.getAccountInfo({
  accountAddress: "0x1"
});
// accountInfo: { sequence_number, authentication_key, ... }

---

view() —— Move 查看函数

// No type arguments
const result = await aptos.view({
  payload: {
    function: `${MODULE_ADDRESS}::counter::get_count`,
    functionArguments: [accountAddress]
  }
});
const count = Number(result[0]);

// With type arguments (e.g. coin type)
const balanceResult = await aptos.view({
  payload: {
    function: "0x1::coin::balance",
    typeArguments: ["0x1::aptos_coin::AptosCoin"],
    functionArguments: [accountAddress]
  }
});
const coinBalance = BigInt(balanceResult[0] as string);

// Multiple return values
// Move: public fun get_listing(addr): (address, u64, bool)
const [seller, price, isActive] = await aptos.view({
  payload: {
    function: `${MODULE_ADDRESS}::marketplace::get_listing`,
    functionArguments: [listingAddress]
  }
});
const listing = {
  seller: seller as string,
  price: BigInt(price as string),
  isActive: isActive as boolean
};

---

getAccountResources

const resources = await aptos.getAccountResources({
  accountAddress: account.accountAddress
});
// resources: Array<MoveResource>
const counterResource = resources.find((r) => r.type === `${MODULE_ADDRESS}::counter::Counter`);

---

getAccountResource（单个类型）

const resource = await aptos.getAccountResource({
  accountAddress: account.accountAddress,
  resourceType: `${MODULE_ADDRESS}::counter::Counter`
});
// resource.data has the struct fields
const value = (resource?.data as { value: number })?.value;

---

getAccountModules

const modules = await aptos.getAccountModules({
  accountAddress: modulePublisherAddress
});
// modules: MoveModuleBytecode[] (ABI, bytecode)

---

getModule（按名称获取单个模块）

const module = await aptos.getModule({
  accountAddress: modulePublisherAddress,
  moduleName: "counter"
});

---

分页（资源／模块）

有可用选项时，请使用基于游标的选项：

const { resources, cursor } = await aptos.getAccountResourcesPage({
  accountAddress: account.accountAddress,
  options: { limit: 10, cursor: nextCursor }
});

---

查看结果的类型处理

Move 返回类型	TypeScript	示例
u8..u64	number 或 bigint	Number(result[0]) 或 BigInt(result[0])
u128, u256	bigint	BigInt(result[0] as string)
address	string	result[0] as string
bool	boolean	result[0] as boolean
vector	array	result[0] as T[]

---

常见错误

错误	正确做法
使用 getAccountCoinAmount	使用 aptos.getBalance({ accountAddress })
对 u128 使用 number	使用 BigInt(result[0] as string)
忘记为泛型查看函数传入 typeArguments	Move 函数为泛型时，添加 typeArguments: [coinType]

---

参考

• SDK：src/internal/view.ts、src/api/account.ts、internal 中的 balance/getBalance
• 模式：TYPESCRIPT_SDK.md
• 相关：ts-sdk-client、ts-sdk-types、 use-ts-sdk