ModularUI

自 2.1.0

本页介绍 LDLib2 UI 系统的核心概念。 在运行时，LDLib2 使用一个名为 ModularUI 的类来管理整个 UI 树。 ModularUI 负责：

• 管理 UI 生命周期
• 处理输入事件
• 应用样式和样式表
• 协调渲染
• 在客户端与服务器之间同步数据（与 Menu 配合使用时）

简而言之，ModularUI 是一个 UI 实例的中央控制器。

---

ModularUI 的工作原理

下图展示了 ModularUI 如何将 Minecraft 系统与 UI 树连接起来：

---

ModularUI API

有两种方法可以创建 ModularUI：

• #!java ModularUI.of(ui)
• #!java ModularUI.of(ui, player)

要创建一个简单的仅客户端 UI，第一种方法就足够了。

第二种方法需要一个 Player 作为输入，如果你的 UI 是基于菜单的 UI，并且需要在客户端与服务器之间同步数据，那么这是必需的。

通用 API

方法	描述
shouldCloseOnEsc()	按下 ESC 时是否关闭 UI。
shouldCloseOnKeyInventory()	按下背包键（默认：E）时是否关闭 UI。
getTickCounter()	返回此 ModularUI 实例已激活的刻数。
getWidget()	返回供 Minecraft Screen 使用的控件实例。
getAllElements()	返回 UI 树中所有 UI 元素的不可修改列表。

---

元素查询 API（按 ID）

方法	描述
getElementById(String id)	查找并返回具有给定 ID 的第一个 UI 元素，如果未找到则返回 null。
getElementsById(String id)	返回具有给定 ID 的所有 UI 元素。
hasElementWithId(String id)	检查是否存在至少一个具有给定 ID 的元素。
getElementCountById(String id)	返回具有给定 ID 的元素数量。
getAllElementsById()	返回从 ID 到 UI 元素的内部映射的副本。

---

元素查询 API（正则与模式）

方法	描述
getElementByIdRegex(String pattern)	查找 ID 与给定正则表达式匹配的第一个元素。
getElementsByIdRegex(String pattern)	查找 ID 与给定正则表达式匹配的所有元素。
getElementByIdPattern(Pattern pattern)	与上相同，但使用预编译的 Pattern 以获得更好的性能。
getElementsByIdPattern(Pattern pattern)	返回与预编译正则表达式模式匹配的所有元素。

---

元素查询 API（部分匹配）

方法	描述
getElementsByIdContains(String substring)	查找 ID 包含给定子字符串的所有元素。
getElementsByIdStartsWith(String prefix)	查找 ID 以给定前缀开头的所有元素。
getElementsByIdEndsWith(String suffix)	查找 ID 以给定后缀结尾的所有元素。

---

元素查询 API（按类型）

方法	描述
getElementsByType(Class<T> type)	返回给定类型的所有 UI 元素。
getAllElementsByType()	返回从元素类型到 UI 元素的内部映射的副本。

INFO

所有查询方法在适用时返回内部集合的副本。返回的列表可以安全修改，不会影响内部 UI 树。

---

调试你的 UI

在开发过程中，UI 树的行为可能并不总是如预期， 而且很难理解哪里出了问题。

LDLib2 提供了一个类似 Chrome 调试工具的 Debug Panel。你可以通过它检查实时 UI 层级、查看计算后的样式和布局信息，并在 UI 运行时选择元素。

INFO

自 mc26.1

按 F12 可以打开或关闭 Debug Panel。在 1.21 上，快捷键是 F3。

打开 Debug Panel 后，按 F1 可以切换 Look Up 模式。在 Look Up 模式下，将鼠标悬停在目标 UI 的元素上并点击，即可跳转到 Debug Panel 的层级树和检查器中的对应 UIElement。按 F4 可以切换是否绘制 UI 的布局形状。

在独立窗口中调试

自 2.2.38

Debug Panel 默认叠加在游戏画面之上打开。点击它标题栏上的窗口切换按钮，可以把它移到独立的桌面窗口中，这样它就不会再遮住你正在检查的 UI。在独立窗口中，它可以比游戏窗口更大、可以移到另一台显示器，也可以通过置顶开关保持在其他窗口之上。它的大小、位置和置顶状态都会被记住。

鼠标停在被检查的 UI 上时，F1 和 F4 依然有效。

调试器打开时，也可以在代码中切换：

modularUI.enableDebugger(true);
modularUI.setDebuggerWindowed(true);    // false 则移回游戏画面之上
modularUI.isDebuggerWindowed();

无法打开第二个窗口时（例如原生全屏），setDebuggerWindowed(true) 不会做任何事。见 ModularUIWindow。

选择要检查的 UI

自 2.2.38

屏幕上同时有多个 UI 时，使用调试器的目标选择器来选择要检查哪一个：游戏窗口中的 UI、独立窗口中的 UI（例如浮动的编辑器 View），或者嵌入在两者之中的 UI。元素轮廓会绘制在被检查 UI 所在的窗口中。

自 2.2.42 起，绘制在另一个 UI 元素内部、并通过 ModularUI#embedIn(host, name) 注册的 UI，会以 Outer / Name 的形式出现在选择器中。焦点在 host 内部时按调试键，会在嵌入的 UI 上打开调试器。UI 编辑器的 模拟 就使用了这一机制。