TypeScript SDK：查看与查询

目的

指导如何在 @aptos-labs/ts-sdk 中进行只读链上数据访问：调用 Move 视图函数、查询 APT 余额、账户信息、资源（resources）和模块（modules）。

务必遵守

1. 使用 aptos.getBalance({ accountAddress }) 查询 APT 余额 —— 不要使用已弃用的 getAccountCoinAmount / getAccountAPTAmount。
2. 使用 aptos.view() 调用 Move 视图函数 —— 传入 function、functionArguments，以及可选的 typeArguments。
3. 对返回 u128/u256 的视图函数，使用 bigint 类型接收结果 —— 当 Move 函数返回 u128/u256 时，请将 result[0] 显式转换为 BigInt(...)。
4. 地址参数支持字符串或 AccountAddress 实例 —— SDK 接受 AccountAddressInput 类型（即字符串或 AccountAddress 对象）。

严禁操作

1. 禁止使用已弃用的 getAccountCoinAmount 或 getAccountAPTAmount —— 请统一使用 getBalance()。
2. 禁止对 u128/u256 使用 number 类型 —— 将导致精度丢失；必须使用 bigint。
3. 不要假设视图函数返回值总是字符串 —— 返回类型多样（number、bigint、string、boolean、array 等）。

getBalance（APT 余额）

const balance = await aptos.getBalance({
  accountAddress: account.accountAddress
});
// balance 是以 octas 为单位的 bigint（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 视图函数

// 无类型参数（type arguments）
const result = await aptos.view({
  payload: {
    function: `${MODULE_ADDRESS}::counter::get_count`,
    functionArguments: [accountAddress]
  }
});
const count = Number(result[0]);

// 带类型参数（例如代币类型）
const balanceResult = await aptos.view({
  payload: {
    function: "0x1::coin::balance",
    typeArguments: ["0x1::aptos_coin::AptosCoin"],
    functionArguments: [accountAddress]
  }
});
const coinBalance = BigInt(balanceResult[0] as string);

// 多返回值示例
// 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
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 包含结构体字段
const value = (resource?.data as { value: number })?.value;

getAccountModules（获取全部模块）

const modules = await aptos.getAccountModules({
  accountAddress: modulePublisherAddress
});
// modules: MoveModuleBytecode[]（含 ABI 和字节码）

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

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

分页（资源 / 模块）

当接口支持时，请使用基于游标的分页选项：

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

视图函数返回值的类型处理

常见错误

参考资料

• SDK 源码：src/internal/view.ts、src/api/account.ts，以及内部实现中的 balance/getBalance
• 规范文档：TYPESCRIPT_SDK.md
• 相关项目：ts-sdk-client、ts-sdk-types、use-ts-sdk