#Class: ItemStack

Beta

定义一个物品集合。

Defines a collection of items.

#Examples

import { ItemStack, DimensionLocation } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function itemStacks(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const oneItemLoc = { x: targetLocation.x + targetLocation.y + 3, y: 2, z: targetLocation.z + 1 };
  const fiveItemsLoc = { x: targetLocation.x + 1, y: targetLocation.y + 2, z: targetLocation.z + 1 };
  const diamondPickaxeLoc = { x: targetLocation.x + 2, y: targetLocation.y + 2, z: targetLocation.z + 4 };

  const oneEmerald = new ItemStack(MinecraftItemTypes.Emerald, 1);
  const onePickaxe = new ItemStack(MinecraftItemTypes.DiamondPickaxe, 1);
  const fiveEmeralds = new ItemStack(MinecraftItemTypes.Emerald, 5);

  log(`Spawning an emerald at (${oneItemLoc.x}, ${oneItemLoc.y}, ${oneItemLoc.z})`);
  targetLocation.dimension.spawnItem(oneEmerald, oneItemLoc);

  log(`Spawning five emeralds at (${fiveItemsLoc.x}, ${fiveItemsLoc.y}, ${fiveItemsLoc.z})`);
  targetLocation.dimension.spawnItem(fiveEmeralds, fiveItemsLoc);

  log(`Spawning a diamond pickaxe at (${diamondPickaxeLoc.x}, ${diamondPickaxeLoc.y}, ${diamondPickaxeLoc.z})`);
  targetLocation.dimension.spawnItem(onePickaxe, diamondPickaxeLoc);
}

import {
  world,
  ItemStack,
  EntityEquippableComponent,
  EquipmentSlot,
  EntityComponentTypes,
  DimensionLocation,
} from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function givePlayerEquipment(targetLocation: DimensionLocation) {
  const players = world.getAllPlayers();

  const armorStandLoc = { x: targetLocation.x, y: targetLocation.y, z: targetLocation.z + 4 };
  const armorStand = players[0].dimension.spawnEntity(MinecraftItemTypes.ArmorStand, armorStandLoc);

  const equipmentCompPlayer = players[0].getComponent(EntityComponentTypes.Equippable) as EntityEquippableComponent;
  if (equipmentCompPlayer) {
    equipmentCompPlayer.setEquipment(EquipmentSlot.Head, new ItemStack(MinecraftItemTypes.GoldenHelmet));
    equipmentCompPlayer.setEquipment(EquipmentSlot.Chest, new ItemStack(MinecraftItemTypes.IronChestplate));
    equipmentCompPlayer.setEquipment(EquipmentSlot.Legs, new ItemStack(MinecraftItemTypes.DiamondLeggings));
    equipmentCompPlayer.setEquipment(EquipmentSlot.Feet, new ItemStack(MinecraftItemTypes.NetheriteBoots));
    equipmentCompPlayer.setEquipment(EquipmentSlot.Mainhand, new ItemStack(MinecraftItemTypes.WoodenSword));
    equipmentCompPlayer.setEquipment(EquipmentSlot.Offhand, new ItemStack(MinecraftItemTypes.Shield));
  }

  const equipmentCompArmorStand = armorStand.getComponent(EntityComponentTypes.Equippable) as EntityEquippableComponent;
  if (equipmentCompArmorStand) {
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Head, new ItemStack(MinecraftItemTypes.GoldenHelmet));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Chest, new ItemStack(MinecraftItemTypes.IronChestplate));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Legs, new ItemStack(MinecraftItemTypes.DiamondLeggings));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Feet, new ItemStack(MinecraftItemTypes.NetheriteBoots));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Mainhand, new ItemStack(MinecraftItemTypes.WoodenSword));
    equipmentCompArmorStand.setEquipment(EquipmentSlot.Offhand, new ItemStack(MinecraftItemTypes.Shield));
  }
}

import { ItemStack, DimensionLocation } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function spawnFeatherItem(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const featherItem = new ItemStack(MinecraftItemTypes.Feather, 1);

  targetLocation.dimension.spawnItem(featherItem, targetLocation);
  log(`New feather created at ${targetLocation.x}, ${targetLocation.y}, ${targetLocation.z}!`);
}

#Constructors

#Constructor

new ItemStack(itemType, amount?): ItemStack

Beta

#Parameters

#itemType

string | ItemType

