我的世界基岩版 UI 文档
  1. < 首页
  2. 开关

开关

Toggle（开关）是一种常用的UI组件，用于在两种状态（不包含悬停、锁定）之间进行切换。

提示
本文章需要一定的 JSON UI 知识，建议了解绑定属性。

开关属性

属性属性名值默认值描述
toggle_name开关名称字符串用于区分不同的开关组。
radio_toggle_group开关组布尔值false是否启用开关组。
toggle_group_forced_index开关组索引数字-1该控件在开关组中的索引。
toggle_group_default_selected开关组默认索引数字0开关组默认的索引。
toggle_default_state开关默认状态布尔值false开关默认状态。
toggle_on_button开关开启事件字符串：事件名开关开启的按钮映射事件。
toggle_off_button开关关闭事件字符串：事件名开关关闭的按钮映射事件。
enable_directional_toggling启用方向切换布尔值false开关是否启用方向切换。
toggle_grid_collection_name开关网格集合名称字符串开关组的网格集合名称。
checked_control开启时的子控件名称字符串开关在开启后（没有悬停），显示的子控件的名称。
unchecked_control关闭时的子控件名称字符串开关在关闭后（没有悬停），显示的子控件的名称。
checked_hover_control开启并悬停时的子控件名称字符串开关在开启并悬停后，显示的子控件的名称。
unchecked_hover_control关闭并悬停时的子控件名称字符串开关在关闭并悬停后，显示的子控件的名称。
checked_locked_control锁定状态，开启时的子控件名称字符串锁定状态下，开关在开启后（没有悬停），显示的子控件的名称。
unchecked_locked_control锁定状态，关闭时的子控件名称字符串锁定状态下，开关在关闭后（没有悬停），显示的子控件的名称。
checked_locked_hover_control锁定状态，开启并悬停时的子控件名称字符串锁定状态下，开关在开启并悬停后，显示的子控件的名称。
unchecked_locked_hover_control锁定状态，关闭并悬停时的子控件名称字符串锁定状态下，开关在关闭并悬停后，显示的子控件的名称。

创建开关

要创建一个开关，我们可以选择使用原版预设的开关。（以下将“原版预设的开关”简称为“预设开关”）

RP/ui/start_screen.json
1
2
3
4
5
6
"test_toggle@common_toggles.light_text_toggle": {
  "size": [100,30],
  "$toggle_state_binding_name": "#toggle_state",
  "$toggle_view_binding_name": "toggle_name_1",
  "$button_text": "toggle"
}

在示例中，使用$toggle_view_binding_name让绑定读取当前开关的状态。

提示
代码中的 "$toggle_state_binding_name": "#toggle_state" 用于防止代码报错，这是由于该变量在预设开关中没有声明。

现在，为某个控件添加绑定，让开关的状态转化为控件可见的状态。这样可以让控件在开关开启状态下显示该控件。

RP/ui/start_screen.json
1
2
3
4
5
6
7
8
9
10
11
12
"test": {
  "type": "label",
  "text": "hello world",
  "bindings": [
    {
      "binding_type": "view",
      "source_control_name": "toggle_name_1",
      "source_property_name": "#toggle_state",
      "target_property_name": "#visible"
    }
  ]
}

代码块中的source_control_name等于上方开关的$toggle_view_binding_name，这样才能把控件的可见性绑定为开关的状态。

提示
$toggle_view_binding_name不能与其他子控件名重复，否则绑定冲突，需要让变量值是唯一的。

更改开关外观

当你想要修改一个预设开关的外观时，你可以尝试使用下方的变量修改预设开关不同状态下的外观。

当你的开关没有禁用的需求，你可以不修改锁定状态的样式。

这些变量的值为控件，格式为namespace.control_name，namespace 是当前样式控件所在文件的命名空间（此处请不要忽略命名空间），control_name 是当前样式控件的控件名。我们只需要把不同样式的控件分别引用到这些变量中即可：

RP/ui/start_screen.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
"test_toggle@common_toggles.light_text_toggle":{
  "size": [30,20],
  "$toggle_state_binding_name": "#toggle_state",
  "$toggle_view_binding_name": "toggle_name_1",
  "$unchecked_control": "start.toggle_uncheck",
  "$checked_control": "start.toggle_check",
  "$unchecked_hover_control": "start.toggle_uncheck_hover",
  "$checked_hover_control": "start.toggle_check_hover"
},
"toggle_uncheck@toggle_style":{"$toggle_image":"toggle_off"},
"toggle_check@toggle_style":{"$toggle_image":"toggle_on"},
"toggle_uncheck_hover@toggle_style":{"$toggle_image":"toggle_off_hover"},
"toggle_check_hover@toggle_style":{"$toggle_image":"toggle_on_hover"},
"toggle_style":{"type":"image","texture":"('textures/ui/' + $toggle_image)"}

