---
title: ZEPETO.Multiplay.Inventory
slug: world-sdk-guide-ch/zepetomultiplayinventory
docTags: 
createdAt: 2026-09-04T05:49:36.862Z
---

| 类型                                    | 说明                                     |
| ------------------------------------- | -------------------------------------- |
| [InventoryError](./#inventoryerror)   | 表示库存相关请求失败原因的错误代码。                     |
| [InventoryRecord](./#inventoryrecord) | 库存商品信息。                                |
| [Inventory](./#inventory)             | `Inventory` 用于管理与玩家的 World 内商品库存相关的操作。 |

## InventoryError

`enum`

表示库存相关请求失败原因的错误代码。

| 名称           | 值  | 说明                          |
| ------------ | -- | --------------------------- |
| Unknown      | -1 | 错误：未知错误。                    |
| NetworkError | 0  | 错误：与网络问题相关的错误，包括连接中断或连接不稳定。 |

## InventoryRecord

`interface`

库存商品信息。

### 属性

| 名称        | 类型       | 说明                |
| --------- | -------- | ----------------- |
| productId | `string` | 商品 ID。            |
| quantity  | `number` | 商品数量。             |
| createdAt | `Date`   | 商品被添加到库存的日期和时间。   |
| updatedAt | `Date`   | 商品信息最后一次更新的日期和时间。 |

## Inventory

`interface`

`Inventory` 用于管理与玩家的 World 内商品库存相关的操作。

### 方法

### use

`use(productId: string, quantity?: number, reason?: string) → Promise<boolean>`

使用玩家库存中的 World 内商品。会抛出 `InventoryError`。

| 参数            | 类型       | 说明                 |
| ------------- | -------- | ------------------ |
| productId     | `string` | 要使用的商品 ID。         |
| quantity （可选） | `number` | 要使用的商品数量。默认值为 `1`。 |
| reason （可选）   | `string` | 可选择性地说明使用原因。       |

**返回值：** `Promise<boolean>` — 处理完成时兑现的 `Promise`，表示成功（`true`）或失败（`false`）。

### add

`add(productId: string, quantity?: number, reason?: string) → Promise<boolean>`

向玩家库存中添加 World 内商品。会抛出 `InventoryError`。

| 参数            | 类型       | 说明                 |
| ------------- | -------- | ------------------ |
| productId     | `string` | 要添加的商品 ID。         |
| quantity （可选） | `number` | 要添加的商品数量。默认值为 `1`。 |
| reason （可选）   | `string` | 可选择性地说明添加原因。       |

**返回值：** `Promise<boolean>` — 处理完成时兑现的 `Promise`，表示成功（`true`）或失败（`false`）。

### madd

`madd(products: { productId: string; quantity: number; reason?: string }[]) → Promise<boolean>`

向玩家库存中批量添加 World 内商品。会抛出 `InventoryError`。

| 参数       | 类型                                                           | 说明        |
| -------- | ------------------------------------------------------------ | --------- |
| products | `{ productId: string; quantity: number; reason?: string }[]` | 要添加的商品数组。 |

**返回值：** `Promise<boolean>` — 处理完成时兑现的 `Promise`，表示成功（`true`）或失败（`false`）。

### has

`has(productId: string) → Promise<boolean>`

检查玩家库存中是否存在指定的 World 内商品。会抛出 `InventoryError`。

| 参数        | 类型       | 说明         |
| --------- | -------- | ---------- |
| productId | `string` | 要检查的商品 ID。 |

**返回值：** `Promise<boolean>` — 处理完成时兑现的 `Promise`，表示存在（`true`）或不存在（`false`）。

### get

`get(productId: string) → Promise<InventoryRecord | null>`

从玩家库存中获取 World 内商品。会抛出 `InventoryError`。

| 参数        | 类型       | 说明         |
| --------- | -------- | ---------- |
| productId | `string` | 要获取的商品 ID。 |

**返回值：** `Promise<InventoryRecord | null>` — 处理完成时兑现的 `Promise`，携带获取到的 `InventoryRecord` 对象。

### remove

`remove(productId: string) → Promise<boolean>`

从玩家库存中移除 World 内商品。会抛出 `InventoryError`。

| 参数        | 类型       | 说明         |
| --------- | -------- | ---------- |
| productId | `string` | 要移除的商品 ID。 |

**返回值：** `Promise<boolean>` — 处理完成时兑现的 `Promise`，表示成功（`true`）或失败（`false`）。

### list

`list() → Promise<InventoryRecord[]>`

从玩家库存中获取所有 World 内商品。会抛出 `InventoryError`。

**返回值：** `Promise<InventoryRecord[]>` — 处理完成时兑现的 `Promise`，携带获取到的 `InventoryRecord` 对象数组。