要创建的物品类型。参见 @minecraft/vanilla-data.MinecraftItemTypes 枚举以获取 Minecraft 中标准物品类型的列表。

Type of item to create. See the @minecraft/vanilla-data.MinecraftItemTypes enumeration for a list of standard item types in Minecraft experiences.

#amount?

number

放入物品堆的物品数量，介于 1-255 之间。提供的值会被限制 在该物品的最大堆叠数量以内。注意某些物品的物品堆中只能有 一个物品。

Number of items to place in the stack, between 1-255. The provided value will be clamped to the item's maximum stack size. Note that certain items can only have one item in the stack. Defaults to: 1 Bounds: [1, 255]

#Returns

ItemStack

#Remarks

创建一个可在世界中使用的物品堆新实例。

Creates a new instance of a stack of items for use in the world.

#Throws

Throws if itemType is invalid, or if amount is outside the range of 1-255.

#Properties

#amount

amount: number

World Mutation Beta

#Remarks

物品堆中的物品数量。有效值范围为 1-255。提供的值会被 限制在该物品的最大堆叠数量以内。

Number of the items in the stack. Valid values range between 1-255. The provided value will be clamped to the item's maximum stack size.

Bounds: [1, 255]

#Throws

Throws if the value is outside the range of 1-255.

#isStackable

readonly isStackable: boolean

Beta

#Remarks

返回该物品是否可堆叠。当物品的最大堆叠数量大于 1 且不 包含任何自定义数据或属性时，该物品被视为可堆叠。

Returns whether the item is stackable. An item is considered stackable if the item's maximum stack size is greater than 1 and the item does not contain any custom data or properties.

#keepOnDeath

keepOnDeath: boolean

World Mutation Beta

#Remarks

获取或设置该物品是否在死亡时保留。

Gets or sets whether the item is kept on death.

#localizationKey

readonly localizationKey: string

Beta

#Remarks

用于在 .lang 文件中本地化该物品名称的键。

Key for the localization of this items's name used in .lang files.

#Throws

This property can throw when used.

EngineError

#lockMode

lockMode: ItemLockMode

World Mutation Beta

#Remarks

获取或设置该物品的锁定模式。默认值为 ItemLockMode.none。

Gets or sets the item's lock mode. The default value is ItemLockMode.none.

#maxAmount

readonly maxAmount: number

Beta

#Remarks

最大堆叠数量。该值因物品类型而异。例如，火把的最大堆叠 数量为 64，而鸡蛋的最大堆叠数量为 16。

The maximum stack size. This value varies depending on the type of item. For example, torches have a maximum stack size of 64, while eggs have a maximum stack size of 16.

#nameTag?

optional nameTag?: string

World Mutation Beta

#Remarks

该物品堆的给定名称。名称标签会在悬停于物品上时显示。将 名称标签设置为空字符串或 undefined 会移除名称标签。

Given name of this stack of items. The name tag is displayed when hovering over the item. Setting the name tag to an empty string or undefined will remove the name tag.

#Throws

Throws if the length exceeds 255 characters.

#type

readonly type: ItemType

Beta

#Remarks

该物品的类型。

The type of the item.

#typeId

readonly typeId: string

Beta

#Remarks

该物品堆的物品类型标识符。若未指定命名空间，则默认使用 'minecraft:'。例如 'wheat' 或 'apple'。

Identifier of the type of items for the stack. If a namespace is not specified, 'minecraft:' is assumed. Examples include 'wheat' or 'apple'.

#weight

readonly weight: number

Beta

#Remarks

物品堆中所有物品的总重量，加上由 Storage Item 组件定义 的物品容器内所有物品的重量。每个物品的重量可通过 Storage Weight Modifier 组件修改。

The total weight of all items in the stack plus the weight of all items in the items container which is defined with the Storage Item component. The weight per item can be modified by the Storage Weight Modifier component.

#Methods

#clearDynamicProperties()

clearDynamicProperties(): void

Beta

#Returns

void

#Remarks

清除已在该物品堆上设置的所有动态属性。

Clears all dynamic properties that have been set on this item stack.

#clone()

clone(): ItemStack

Beta

#Returns

ItemStack

返回该物品堆的一个副本。

Returns a copy of this item stack.

#Remarks

创建该物品堆的精确副本，包括任何自定义数据或属性。

Creates an exact copy of the item stack, including any custom data or properties.

