跳转至

UI Xml

自 2.1.6

LDLib2 允许你使用 XML 定义 UI，包括 样式 和 组件树。 这提供了一种类似 HTML（H5）UI 开发 的工作流，使 UI 结构清晰且声明式。

一个最简的 UI XML 模板 如下所示：

<?xml version="1.0" encoding="UTF-8" ?>
<ldlib2-ui xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/Low-Drag-MC/LDLib2/refs/heads/1.21/ldlib2-ui.xsd">
    <stylesheet location="ldlib2:lss/mc.lss"/>
    <style>
        .half-button {
            width: 50%
        }
    </style>
    <root class="panel_bg" style="width: 150; height: 300">
        <button text="click me!"/>
        <button class="half-button" text="half"/>
    </root>
</ldlib2-ui>

属性 xsi:noNamespaceSchemaLocation 指向 LDLib2 提供的 XSD 模式。 在 VS Code、IntelliJ IDEA 或其他 IDE 中编辑 XML 时，该模式可提供：

  • 语法高亮
  • 验证与错误检查
  • 自动补全与提示

加载 UI Xml 并进行设置

你可以通过以下方式加载并使用 UI XML 文件：

编辑器外观 
var xml = XmlUtils.loadXml(ResourceLocation.parse("ldlib2:tuto.xml"));
if (xml != null) {
    var ui = UI.of(xml);

    // find elemetns and do data bindings or logic setup here
    var buttons = ui.select(".button_container > button").toList(); // by selector
    var container = ui.selectRegex("container").findFirst().orElseThrow(); // by id regex
}

let xml = XmlUtils.loadXml(ResourceLocation.parse("ldlib2:tuto.xml"));
if (xml != null) {
    let ui = UI.of(xml);

    // find elemetns and do data bindings or logic setup here
    let buttons = ui.select(".button_container > button").toList(); // by selector
    let container = ui.selectRegex("container").findFirst().orElseThrow(); // by id regex
}

Info

XmlUtils 还提供了其他加载 XML 文档的方式，例如从字符串或输入流加载。 请选择最适合你使用场景的方法。

XML 语法概览

LDLib2 UI XML 使用声明式语法来描述 UI 结构 及其 样式，类似于 HTML + CSS。

在顶层，<ldlib2-ui> 根节点定义了一个完整的 UI 文档。 在其内部，你可以描述 样式、外部样式表 和 组件树。

样式表

Note

在阅读本章之前，请先阅读 LSS 页面。

你可以使用 <stylesheet> 标签引用外部 LSS 文件：

<stylesheet location="ldlib2:lss/mc.lss"/>

这允许你复用共享样式，或让资源包全局覆盖 UI 外观。

当 <stylesheet> 直接置于 <ldlib2-ui> 下时，它是作用于整个 UI 的全局样式表。

嵌入式样式

可以使用 LSS（LDLib Style Sheet） 语法在 <style> 块中定义内联样式：

<style>
    label:host {
        vertical-align: center;
        horizontal-align: center;
    }
    .flex-1 {
        flex: 1;
    }
    .bg {
        background: sprite(ldlib2:textures/gui/icon.png)
    }
</style>

当 <style> 直接置于 <ldlib2-ui> 下时，它同样是作用于整个 UI 的全局样式。

元素上的本地样式表

你也可以将 <style> 或 <stylesheet> 放在任意元素节点内部（例如 root、element、button、tab、selector）。

此时，该样式表被视为本地样式表，仅影响：

  • 当前元素
  • 它的后代元素

它不会影响父元素或兄弟分支。

<root>
    <element id="left-panel">
        <style>
            button {
                width: 70;
            }
        </style>
        <button text="inside panel"/>
    </element>

    <button text="outside panel"/>
</root>

在上面的示例中，width 规则只作用于 left-panel 内部的 button，而不作用于外部的同级 button。

Note

ldlib2-ui.xsd 已包含元素级别的 <style> / <stylesheet> 节点定义，因此 IDE 的 Schema 验证与自动补全同样支持本地样式表。

内联样式属性

对于快速调整，样式也可以直接在元素上设置：

<button style="height: 30; align-items: center;"/>

内联样式的优先级高于样式表规则。

组件树

UI 布局在 <root> 下被描述为元素树。 每个 XML 节点对应一个 UI 组件，嵌套关系定义了父子关系。

属性用于配置组件属性，子节点用于定义结构。

简而言之：

  • <stylesheet> → 加载外部样式
  • <style> → 定义嵌入式样式
  • 元素级别的 <stylesheet> / <style> → 仅作用于该元素子树的本地样式表
  • style 属性 → 内联样式
  • XML 层级结构 → UI 组件树

这使得 UI 定义清晰、易读且易于维护。