跳到主要内容

getObject

通过 32 字节十六进制对象 ID,检索单个 Sui 对象的链上详细信息和元数据。

使用此方法可检查 Move 包和对象所有权,也可查看结构体字段。读取操作不会更改对象。getObject 从全节点状态中读取数据,运行时无需交易、Gas 或钱包签名。

  • 类: SuiClient
  • 包: @mysten/sui/client

签名​

Signature
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>

参数​

该方法接受一个对象,包含以下属性。

参数类型必填描述
idstring是32 字节的十六进制对象 ID,例如 0x123...。
optionsSuiObjectDataOptions否用于控制响应数据字段的标志。每个标志默认值为 false。

SuiObjectDataOptions​

默认情况下,getObject 返回 ID、版本和摘要。将每个标志设置为 true 可获取更多数据。

选项描述
showType返回 Move 类型,例如 0x2::coin::Coin<0x2::sui::SUI>。
showContent返回经过解析的 Move 数据字段,代表对象的内部状态。
showOwner返回拥有此项所有权的地址或对象。
showDisplay返回用于 UI 渲染的 Display 标准元数据。该元数据包括名称、描述和图片 URL。
showStorageRebate返回与该对象关联的存储返利。
showBcs返回用于客户端解码的原始二进制规范序列化(BCS)字节。
showPreviousTransaction返回最后一次修改该对象的交易的摘要。

返回值​

返回一个 Promise,该 Promise 解析后返回 SuiObjectResponse。响应包含成功或错误数据:

SuiObjectResponse envelope
┌─────────────────────────────────────────────────────────────┐
│ SuiObjectResponse │
├──────────────────────────────┬──────────────────────────────┤
│ Success: `response.data` │ Error: `response.error` │
│ - objectId, version │ - code: "notExists" │
│ - type, digest │ - code: "deleted" │
│ - content, owner, display │ - object_id │
└──────────────────────────────┴──────────────────────────────┘

成功响应:data​

当对象存在时,其 data 属性包含 SuiObjectData。

Response: success
{
"data": {
"objectId": "0x...",
"version": "10",
"digest": "...",
"type": "0x2::coin::Coin<0x2::sui::SUI>",
"content": {
"dataType": "moveObject",
"fields": { "balance": "1000000000" }
},
"owner": {
"AddressOwner": "0xabc..."
}
}
}

错误响应:error​

当事务删除了该对象或将其封装到另一个对象中时,error 属性会返回详细信息。当 ID 不存在时,该属性也会返回详细信息。

Response: error
{
"error": {
"code": "notExists",
"object_id": "0x..."
}
}

使用示例​

检查对象是否存在​

此轻量级查询不请求数据字段,仅返回摘要和版本号。

checkExists.js
const response = await client.getObject({
id: '0x123...'
});

if (response.error) {
console.log("Object doesn't exist.");
} else if (response.data) {
console.log("Object exists at version:", response.data.version);
} else {
console.log("The response didn't include object data.");
}

获取非同质化代币元数据和显示字段​

此请求将 showContent 设置为读取链上字段,并将 showDisplay 设置为检索 UI 资源。

fetchNFT.js
const nft = await client.getObject({
id: '0x123...',
options: {
showContent: true,
showDisplay: true
}
});

if (nft.data) {
const name = nft.data.content?.fields?.name;
const imageUrl = nft.data.display?.data?.image_url;
console.log(`NFT Name: ${name}, Image: ${imageUrl}`);
} else {
console.warn("Item failed to load:", nft.error);
}

验证对象所有权​

使用此代码检查特定账户地址是否控制某项资产。

verifyOwnership.js
const item = await client.getObject({
id: '0x123...',
options: { showOwner: true }
});

const owner = item.data?.owner;

if (owner && owner.AddressOwner === '0xMyAddress...') {
console.log("You own this item.");
}

常见错误​

错误代码原因解决方法
notExists对象 ID 包含有效的十六进制字符串,但网络无法定位该对象。请验证 ID,或确认该对象未被之前的交易删除。
deleted某笔交易已将该对象从活动状态中删除、销毁或清理。无法通过 getObject 检索已删除对象的历史数据。
invalid_param对象 ID 的 32 字节十六进制格式不正确。请检查 ID 是否以 0x 开头且长度正确。

参见​