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.UIElements
或 UnityEditor.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-name
和 slot
:字段 (slot) 用作在实例化 UXML 组件时插入其他视觉元素的占位空间。请参阅下面的字段。tooltip
:鼠标悬停在元素上方时显示为工具提示的字符串。UXML 模板示例未定义用户界面的视觉要素。一般情况下,应该使用单独文件(包含以 USS 编写的样式规则)来定义用于绘制 UI 的样式信息,例如尺寸、字体和颜色(请参阅样式和 Unity 样式表)。
可通过在 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 中定义的窗口组件可以进一步定义两个名为 title
和 content
的字段:
<?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
的映射。此字典可用于添加视觉元素作为字段的子项。
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.