TypeScript SDK: 查看与查询

目的

指导对 @aptos-labs/ts-sdk 中链上数据的只读访问：视图函数、余额、账户信息、资源和模块。

始终

1. 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. 1. 不要使用已弃用的 getAccountCoinAmount 或 getAccountAPTAmount – 使用 getBalance()。
2. 不要对 u128/u256 使用 number – 会丢失精度；使用 bigint。
3. 不要假设视图返回值总是字符串 – 类型多种多样（number、bigint、string、boolean、array）。

getBalance (APT)

typescript
const balance = await aptos.getBalance({
accountAddress: account.accountAddress
});
// balance 是 bigint 类型，单位为 octas（1 APT = 100000000 octas）
const apt = balance / 100000000n;
const remainder = balance % 100000000n;
console.log(${apt}.${remainder.toString().padStart(8, 0)} APT);

getAccountInfo

typescript
const accountInfo = await aptos.getAccountInfo({
accountAddress: 0x1
});
// accountInfo: { sequencenumber, authenticationkey, ... }

view() – Move 视图函数

typescript
// 无类型参数
const result = await aptos.view({
payload: {
function: ${MODULEADDRESS}::counter::getcount,
functionArguments: [accountAddress]
}
});
const count = Number(result[0]);

// 带类型参数（例如 coin 类型）
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: ${MODULEADDRESS}::marketplace::getlisting,
functionArguments: [listingAddress]
}
});
const listing = {
seller: seller as string,
price: BigInt(price as string),
isActive: isActive as boolean
};

getAccountResources

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

getAccountResource（单一类型）

typescript
const resource = await aptos.getAccountResource({
accountAddress: account.accountAddress,
resourceType: ${MODULE_ADDRESS}::counter::Counter
});
// resource.data 包含结构体字段
const value = (resource?.data as { value: number })?.value;

getAccountModules

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

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

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

分页（资源/模块）

在可用时使用基于游标的选项：

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

视图结果的类型处理