JSON UI¶
JSON UI是Minecraft基岩版中用于定义游戏用户界面的系统。该系统使用JSON格式的数据文件声明界面的布局、控件和交互逻辑，允许资源包覆盖或扩展游戏内界面。
JSON UI没有独立的格式版本控制，更新时应始终以目标版本原版ui/文件与内容日志为准。
概述¶
基岩版的几乎所有游戏界面——包括主菜单、背包界面、合成界面、设置界面、聊天框、暂停菜单等——都通过JSON UI系统定义。JSON UI文件存放在资源包的ui/目录中，每个文件定义一个或多个界面的布局和行为。
JSON UI系统使用声明式方式描述界面：开发者通过JSON定义控件的类型、位置、大小、绑定数据和交互行为，游戏引擎在运行时根据这些定义渲染界面。JSON UI属于资源包客户端资源，不是脚本API表单系统，也不是Ore UI或中国版ModSDK UI接口。
文件组织¶
国际版资源包的JSON UI主要由以下文件组成：
| 文件 | 作用 |
|---|---|
ui/_ui_defs.json | 列出需要由游戏加载的UI屏幕文件路径。路径相对于资源包根目录，通常以ui/开头。 |
ui/_global_variables.json | 定义跨屏幕复用的全局变量。变量名以$开头，常用于颜色、尺寸等可复用值。 |
ui/*.json | 定义具体屏幕、控件层级、变量、绑定和交互映射。 |
屏幕文件通常具有namespace字段。除namespace外，根对象中的其他键通常代表控件定义。控件可以使用名称@命名空间.控件名语法继承其他控件，也可以使用以$开头的字段或变量项覆盖可复用值。
控件¶
控件（Control）是JSON UI中的基本元素，每个控件代表界面上的一个可视化或逻辑组件。控件以JSON对象的形式声明，通过type字段指定类型。常见的控件类型包括：
| 类型 | 描述 |
|---|---|
panel | 面板，用于组织和容纳子控件。 |
label | 文本标签。 |
image | 图片。 |
button | 按钮。 |
toggle | 开关。 |
slider | 滑块。 |
edit_box | 文本输入框。 |
grid | 网格布局。 |
stack_panel | 栈面板，沿一个方向依次排列子控件。 |
scroll_view | 滚动视图。 |
input_panel | 输入面板，用于处理输入事件。 |
screen | 屏幕，界面的顶层容器。 |
布局系统¶
JSON UI的布局系统基于锚点（Anchor）和偏移（Offset）来定位控件。每个控件可以指定其在父控件中的锚点位置，并通过偏移量进行微调。
控件的大小可以通过固定像素值、百分比或自适应内容等方式指定。九切片（NineSlice）技术被广泛用于按钮和面板等控件的背景纹理，使纹理在拉伸时保持边角的正确比例。
绑定¶
绑定（Binding）是JSON UI中将界面控件与游戏数据连接的机制。通过绑定，控件可以动态显示游戏运行时的数据，也可以将用户的输入操作传递给游戏逻辑。
绑定通过bindings数组声明，每个绑定指定数据源名称、目标属性和绑定条件等信息。部分绑定数据源和行为由游戏硬编码，无法只通过资源包任意扩展。
屏幕¶
屏幕（Screen）是JSON UI中的顶层界面容器。游戏中的每个界面对应一个屏幕定义，屏幕内包含该界面的控件层次结构。屏幕通过screen类型的控件定义，并由游戏引擎根据游戏状态自动显示和隐藏。
变量¶
JSON UI中的变量（Variable）以$开头，用于在控件定义内传递可复用值。变量可以在控件或其父控件的定义中声明，并在控件的任意字段中以$变量名的形式引用；子控件可以通过继承（@语法）覆盖父模板所定义的变量值，从而实现参数化复用。
变量名区分大小写，值可以是字符串、数值、布尔值或其他JSON值。全局变量定义在_global_variables.json中，供所有屏幕共享；局部变量则仅在其所在控件及子控件中有效。
运算符¶
JSON UI的Molang表达式支持以下运算符，可在绑定的source_property_name及任意Molang表达式字段中使用：
| 运算符 | 类型 | 描述 |
|---|---|---|
+ | 二元 | 数值加法；或字符串拼接（当任一操作数为字符串时）。 |
- | 二元 | 数值减法；或从字符串中移除子串（当操作数为字符串时）。 |
* | 二元 | 数值乘法；或字符串转数值（与1相乘时）。 |
/ | 二元 | 数值除法。 |
% | 二元 | 取模。 |
= | 二元 | 等于比较，返回布尔值。 |
< | 二元 | 小于比较，返回布尔值。 |
> | 二元 | 大于比较，返回布尔值。 |
<= | 二元 | 小于等于比较，返回布尔值。 |
>= | 二元 | 大于等于比较，返回布尔值。 |
not | 一元 | 逻辑非。 |
and | 二元 | 逻辑与。 |
or | 二元 | 逻辑或。 |
括号可以改变运算优先级，表达式需完整包裹在圆括号中，例如(A + B)。
动画¶
动画（Animation）允许控件的属性值随时间变化。动画通过独立的动画对象定义，控件以@语法引用。anim_type字段指定动画类型，常见类型包括：
anim_type值 | 描述 |
|---|---|
alpha | 动画化不透明度。 |
color | 动画化颜色。 |
flip_book | 翻书动画，按帧切换纹理UV。 |
aseprite_flip_book | 读取Aseprite导出的JSON帧序列数据进行翻书动画。 |
offset | 动画化位置偏移。 |
size | 动画化尺寸。 |
uv | 动画化UV坐标。 |
wait | 延迟占位，不改变属性值。 |
修改操作¶
资源包可通过modifications数组对原版控件的controls或bindings子项执行结构修改，而无需完整覆写原版文件。modifications中每个对象通过operation字段指定操作类型：
operation值 | 目标 | 描述 |
|---|---|---|
insert_back | controls | 在列表末尾插入新控件。 |
insert_front | controls | 在列表开头插入新控件。 |
insert_after | controls/bindings | 在指定控件或绑定之后插入。 |
insert_before | controls/bindings | 在指定控件或绑定之前插入。 |
move_back | controls | 将指定控件移至末尾。 |
move_front | controls | 将指定控件移至开头。 |
move_after | controls | 将指定控件移至另一控件之后。 |
move_before | controls | 将指定控件移至另一控件之前。 |
swap | controls | 交换两个控件的位置。 |
replace | controls/bindings | 替换指定控件或绑定。 |
remove | controls/bindings | 删除指定控件或绑定。 |
insert_after和insert_before对控件使用control_name字段指定参照控件，对绑定则使用where: { binding_name: "..." }指定参照绑定。
按钮映射¶
按钮映射（Button Mapping）是JSON UI中将输入事件（如鼠标点击、键盘按键、手柄按键）与界面内部动作（如button.menu_select、toggle.switch等）关联的机制。按钮映射通过控件的button_mappings数组声明，每个映射项指定触发来源（from_button_id）、目标动作（to_button_id）以及触发条件。
条件渲染¶
JSON UI通过绑定将#visible或#enabled等属性与布尔表达式关联，从而实现控件的条件渲染。当绑定的表达式求值为false时，控件被隐藏（visible: false）或禁用（enabled: false）。使用"ignored": true可以完全从控件树中排除某控件及其子树，避免任何求值开销。
通过资源包可以覆盖原版的JSON UI文件来修改游戏界面。但JSON UI系统存在以下限制：
- 不支持创建全新的独立界面类型，只能修改或扩展已有界面。
- 部分控件类型、绑定数据源、渲染器和输入动作是硬编码的，不可任意自定义。
- 修改JSON UI需要对原版UI文件的结构有充分了解，因为控件之间存在大量引用关系。
- 官方公开参考当前没有完整列出所有枚举取值和原版硬编码绑定；维护资源包时仍需结合目标版本原版资源包与实际客户端测试。
脚本API与JSON UI¶
在国际版中，脚本API提供了有限的界面交互能力，例如通过@minecraft/server-ui模块显示表单对话框。但这些功能与JSON UI系统相互独立，脚本API目前无法直接操控JSON UI控件。
中国版增强¶
中国版的JSON UI在国际版基础上进行了扩展，提供了更多的控件类型和绑定接口，以支持中国版独有的界面功能。中国版模组SDK还允许通过ScreenNode及相关接口直接创建和管理自定义界面实例；这属于中国版脚本运行时能力，而不是国际版资源包JSON UI本身的通用能力。
旧版中国版MC Studio还提供过界面编辑器。该工具使用.mcgui作为工程文件，并在保存时导出同名JSON界面文件；画布、面板、图片、按钮、文本、滚动列表和网格等控件可通过可视化方式编辑。旧版资料使用%+Px描述位移和尺寸，并记录了手机端320×210、PC端376×250的适配基准。这些内容属于旧版中国版工具链历史资料，不应视为国际版JSON UI通用规则；维护旧项目时可参见旧版中国版MC Studio工具链，若需要走一遍旧版中国版自定义UI工作流，可再阅读制作中国版模组SDK界面。