开关组

开关组允许用户在不同的选项之间进行切换，不同于普通开关，这些选项都是互斥的。

在预设的开关中，可以使用$radio_toggle_group变量定义开关组。

RP/ui/start_screen.json
1
2
3
4
5
6
7
8
"toggle_group@common_toggles.light_text_toggle": {
  "size": [100,30],
  "$toggle_state_binding_name": "#toggle_state",
  "$toggle_view_binding_name": "toggle_name_1",
  "$button_text": "toggle",
  "$radio_toggle_group": true,
  "$toggle_name": "toggle_group_1"
}

示例中，$toggle_name可以定义预设开关所在的开关组。

在不同开关组之间，选项是互不影响的。因此，当前开关组的选项不会因为另外一个开关组而影响。

下方是同一个开关组，不同选项的示例：

RP/ui/start_screen.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
"group_common@common_toggles.light_text_toggle": {
  "size": [100,30],
  "$toggle_state_binding_name": "#toggle_state",
  "$radio_toggle_group": true,
  "$toggle_group_default_selected": 0,
  "$toggle_name": "toggle_group_1"
},
"group_1@group_common":{
  "$toggle_view_binding_name": "toggle_name_1",
  "$button_text": "toggle_1",
  "$toggle_group_forced_index": 0
},
"group_2@group_common":{
  "$toggle_view_binding_name": "toggle_name_2",
  "$button_text": "toggle_2",
  "$toggle_group_forced_index": 1
}

在开关组每个选项中，$toggle_group_forced_index用于定义当前选项的索引。在 group_common 控件中，$toggle_group_default_selected变量用于定义开关组默认选中哪个索引的选项。（这些变量仅适用于预设开关，自行创建的控件可以参考上方的属性）

下方是不同开关组的示例：

RP/ui/start_screen.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
"group_common@common_toggles.light_text_toggle": {
  "size": [100,30],
  "$toggle_state_binding_name": "#toggle_state",
  "$radio_toggle_group": true,
  "$button_text": "toggle",
  "$toggle_group_default_selected": 0,
  "$toggle_group_forced_index": 0
},
"group_1@group_common":{
  "$toggle_view_binding_name": "toggle_name_1",
  "$toggle_name": "toggle_group_1"
},
"group_2@group_common":{
  "$toggle_view_binding_name": "toggle_name_2",
  "$toggle_name": "toggle_group_2"
}

在这个示例中，可以得知不同的开关组之间是不会影响的。

深入探究

开关真的只能用作控制控件的可见状态吗？

除了控制可见性之外，我们还可以使用绑定把开关状态的布尔值传递给某个硬编码。开关的状态等于布尔值。开关开启时为 true，关闭时为 false。接下来以下方示例深入探究：

RP/ui/start_screen.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
"test_toggle@common_toggles.light_text_toggle": {
  "size": [100,30],
  "$toggle_state_binding_name": "#toggle_state",
  "$toggle_view_binding_name": "can_drag",
  "$button_text": "toggle"
},
"drag_panel@common.button": {
  "size": ["100%c","100%c"],
  "sound_volume": 0,
  "draggable": "both",
  "layer": 100,
  "prevent_touch_input": true,
  "controls": [{"text":{"type":"label","text":"hello world"}}],
  "bindings": [
    {
      "binding_type": "view",
      "source_control_name": "can_drag",
      "source_property_name": "#toggle_state",
      "target_property_name": "#enabled"
    }
  ]
}

在代码中，我们演示了开关间接控制拖动面板的拖动状态。

首先我们使用绑定把开关状态转化为enabled属性，再通过这个属性禁用拖动来实现效果。

问题是enabled属性是传播到子控件的，这可能导致子控件无法互动。解决办法也是有的，我们可以其他方法来控制拖动，不过，此文章不再过多展开赘述。

RP/ui/start_screen.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
"test_toggle@common_toggles.light_text_toggle": {
  "size": [100,30],
  "$toggle_state_binding_name": "#toggle_state",
  "$toggle_view_binding_name": "hidden",
  "$button_text": "toggle"
},
"test": {
  "type": "panel",
  "size": ["100%c","100%c"],
  "layer": 100,
  "alpha": 0,
  "controls": [{"text":{"type":"label","text":"hello world"}}],
  "bindings": [
    {
      "binding_type": "view",
      "source_control_name": "hidden",
      "source_property_name": "#toggle_state",
      "target_property_name": "#propagateAlpha"
    }
  ]
}

