ts-sdk-view-and-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript SDK: View and Query

TypeScript SDK：视图与查询

Purpose

用途

Guide read-only access to chain data in

@aptos-labs/ts-sdk

: view functions, balance, account info, resources, and modules.

指导如何通过

@aptos-labs/ts-sdk

以只读方式访问链上数据：包括视图函数、余额、账户信息、资源和模块。

ALWAYS

注意事项（必做）

Use
aptos.getBalance({ accountAddress })
for APT balance – not deprecated

getAccountCoinAmount

getAccountAPTAmount

Use
aptos.view()
for Move view functions – pass

function

functionArguments

, and optional

typeArguments

Use
bigint
for u128/u256 view return values – cast
```
result[0]
```
to
```
BigInt(...)
```
when the Move function returns u128/u256.
Pass address as string or AccountAddress – SDK accepts
```
AccountAddressInput
```
(string or
```
AccountAddress
```
).

获取APT余额请使用
aptos.getBalance({ accountAddress })
– 不要使用已弃用的

getAccountCoinAmount

getAccountAPTAmount

。

调用Move视图函数请使用
aptos.view()
– 传入
```
function
```
、
```
functionArguments
```
，可选传入
```
typeArguments
```
。
u128/u256类型的视图返回值请使用
bigint
处理 – 当Move函数返回u128/u256时，将
```
result[0]
```
转换为
```
BigInt(...)
```
。
地址参数可传入字符串或AccountAddress – SDK支持
```
AccountAddressInput
```
类型（字符串或
```
AccountAddress
```
实例）。

NEVER

注意事项（禁止）

Do not use deprecated
getAccountCoinAmount
or
getAccountAPTAmount
– use

getBalance()

Do not use
number
for u128/u256 – precision loss; use
```
bigint
```
.
Do not assume view returns are always strings – types vary (number, bigint, string, boolean, array).

不要使用已弃用的
getAccountCoinAmount
或
getAccountAPTAmount
– 请使用

getBalance()

。

不要用
number
类型处理u128/u256 – 会丢失精度；请使用
```
bigint
```
。
不要假设视图返回值始终是字符串 – 返回类型多样（数字、bigint、字符串、布尔值、数组）。

getBalance (APT)

getBalance（APT余额）

typescript

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

typescript

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

getAccountInfo（获取账户信息）

typescript

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

typescript

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

view() – Move view functions

view() – Move视图函数

typescript

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

typescript

// 无类型参数
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

getAccountResources（获取账户资源列表）

typescript

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

typescript

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

getAccountResource (single type)

getAccountResource（获取单个类型的账户资源）

typescript

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;

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

getAccountModules（获取账户模块列表）

typescript

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

typescript

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

getModule (single module by name)

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

typescript

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

typescript

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

Pagination (resources / modules)

分页查询（资源/模块）

Use cursor-based options when available:

typescript

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

当支持时，使用基于游标选项：

typescript

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

Type handling for view results

视图返回值的类型处理

Move return type	TypeScript	Example
u8..u64	number or bigint	`Number(result[0])` or `BigInt(result[0])`
u128, u256	bigint	`BigInt(result[0] as string)`
address	string	`result[0] as string`
bool	boolean	`result[0] as boolean`
vector<T>	array	`result[0] as T[]`

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<T>	数组	`result[0] as T[]`

Common mistakes

常见错误

Mistake	Correct approach
Using getAccountCoinAmount	Use `aptos.getBalance({ accountAddress })`
Using number for u128	Use `BigInt(result[0] as string)`
Forgetting typeArguments for generic view	Add `typeArguments: [coinType]` when Move function is generic

错误做法	正确方式
使用getAccountCoinAmount	使用 `aptos.getBalance({ accountAddress })`
用number处理u128	使用 `BigInt(result[0] as string)`
泛型视图函数忘记传入typeArguments	当Move函数为泛型时，添加 `typeArguments: [coinType]`

References

参考资料

SDK:
```
src/internal/view.ts
```
,
```
src/api/account.ts
```
, balance/getBalance in internal
Pattern: TYPESCRIPT_SDK.md
Related: ts-sdk-client, ts-sdk-types, use-ts-sdk

SDK源码：
```
src/internal/view.ts
```
、
```
src/api/account.ts
```
，以及内部的balance/getBalance模块
模式文档：TYPESCRIPT_SDK.md
相关文档：ts-sdk-client、ts-sdk-types、use-ts-sdk