Differences

This shows you the differences between two versions of the page.

--- zh_cn:tutorial:blockentity_modify_data [2024/08/27 02:28] – solidblock
+++ zh_cn:tutorial:blockentity_modify_data [2025/04/01 12:48] (current) – [关于 NbtCompound 的注意事项] solidblock
@@ Line 3: / Line 3: @@
 在之前的教程，我们创建了[[blockentity|方块实体]]，但是这些方块实体太无聊了，没有任何数据。所以我们尝试给它添加一些数据，并定义了序列化和反序列化数据的方块。
+===== 关于 NbtCompound 的注意事项 =====
+自从 1.21.5 开始，''NbtCompound'' 的相关方法被更改了。各 getter 方法返回的都是 ''Optional'' 对象，除非再指定一个参数以表示该项不存在时的默认值。例如：
+<code java>
+// 没有指定默认值，将返回 Optional
+Optional<Integer> value = nbt.getInt("value"); // 注意不是 OptionalInt
+// 指定默认值，当对应字段不存在时返回这个默认值
+int value = nbt.getInt("value", 1000);
+</code>
+对于集合类型，如复合标签和列表，可以返回一个空的对象作为默认值，例如：
+<code java>
+// 没有指定默认值，将返回 Optional
+Optional<NbtCompound> config = nbt.getCompound("config");
+// 当对应字段不存在时，返回空复合标签
+NbtCompound config = nbt.getCompoundOrEmpty("config");
+</code>
+而在 1.21.5 之前，默认都会返回零值或者空白，如果需要指定默认值需要先自行用 ''contains'' 方法进行判断，例如：
+<code java>
+// 当对应字段不存在时返回 0。
+int value = nbt.getInt("value");
+// 当对应字段不存在时返回空复合标签。
+NbtCompound config = nbt.getCompound("config");
+</code>
+此外，自从 1.21.5 开始，整个 NBT 复合标签以及里面的字段，可以直接使用 [[codec]] 进行解码，例如：
+<code java>
+NbtCompound nbt = new NbtCompound();
+nbt.put("Id", Identifier.CODEC, Identifier.of("tutorial", "example_id"));
+Optional<Identifier> id = nbt.get("Id", Identifier.CODEC);
+</code>
+<code java>
+NbtCompound nbt = new NbtCompound();
+// 需要使用 RegistryOps，因为物品堆在编码解码时需要访问注册表内容
+nbt.copyFromCodec(ItemStack.MAP_CODEC, wrapperLookup.getOps(NbtOps.INSTANCE), new ItemStack(Items.WHEAT));
+Optional<ItemStack> stack = nbt.decode(ItemStack.MAP_CODEC, wrapperLookup.getOps(NbtOps.INSTANCE));
+</code>
+此外，从 1.21.5 开始，列表支持混合不同类型的元素，而在之前的版本中，混入不同类型的元素会导致报错。
+关于 NBT 变化的更多信息，请参见 [[https://fabricmc.net/2025/03/24/1215.html|Fabric for Minecraft 1.21.5]]。
 ===== 序列化数据 =====
@@ Line 25: / Line 72: @@
     // 序列化方块实体
     @Override
-    public void writeNbt(NbtCompound nbt, RegistryWrapper.WrapperLookup wrapper) {
+    public void writeNbt(NbtCompound nbt, RegistryWrapper.WrapperLookup registries) {
         // 将数字的当前值保存到 nbt
         nbt.putInt("number", number);
-        super.writeNbt(nbt, wrapper);
+        super.writeNbt(nbt, registries);
     }
 }
@@ Line 39: / Line 86: @@
     // 反序列化方块实体
     @Override
-    public void readNbt(NbtCompound nbt, RegistryWrapper.WrapperLookup wrapper) {
+    public void readNbt(NbtCompound nbt, RegistryWrapper.WrapperLookup registries) {
-        super.readNbt(nbt, wrapper);
+        super.readNbt(nbt, registries);
-        number = nbt.getInt("number");
+        number = nbt.getInt("number", 0);
     }
 </code>
-要获取方块实体的 NBT 数据，调用 ''createNbt(registryLookup)''，这会自动地处理一些数据，例如位置和组件。
+要获取方块实体的 NBT 数据，调用 ''createNbt(registries)''，这会自动地处理一些数据，例如位置和组件。
 旧有版本中必须调用 ''super.readNbt()'' 和 ''super.writeNbt()''，因为有必要处理坐标等数据。在旧版本中，如果 ''createNbt'' 不存在，尝试 ''writeNbt(new NbtCompound())''。
@@ Line 79: / Line 126: @@
     @Override
-    public void writeNbt(NbtCompound nbt) {
+    public void writeNbt(NbtCompound nbt, RegistryWrapper.WrapperLookup registries) {
         nbt.putInt("number", number);
-        super.writeNbt(nbt);
+        super.writeNbt(nbt, registries);
     }
     @Override
-    public void readNbt(NbtCompound nbt) {
+    public void readNbt(NbtCompound nbt, RegistryWrapper.WrapperLookup registries) {
-        super.readNbt(nbt);
+        super.readNbt(nbt, registries);
-        number = nbt.getInt("number");
+        // 对于 1.21.5 之前的版本，请使用 nbt.getInt("number");
+        number = nbt.getInt("number", 0);
     }
 }
@@ Line 127: / Line 175: @@
                 world.updateListeners(pos, state, state, 0);
 </code>
+===== 使用数据组件 =====
+自从 1.20.5 开始，还可以使用数据组件来存储数据，如果要将数据写入到物品堆，则有必要。你还是需要写 ''readNbt'' 和 ''writeNbt'' 方块以正确保存方块实体。
+在单独的 ''TutorialDataComponentTypes'' 类中创建数据组件。关于注册数据组件的更多信息，可见 [[https://docs.fabricmc.net/zh_cn/develop/items/custom-data-components|Fabric Docs 页面]]。
+<code java TutorialDataComponentTypes.java>
+public class TutorialDataComponentTypes {
+  public static final ComponentType<Integer> NUMBER = register("number", builder -> builder
+      .codec(Codec.INT)
+      .packetCodec(PacketCodecs.INTEGER));
+  public static <T> ComponentType<T> register(String path, UnaryOperator<ComponentType.Builder<T>> builderOperator) {
+    return Registry.register(Registries.DATA_COMPONENT_TYPE, Identifier.of("tutorial", path), builderOperator.apply(ComponentType.builder()).build());
+  }
+  public static void initialize() {
+  }
+}
+</code>
+记得有 ''ModInitializer'' 中引用这个方块：
+<code java ExampleMod.java>
+public class ExampleMod implements ModInitializer {
+  [...]
+  @Override
+  public static void onInitialize() {
+    [..]
+    TutorialDataComponentTypes.initialize();
+  }
+}
+</code>
+然后在方块实体中：
+<code java DemoBlockEntity.java>
+  @Override
+  protected void readComponents(ComponentsAccess components) {
+    super.readComponents(components);
+    this.number = components.getOrDefault(ExampleMod.NUMBER, 0);
+  }
+  @Override
+  protected void addComponents(ComponentMap.Builder componentMapBuilder) {
+    super.addComponents(componentMapBuilder);
+    componentMapBuilder.add(ExampleMod.NUMBER, number);
+  }
+  @Override
+  public void removeFromCopiedStackNbt(NbtCompound nbt) {
+    nbt.remove("number");
+  }
+</code>
+''removeFromCopiedStackNbt'' 的用途是，复制物品堆时，因为数据组件已经被复制，所以 NBT 就不再需要了。如果拾取物品（按下 ''Ctrl'' 的同时按下鼠标中键），组件会转移到物品堆。如果需要在不按下 ''Ctrl'' 的情况下就转移这些组件（就像原版旗帜的行为），请看 [[blockentity_sync_itemstack]]。