在代码中，我们另外演示了开关控制控件的不透明度传播，做到了视觉上的隐藏。

其他预设开关

在前面的示例中，通常是以 common_toggles 的开关作为示例。下方还有其他的预设开关，以供参考。
RP/ui/start_screen.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
"toggle_control@settings_common.option_toggle_control": {
  "size": [30,20],
  "$option_binding_name": "#toggle_state"
  // 此处可以使用 $unchecked_control 等变量定义开关的样式
},
"toggle@settings_common.option_toggle": {
  // 可以使用下方变量移除选项文字
  // "$show_option_label": false,
  "$option_label": "测试",
  "$control_name": "start.toggle_control",
  "anchor_from": "bottom_middle",
  "anchor_to": "bottom_middle"
},
"test": {
  "type": "label",
  "text": "hello world",
  "bindings": [
    {
      "binding_type": "view",
      "source_control_name": "start.toggle_control",
      "source_property_name": "#toggle_state",
      "target_property_name": "#visible"
    }
  ]
}

这是 settings_common 中的预设开关。要注意的是$control_name变量的格式为namespace.control_name，namespace 是 toggle_control 控件所在文件的命名空间（不能忽略命名空间），control_name 是 toggle_control 控件的控件名。

代码中的 $option_binding_name 等于上方所说到的 $toggle_state_binding_name 变量，作用一致，都是为了防止变量未声明报错。

提示
绑定中的 source_control_name 要与 $control_name 的值一致，这样才能绑定到开关。
RP/ui/start_screen.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
"toggle@common.toggle":{
  "size": [30,20],
  "$toggle_state_binding_name": "#toggle_state",
  // 此处可以使用 $unchecked_control 等变量定义开关的样式
  // 也可以使用 controls 属性定义开关的样式
  // 例如："controls": [{"unchecked":{}}]
},
"toggle_panel": { // 引用 toggle 的控件
  "controls": [
    {"toggle_name_1@start.toggle":{}}
  ]
},
"test": {
  "type": "label",
  "text": "hello world",
  "bindings": [
    {
      "binding_type": "view",
      "source_control_name": "toggle_name_1",
      "source_property_name": "#toggle_state",
      "target_property_name": "#visible"
    }
  ]
}

这是 ui_common 中的预设开关。代码中的{"toggle_name_1@start.toggle":{}}子控件名用于 view 绑定，用于绑定的子控件名必须是唯一的，不可重复，否则无法绑定到指定开关上。

另外，common.toggle 的预设开关默认是没有外观样式的，需要自行定义样式。

代码示例

开关
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
"test_toggle@common_toggles.light_text_toggle": {
  "size": [100,30],
  "$toggle_state_binding_name": "#toggle_state",
  "$toggle_view_binding_name": "toggle_name_1",
  "$button_text": "toggle"
},
"test": {
  "type": "label",
  "text": "hello world",
  "bindings": [
    {
      "binding_type": "view",
      "source_control_name": "toggle_name_1",
      "source_property_name": "#toggle_state",
      "target_property_name": "#visible"
    }
  ]
}
开关样式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
"test_toggle@common_toggles.light_text_toggle":{
  "size": [30,20],
  "$toggle_state_binding_name": "#toggle_state",
  "$toggle_view_binding_name": "toggle_name_1",
  "$unchecked_control": "start.toggle_uncheck",
  "$checked_control": "start.toggle_check",
  "$unchecked_hover_control": "start.toggle_uncheck_hover",
  "$checked_hover_control": "start.toggle_check_hover"
},
"toggle_uncheck@toggle_style":{"$toggle_image":"toggle_off"},
"toggle_check@toggle_style":{"$toggle_image":"toggle_on"},
"toggle_uncheck_hover@toggle_style":{"$toggle_image":"toggle_off_hover"},
"toggle_check_hover@toggle_style":{"$toggle_image":"toggle_on_hover"},
"toggle_style":{"type":"image","texture":"('textures/ui/' + $toggle_image)"}
版权声明- 除非另有说明，否则文档内容均采用CC BY-NC-SA 4.0许可协议
- 此网站与 Mojang Studios 以及微软无任何从属关系
- 转载需要作者同意，并且标明内容来自于本网站
 导航＆目录
阅读进度 - 0%
开关属性创建开关更改开关外观开关组深入探究其他预设开关代码示例
首页B站主页交流群隐私政策全屏