API 参考: getObject

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

使用此方法可查询 Move 包定义、检查结构体字段以及验证对象所有权。您还可以检查某笔交易是否修改或删除了某个对象。由于 getObject 是一项直接从全节点本地状态中提供服务的读取操作，因此它会立即执行，无需提交交易或消耗 gas。

• 类: SuiClient
• 包: @mysten/sui/client
• 操作类型: 读取操作（无需 gas，无需钱包签名）

---

签名

签名

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	返回最后一次修改此对象的交易摘要。

---

返回值

返回一个解析为 SuiObjectResponse 的 Promise。此响应是一个标准封装体，同时封装了成功和错误状态：

SuiObjectResponse 封装体

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

成功响应 (data)

当对象存在且可访问时，data 属性将包含 SuiObjectData。

响应: 成功

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

错误响应 (error)

如果某笔交易删除了该对象、将其封装到另一个对象中，或者该 ID 不存在，则 error 属性将返回错误详情。

响应: 错误

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

---

使用示例

检查对象是否存在

这是最轻量级的查询。它不请求任何数据字段，仅请求摘要和版本号。

checkExists.js

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

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

获取 NFT 元数据和 Display 字段

此请求通过 content 读取链上字段，并通过 display 获取 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}, 图片: ${imageUrl}`);
} else {
    console.warn("加载项目失败:", 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("您拥有该项目。");
}

---

常见错误

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

---

另请参阅

• multiGetObjects: 通过单次批量请求获取多个对象的详细信息。
• getOwnedObjects: 列出特定地址拥有的所有对象。
• 如何获取对象数据: 在 Node.js 脚本中实现 getObject 的分步教程。
• SuiClient 架构: 解释 SuiClient 及读取操作的概念设计。