跳转至

ModularUI

自 2.1.0

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

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

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

ModularUI 的工作原理

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

flowchart LR
    Screen["Screen<br/>(Mouse / Keyboard Input)"]
    Menu["Menu<br/>(Server Data)"]

    %% internal structure
    subgraph ModularUI["ModularUI"]
        direction TB
        UITree["UI Tree"]
        Style["Style Engine<br/>(LSS / Stylesheets)"]
        Events["Event System<br/>(Dispatch / Bubble)"]
        Render["Renderer<br/>(Draw Commands)"]
        Bindings["Data Binding<br/>(C<-->S)"]

        UITree <--> Style
        UITree <--> Events
        UITree <--> Render
        UITree <--> Bindings
    end

    %% external connections
    Screen -->|Input Events| ModularUI
    Menu -->|Data Sync| ModularUI
    ModularUI -->|Render Output| Screen
    ModularUI -->|Data Sync / RPC Event| Menu

ModularUI API

有两种方法可以创建 ModularUI：

  • ModularUI.of(ui)
  • 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 元素的内部映射的副本。

Note

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

调试你的 UI

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

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

Note

Since mc26.1

按 F12 可以打开或关闭 Debug Panel。在较早的 1.21 构建中，调试快捷键是 F3。

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

Debug