#getCanDestroy()

getCanDestroy(): string[]

World Mutation Beta

#Returns

string[]

#Remarks

获取该物品在冒险模式下可破坏的方块类型列表。

Get the list of block types this item can break in Adventure mode.

#getCanPlaceOn()

getCanPlaceOn(): string[]

World Mutation Beta

#Returns

string[]

#Remarks

获取该物品在冒险模式下可放置于其上的方块类型列表。

Get the list of block types this item can be placed on in Adventure mode.

#getComponent()

getComponent<T>(componentId): ItemComponentReturnType<T> | undefined

Beta

#Type Parameters

#T

T extends string

#Parameters

#componentId

T

组件的标识符（例如 'minecraft:food'）。若未指定命名空间 前缀，则默认使用 'minecraft:'。可用的组件 ID 包括 ItemComponentTypes 枚举中的组件，以及通过 ItemComponentRegistry 注册的自定义组件 ID。

The identifier of the component (e.g., 'minecraft:food'). If no namespace prefix is specified, 'minecraft:' is assumed. Available component IDs are those in the ItemComponentTypes enum and custom component IDs registered with the ItemComponentRegistry.

#Returns

ItemComponentReturnType<T> | undefined

若该组件存在于物品堆上则返回该组件，否则返回 undefined。

Returns the component if it exists on the item stack, otherwise undefined.

#Remarks

获取物品堆的某个组件（表示附加功能）。

Gets a component (that represents additional capabilities) for an item stack.

#Example

giveHurtDiamondSword.ts

import {
  world,
  ItemStack,
  EntityInventoryComponent,
  EntityComponentTypes,
  ItemComponentTypes,
  ItemDurabilityComponent,
  DimensionLocation,
} from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function giveHurtDiamondSword(targetLocation: DimensionLocation) {
  const hurtDiamondSword = new ItemStack(MinecraftItemTypes.DiamondSword);

  const durabilityComponent = hurtDiamondSword.getComponent(ItemComponentTypes.Durability) as ItemDurabilityComponent;

  if (durabilityComponent !== undefined) {
    durabilityComponent.damage = durabilityComponent.maxDurability / 2;
  }

  for (const player of world.getAllPlayers()) {
    const inventory = player.getComponent(EntityComponentTypes.Inventory) as EntityInventoryComponent;
    if (inventory && inventory.container) {
      inventory.container.addItem(hurtDiamondSword);
    }
  }
}

#getComponents()

getComponents(): ItemComponent[]

Beta

#Returns

ItemComponent[]

#Remarks

返回该物品堆上存在的所有脚本组件。

Returns all scripting components that are present on this item stack.

#getDynamicProperty()

getDynamicProperty(identifier): string | number | boolean | Vector3 | undefined

Beta

#Parameters

#identifier

string

属性标识符。

The property identifier.

#Returns

string | number | boolean | Vector3 | undefined

返回该属性的值，若属性尚未设置则返回 undefined。

Returns the value for the property, or undefined if the property has not been set.

#Remarks

返回一个属性值。

Returns a property value.

#getDynamicPropertyIds()

getDynamicPropertyIds(): string[]

Beta

#Returns

string[]

一个字符串数组，包含该实体上已设置的动态属性。

A string array of the dynamic properties set on this entity.

#Remarks

返回已在该实体上使用的可用动态属性标识符集合。

Returns the available set of dynamic property identifiers that have been used on this entity.

#getDynamicPropertyTotalByteCount()

getDynamicPropertyTotalByteCount(): number

Beta

#Returns

number

#Remarks

返回当前为该实体存储的所有动态属性的总大小（以字节为 单位）。这包括键和值两者的大小。该值可用于诊断性能警告 迹象——例如，若某个实体关联了数兆字节的动态属性，它在 各种设备上加载时可能会很慢。

Returns the total size, in bytes, of all the dynamic properties that are currently stored for this entity. This includes the size of both the key and the value. This can be useful for diagnosing performance warning signs - if, for example, an entity has many megabytes of associated dynamic properties, it may be slow to load on various devices.

#getLore()

getLore(): string[]

Beta

#Returns

string[]

lore 行的数组。若该物品没有 lore，则返回空数组。

An array of lore lines. If the item does not have lore, returns an empty array.

#Remarks

返回物品堆的 lore 值——一个次要显示字符串。

