Version: 2018.4
UXML 格式
从 C# 加载 UXML

编写 UXML 模板

UXML 模板是使用 XML 标记编写的文本文件,用于定义用户界面的逻辑结构。以下代码示例演示了如何定义一个提示用户做出选择的简单面板:

<?xml version="1.0" encoding="utf-8"?>
<engine:UXML
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:engine="UnityEngine.Experimental.UIElements"
    xsi:noNamespaceSchemaLocation="../UIElementsSchema/UIElements.xsd"
    xsi:schemaLocation="UnityEngine.Experimental.UIElements ../UIElementsSchema/UnityEngine.Experimental.UIElements.xsd">

    <engine:Label text="Select something to remove from your suitcase:"/>
    <engine:Box>
        <engine:Toggle name="boots" label="Boots" value="false" />
        <engine:Toggle name="helmet" label="Helmet" value="false" />
        <engine:Toggle name="cloak" label="Cloak of invisibility" value="false"/>
    </engine:Box>
    <engine:Box>
        <engine:Button name="cancel" text="Cancel" />
        <engine:Button name="ok" text="OK" />
    </engine:Box>
</engine:UXML>

文件的第一行是 XML 声明。声明是可选的,但如果包含的话,它必须在第一行,并且在它之前不能出现其他内容或空格。version 属性是必需的,但 encoding 是可选的。如果包含 version,它必须表示文件的字符编码。

下一行定义文档根 <UXML><UXML> 元素包含命名空间前缀定义的属性和架构定义文件的位置。可以按任意顺序指定这些属性。

在 UIElements 中,每个元素都在 UnityEngine.Experimental.UIElementsUnityEditor.Experimental.UIElements 命名空间中定义:

  • UnityEngine.Experimental.UIElements 命名空间包含被定义为 Unity Runtime 一部分的元素。
  • UnityEditor.Experimental.UIElements 命名空间包含 Unity Editor 中可用的元素。要完整指定一个元素,必须在其前面添加其命名空间。

例如,如果要在 UXML 模板中使用 Button 元素,则必须指定 <UnityEngine.Experimental.UIElements:Button />

要方便指定命名空间,可以定义命名空间前缀。例如,xmlns:engine="UnityEngine.Experimental.UIElements" 代码行定义了 engine 前缀,表示指定 UnityEngine.Experimental.UIElements

定义此缩略前缀后,<engine:Button /> 文本相当于 <UnityEngine.Experimental.UIElements:Button />

如果是自行定义元素,这些元素可能在其自身的命名空间中定义。如果要在 UXML 模板中使用这些元素,则必须在 <UXML> 标签中包含命名空间定义和架构文件位置以及 Unity 命名空间。

Asset/Create/UIElements View 菜单创建新的 UXML 模板资源时,Unity Editor 会自动执行以上操作。

UI 的定义在 <UXML> 根中。UI 定义是一系列嵌套的 XML 元素,每个元素代表一个 VisualElement

元素名称对应于要实例化的元素的 C# 类名。大多数元素都有属性,且属性的值映射到 C# 中相应的类属性。每个元素都继承其父类类型的属性,并可在父类类型的基础上添加自己的属性集。VisualElement 作为所有元素的基类,为所有元素提供以下属性:

  • name:元素的标识符。名称应具有唯一性。
  • picking-mode:设置为 Position(响应鼠标事件)或 Ignore (忽略鼠标事件)。
  • focus-index:在用 Tab 键移动时用于确定焦点顺序。请参阅分发事件下的焦点环。
  • class:用于表征元素的标识符的空格分隔列表。使用类为元素指定视觉样式。还可以使用类在 UQuery 中选择一组元素。
  • slot-nameslot:字段 (slot) 用作在实例化 UXML 组件时插入其他视觉元素的占位空间。请参阅下面的字段
  • tooltip:鼠标悬停在元素上方时显示为工具提示的字符串。

UXML 模板示例未定义用户界面的视觉要素。一般情况下,应该使用单独文件(包含以 USS 编写的样式规则)来定义用于绘制 UI 的样式信息,例如尺寸、字体和颜色(请参阅样式和 Unity 样式表)。

重用 UXML

可通过在 UXML 文件中定义组件的方式来创建组件, 并使用另一个 UXML 文件中的 <Template><Instance> 元素将组件导入。

在设计大型用户界面时,可以创建一些用于定义 UI 组成部分的模板 UXML 文件。

可能会在许多地方使用相同的 UI 定义。例如,假设有一个包含图像、名称和标签的纵向 UI 元素。可以创建一个 UXML 模板文件以便在其他 UXML 文件中重用此纵向 UI 元素。

例如,假设在 Assets/Portrait.uxml 文件中有一个 Portrait 组件:

<?xml version="1.0" encoding="utf-8"?>
<engine:UXML ...>
    <engine:VisualElement class="portrait">
        <engine:Image name="portaitImage" image="a.png"/>
        <engine:Label name="nameLabel" text="Name"/>
        <engine:Label name="levelLabel" text="42"/>
    </engine:VisualElement>
</engine:UXML>

可以将 Portrait 组件嵌入到其他 UXML 模板中,如下所示:

<?xml version="1.0" encoding="utf-8"?>
<engine:UXML ...>
    <engine:Template path="Assets/Portrait.uxml" name="Portrait">
    <engine:VisualElement name="players">
        <engine:Instance template="Portrait" name="player1"/>
        <engine:Instance template="Portrait" name="player2"/>
    </engine:VisualElement>
</engine:UXML>

字段

UXML 组件可以定义在实例化组件时插入元素的字段 (slot)。字段用作在实例化 UXML 组件时插入其他视觉元素的占位空间。

应使用 slot-name 属性来定义字段。例如,在 Window.uxml 中定义的窗口组件可以进一步定义两个名为 titlecontent 的字段:

<?xml version="1.0" encoding="utf-8"?>
<engine:UXML ...>
    <engine:VisualElement>
        <engine:VisualElement slot-name="title"/>
        <engine:ScrollView slot-name="content"/>
    </engine:VisualElement>
</engine:UXML>

然后,一个模板可以使用此窗口,具体方法是导入模板文件,实例化其内容并使用自己的元素填充字段,通过为视觉元素添加 slot 属性将视觉元素绑定到 slot-name

<?xml version="1.0" encoding="utf-8"?>
<engine:UXML ...>
    <engine:Template path="Assets/Window.uxml" name="window"/>
    <engine:Instance template="window">
        <engine:Label slot="title">
        <engine:TextBox slot="content"/>
    </engine:Instance>
</Window>

生成的视觉元素层级视图将如下所示:

VisualElement
    VisualElement slot-name="title"
        Label slot="title"
    ScrollView slot-name="content"
        TextBox slot="content"

在上面的视觉元素中,带有 slot="title" 属性的 Label 已添加作为带有 slot-name="title" 属性的 VisualElement 的子项。

在 C# 中也可以从组件的 VisualTreeAsset 填充字段:

var slots = new Dictionary<string, VisualElement>();
VisualElement t = visualTreeAsset.CloneTree(slots);
slots["title"].add(new Label());

在调用 CloneTree 之后,slots 字典会保存字段名称到字段 VisualElement 的映射。此字典可用于添加视觉元素作为字段的子项。


  • 2018–11–02 页面已修订并只进行了有限的编辑审查
UXML 格式
从 C&#35; 加载 UXML