跳到主要内容

API 参考：getObject

从区块链中检索特定对象的详细信息。

类： SuiClient 方法类型： 读取操作，无需 gas

签名​

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

参数​

该方法接受一个包含以下属性的配置对象：

参数类型必填描述
idstring是32 字节的十六进制对象 ID，例如 0x123...。
optionsSuiObjectDataOptions否用于控制响应中特定数据字段的配置标志。默认情况下所有字段均为 false。

SuiObjectDataOptions​

默认情况下，getObject 仅返回对象的引用，即其 ID、版本和摘要。若要获取实际数据，必须将这些标志显式设置为 true。

选项描述
showType返回 Move 类型，例如 0x2::coin::Coin<SUI>。
showContent返回解析后的 Move 数据字段，即对象的内部状态。
showOwner返回拥有该项目的地址或对象。
showDisplay返回 Display 标准元数据（特别是图片和名称），用于 UI 渲染。
showStorageRebate返回与该对象关联的存储返利。

返回值​

返回一个 Promise，其解析结果为 SuiObjectResponse。该响应是一个标准封装器，用于处理成功和错误状态。

1. 成功响应（data）​

如果对象存在且访问权限有效，则 data 属性包含 SuiObjectData。

{
  "data": {
    "objectId": "0x...",
    "version": "10",
    "digest": "...",
    "type": "0x2::coin::Coin<0x2::sui::SUI>", // Present if showType: true
    "content": {                              // Present if showContent: true
       "dataType": "moveObject",
       "fields": { "balance": "1000000000" }
    },
    "owner": {                                // Present if showOwner: true
       "AddressOwner": "0xabc..." 
    }
  }
}

2. 错误响应（error）​

如果对象已被删除、被另一个对象封装，或不存在，则 error 属性包含相应值。

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

使用示例​

场景 A：检查对象是否存在​

这是最轻量级的查询。它不请求任何数据，仅获取摘要/版本。

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

if (response.error) {
    console.log("对象不存在。");
} else {
    console.log("对象存在，版本号为：", response.data.version);
}

场景 B：获取非同质化代币的元数据​

此请求通过 content 字段读取字段信息，并通过 display 字段获取图片地址。

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

const name = nft.data.content.fields.name;
const imageUrl = nft.data.display.data.image_url;

场景 C：验证所有权​

使用此方法检查特定用户是否拥有某项资产。

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

const owner = item.data.owner;

if (owner && owner.AddressOwner === '0xMyAddress...') {
    console.log("您拥有此物品。");
}

常见错误​

错误代码原因解决方法
notExists对象 ID 格式为有效的十六进制数，但在网络上未找到该对象。检查 ID 或确保该对象未在之前的交易中被删除。
deleted该对象曾存在但已被销毁或您已将其删除。无法获取已删除对象的数据。
invalid_param提供的对象 ID 不是有效的 32 字节十六进制字符串。确保 ID 以 0x 开头且长度正确。

参见​