Returns the lore value - a secondary display string - for an ItemStack.

#getRawLore()

getRawLore(): RawMessage[]

Beta

#Returns

RawMessage[]

lore 行的数组。若该物品没有 lore，则返回空数组。

An array of lore lines. If the item does not have lore, returns an empty array.

#Remarks

返回物品堆的 lore 值——一个次要显示字符串。字符串类型的 lore 行会被转换为 RawMessage 并置于 RawMessage.text 之下。

Returns the lore value - a secondary display string - for an ItemStack. String lore lines will be converted to a RawMessage and put under RawMessage.text.

#getTags()

getTags(): string[]

Beta

#Returns

string[]

#Remarks

返回与该物品堆关联的标签集合。

Returns a set of tags associated with this item stack.

#hasComponent()

hasComponent(componentId): boolean

Beta

#Parameters

#componentId

string

要获取的组件的标识符（例如 'minecraft:food'）。若未指定 命名空间前缀，则默认使用 'minecraft:'。

The identifier of the component (e.g., 'minecraft:food') to retrieve. If no namespace prefix is specified, 'minecraft:' is assumed.

#Returns

boolean

#Remarks

若指定组件存在于该物品堆上，则返回 true。

Returns true if the specified component is present on this item stack.

#hasTag()

hasTag(tag): boolean

Beta

#Parameters

#tag

string

要搜索的标签。

Tag to search for.

#Returns

boolean

若该物品堆关联了此标签则返回 true，否则返回 false。

True if the Item Stack has the tag associated with it, else false.

#Remarks

检查该物品堆是否关联了特定标签。

Checks whether this item stack has a particular tag associated with it.

#isStackableWith()

isStackableWith(itemStack): boolean

Beta

#Parameters

#itemStack

ItemStack

用于检查堆叠兼容性的物品堆。

ItemStack to check stacking compatibility with.

#Returns

boolean

若该物品堆可与传入的 itemStack 堆叠则返回 true。对于不可 堆叠的物品返回 false。

True if the Item Stack is stackable with the itemStack passed in. False for non-stackable items.

#Remarks

返回该物品堆是否可与给定的 itemStack 堆叠。这通过比较 物品类型以及与物品堆关联的任何自定义数据和属性来确定。 每个物品堆的数量不在考虑范围内，但对于不可堆叠的物品， 此方法始终返回 false。

Returns whether this item stack can be stacked with the given itemStack. This is determined by comparing the item type and any custom data and properties associated with the item stacks. The amount of each item stack is not taken into consideration, but for non-stackable items this will always return false.

#matches()

matches(itemName, states?): boolean

Beta

#Parameters

#itemName

string

物品的标识符。

Identifier of the item.

#states?

Record<string, string | number | boolean>

仅适用于方块。可选的一组状态用于比较。若未指定 states， 则匹配将在更宽泛的类型集合上进行检查。

Applicable only for blocks. An optional set of states to compare against. If states is not specified, matches checks against the set of types more broadly.

#Returns

boolean

返回一个布尔值，表示指定物品是否匹配。

Returns a boolean whether the specified item matches.

#Remarks

版本安全的物品匹配检查方式。

Version safe way of checking if an item matches.

#setCanDestroy()

setCanDestroy(blockIdentifiers?): void

World Mutation Beta

#Parameters

#blockIdentifiers?

string[]

该物品可破坏的方块类型的字符串列表。

String list of block types that the item can destroy.

#Returns

void

#Remarks

该物品在冒险模式下可破坏的方块类型列表。方块名称会显示 在物品的提示信息中。将值设置为 undefined 会清空该列表。

The list of block types this item can break in Adventure mode. The block names are displayed in the item's tooltip. Setting the value to undefined will clear the list.

#Throws

Throws if any of the provided block identifiers are invalid.

#Example

giveDestroyRestrictedPickaxe.ts

import { world, ItemStack, EntityInventoryComponent, DimensionLocation } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function giveDestroyRestrictedPickaxe(targetLocation: DimensionLocation) {
  for (const player of world.getAllPlayers()) {
    const specialPickaxe = new ItemStack(MinecraftItemTypes.DiamondPickaxe);
    specialPickaxe.setCanDestroy([MinecraftItemTypes.Cobblestone, MinecraftItemTypes.Obsidian]);

    const inventory = player.getComponent('inventory') as EntityInventoryComponent;
    if (inventory === undefined || inventory.container === undefined) {
      return;
    }

    inventory.container.addItem(specialPickaxe);
  }
}

