getObject
通过 32 字节十六进制对象 ID,检索单个 Sui 对象的链上详细信息和元数据。
使用此方法可检查 Move 包和对象所有权,也可查看结构体字段。读取操作不会更改对象。getObject 从全节点状态中读取数据,运行时无需交易、Gas 或钱包签名。
- 类:
SuiClient - 包:
@mysten/sui/client
签名
Signature
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>
参数
该方法接受一个对象,包含以下属性。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
id | string | 是 | 32 字节的十六进制对象 ID,例如 0x123...。 |
options | SuiObjectDataOptions | 否 | 用于控制响应数据字段的标志。每个标志默认值为 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 开头且长度正确。 |
参见
multiGetObjects可通过单次批量请求获取四个对象的详细信息。getOwnedObjects列出特定地址拥有的所有对象。- 如何获取对象数据 提供了一个在 Node.js 脚本中使用
getObject的教程。 - SuiClient 架构 解释了
SuiClient及读取操作的概念设计。