完整版BedrockWiki镜像！

2025-03-20 11:52:46 +08:00
parent 1994c41f01
commit bf9aa4b056
214 changed files with 9042 additions and 8867 deletions
--- a/docs/wiki/blocks/block-states.md
+++ b/docs/wiki/blocks/block-states.md
@@ -0,0 +1,128 @@
+---
+title: 方块状态
+description: 方块状态允许你的方块拥有多种变体，每种变体通过使用置换具备独特的功能和外观。
+category: 基础
+nav_order: 4
+mentions:
+    - QuazChick
+---
+
+# 方块状态
+
+<!--@include: @/wiki/bedrock-wiki-mirror.md-->
+
+:::tip 格式要求 & 最低引擎版本 `1.20.30`
+使用方块状态时，请确保资源包清单中的 `min_engine_version` 设置为 `1.20.20` 或更高。
+:::
+
+方块状态允许你的方块拥有多种变体，每种变体通过使用[置换](/wiki/blocks/block-permutations)具备独特的功能和外观。
+
+## 定义状态
+
+有效状态值可以定义为布尔值、整数或字符串数组，也可以通过对象定义为整数范围。`values` 数组中的第一个元素将作为默认值使用。
+
+### 置换数量限制
+
+**每个状态最多可定义 16 个有效值。所有可能的状态值组合（[置换](/wiki/blocks/block-permutations)）总数不应超过 65,536。**
+
+计算方块置换总数时，需将所有状态的有效值数量相乘。例如下方示例的计算公式为 3 × 2 × 3 × 6，说明该方块具有 108 种可能的置换组合。
+
+_该功能需启用 `Holiday Creator Features` 实验性玩法（格式版本 1.19.70 及以上）。_
+
+::: code-group
+```json [BP/blocks/custom_block.json]
+{
+  "format_version": "1.20.30",
+  "minecraft:block": {
+    "description": {
+      "identifier": "wiki:custom_block",
+      "states": {
+        "wiki:string_state_example": ["red", "green", "blue"],
+        "wiki:boolean_state_example": [false, true],
+        "wiki:integer_state_example": [1, 2, 3],
+        "wiki:integer_range_state_example": {
+          "values": { "min": 0, "max": 5 } // 等同于 [0, 1, 2, 3, 4, 5]
+        }
+      }
+    },
+    "components": { ... },
+    "permutations": [ ... ]
+  }
+}
+```
+:::
+
+## 获取状态值
+
+以下列出在不同上下文中获取方块状态当前值的方法。
+
+### Molang 查询函数
+
+可通过 `block_state` 查询函数获取状态值。
+
+```c
+q.block_state('wiki:string_state_example') == 'blue'
+```
+
+### 命令参数
+
+在 `execute` 和 `testforblock` 等命令中使用[方块状态参数](/wiki/commands/block-states)来检查状态值。
+
+```c
+execute if block ~~~ wiki:custom_block["wiki:string_state_example"="blue", "wiki:integer_state_example"=4] run kill
+```
+
+### 脚本API
+
+:::warning 实验性功能
+使用 [`BlockPermutation.getState()`](https://learn.microsoft.com/minecraft/creator/scriptapi/minecraft/server/blockpermutation#getstate) 方法需启用 `Beta APIs` 实验性玩法。
+:::
+
+通过 [`BlockPermutation.getState()`](https://learn.microsoft.com/minecraft/creator/scriptapi/minecraft/server/blockpermutation#getstate) 方法可获取不同状态的当前值。
+
+```js
+customBlock.permutation.getState("wiki:integer_state_example") === 3
+```
+
+## 设置状态值
+
+### 命令参数
+
+在 `setblock` 和 `fill` 等命令中使用[方块状态参数](/wiki/commands/block-states)来修改默认状态值。
+
+```c
+setblock ~~~ wiki:custom_block["wiki:string_state_example"="blue", "wiki:integer_state_example"=4]
+```
+
+### 脚本API
+
+:::warning 实验性功能
+使用 [`BlockPermutation.withState()`](https://learn.microsoft.com/minecraft/creator/scriptapi/minecraft/server/blockpermutation#withstate) 方法需启用 `Beta APIs` 实验性玩法。
+:::
+
+[`BlockPermutation.withState()`](https://learn.microsoft.com/minecraft/creator/scriptapi/minecraft/server/blockpermutation#withstate) 方法会返回修改了指定状态值的新置换对象。可通过 [`Block.setPermutation()`](https://learn.microsoft.com/minecraft/creator/scriptapi/minecraft/server/block#setpermutation) 方法应用此置换，如下所示：
+
+```js
+customBlock.setPermutation(
+  customBlock.permutation.withState("wiki:boolean_state_example", false)
+);
+```
+
+### 事件响应
+
+:::warning 实验性功能
+方块事件需启用 `Holiday Creator Features` 实验性玩法。
+:::
+
+使用 [`set_block_state`](/wiki/blocks/block-events#set-block-state) 事件响应可以修改自定义方块状态的值。
+
+::: code-group
+```json [minecraft:block > events]
+"wiki:change_state": {
+  "set_block_state": {
+    "wiki:boolean_state_example": false,
+    "wiki:string_state_example": "'red'"
+  }
+}
+```
+:::