#setCanPlaceOn()

setCanPlaceOn(blockIdentifiers?): void

World Mutation Beta

#Parameters

#blockIdentifiers?

string[]

该物品可放置于其上的方块类型的字符串列表。

String list of block types that the item can be placed on.

#Returns

void

#Remarks

该物品在冒险模式下可放置于其上的方块类型列表。这仅适用于 方块物品。方块名称会显示在物品的提示信息中。将值设置为 undefined 会清空该列表。

The list of block types this item can be placed on in Adventure mode. This is only applicable to block items. The block names are displayed in the item's tooltip. Setting the value to undefined will clear the list.

#Throws

Throws if any of the provided block identifiers are invalid.

#Example

givePlaceRestrictedGoldBlock.ts

import { world, ItemStack, EntityInventoryComponent, EntityComponentTypes, DimensionLocation } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function givePlaceRestrictedGoldBlock(targetLocation: DimensionLocation) {
  for (const player of world.getAllPlayers()) {
    const specialGoldBlock = new ItemStack(MinecraftItemTypes.GoldBlock);
    specialGoldBlock.setCanPlaceOn([MinecraftItemTypes.GrassBlock, MinecraftItemTypes.Dirt]);

    const inventory = player.getComponent(EntityComponentTypes.Inventory) as EntityInventoryComponent;
    if (inventory === undefined || inventory.container === undefined) {
      return;
    }

    inventory.container.addItem(specialGoldBlock);
  }
}

#setDynamicProperties()

setDynamicProperties(values): void

Beta

#Parameters

#values

Record<string, boolean | number | string | Vector3 | undefined>

要设置的动态属性的键值对 Record。若数据值为 null，则会 移除该属性。

A Record of key value pairs of the dynamic properties to set. If the data value is null, it will remove that property instead.

#Returns

void

#Remarks

一次性设置多个动态属性及其对应的值。

Sets multiple dynamic properties with specific values.

#Throws

This function can throw errors.

ArgumentOutOfBoundsError

UnsupportedFunctionalityError

#setDynamicProperty()

setDynamicProperty(identifier, value?): void

Beta

#Parameters

#identifier

string

属性标识符。

The property identifier.

#value?

string | number | boolean | Vector3

要设置的属性的数据值。若值为 null，则会移除该属性。

Data value of the property to set. If the value is null, it will remove the property instead.

#Returns

void

#Remarks

将指定属性设置为某个值。注意：此函数仅对不可堆叠的物品 有效。

Sets a specified property to a value. Note: This function only works with non-stackable items.

#Throws

Throws if the item stack is stackable.

ArgumentOutOfBoundsError

UnsupportedFunctionalityError

#setLore()

setLore(loreList?): void

World Mutation Beta

#Parameters

#loreList?

(string | RawMessage)[]

lore 行的列表。列表中每个元素代表新的一行。lore 行的最大 数量为 20。lore 行的最大长度为 50 个字符。

List of lore lines. Each element in the list represents a new line. The maximum lore line count is 20. The maximum lore line length is 50 characters.

#Returns

void

#Remarks

设置物品堆的 lore 值——一个次要显示字符串。若设置为空 字符串或 undefined，则会清空 lore 列表。

Sets the lore value - a secondary display string - for an ItemStack. The lore list is cleared if set to an empty string or undefined.

#Throws

This function can throw errors.

ArgumentOutOfBoundsError

Error

#Example

diamondAwesomeSword.ts

import { EntityComponentTypes, ItemStack, Player } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function giveAwesomeSword(player: Player) {
  const diamondAwesomeSword = new ItemStack(MinecraftItemTypes.DiamondSword, 1);
  diamondAwesomeSword.setLore(['§c§lDiamond Sword of Awesome§r', '+10 coolness', '§p+4 shiny§r']);

  // hover over/select the item in your inventory to see the lore.
  const inventory = player.getComponent(EntityComponentTypes.Inventory);
  if (inventory === undefined || inventory.container === undefined) {
    return;
  }

  inventory.container.setItem(0, diamondAwesomeSword);
}

#同领域相关

• InvalidItemStackError
• ItemLockMode
• ItemType
• BlockPaletteItemType
• CollectionTreeEntryItemType
• CoreActionBarItemType