UIElements开发人员指南5 Writing UXML Templates（编写UXML模板）

本文介绍UXML模板的编写方法，包括XML标记、命名空间定义、元素属性及样式应用，展示了如何通过UXML创建用户界面的逻辑结构。

编写UXML模板

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

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

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

该文件的第一行是XML声明。声明是可选的。如果包含声明，则必须位于第一行，并且其前面不得出现在其他内容或空格。该version属性是必需的，encoding属性是可选的。如果包含encoding，则必须声明文件的字符编码。

下一行定义文档根元素<UXML>，<UXML>元素包括命名空间前缀定义的属性和schema定义文件的位置。您可以不按特定顺序指定这些属性。

在UI元素内部，每个元素都将在UnityEngine.UIElements或在UnityEditor.UIElements命名空间中定义：

该UnityEngine.UIElements命名空间包含了被定义为Unity运行时一部分的元件。
该UnityEditor.UIElements命名空间包含了位于Unity编辑器中的元素。要完全指定元素，必须在其前面添加其命名空间。

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

要使命名空间的指定更容易，可以定义命名空间前缀。例如，xmlns:engine="UnityEngine.UIElements"将前缀engine定义为UnityEngine.UIElements。定义了命名空间前缀后，可以使用它来指定命名空间。例如，<engine:Button />相当于<UnityEngine.UIElements:Button />

您还可以定义默认命名空间而省略前缀。例如，该行xmlns="UnityEngine.UIElements"定义UnityEngine.UIElements为默认命名空间。这意味着，例如，指定<Button />等同于<UnityEngine.UIElements:Button />

如果定义自己的元素，则这些元素可能在其自己的命名空间中定义。如果要在UXML模板中使用这些元素，则必须在<UXML>标记中包含命名空间定义、Schema文件位置以及Unity命名空间。

通过选择Asset > Create > UIElements Editor Window，编辑器会自动为您定义命名空间。

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

元素名称将会匹配要实例化的元素的C＃类名称。大多数元素都有属性，它们的将会值映射到C＃类中相应的属性。每个元素都继承其父类型的属性，也可以添加自己的属性集。VisualElement作为所有可视元素的基类，它为所有元素提供以下属性：

name：元素的标识符。名称应该是唯一的。
picking-mode：设置为Position以响应鼠标事件，或设置为Ignore以忽略鼠标事件。
focus-index:( 已淘汰）使用tabIndex和focusable。
tabindex：一个整数，用于定义当前元素的Tab键位置。
focusable：一个布尔值，指示元素是否可聚焦。
class：以空格分隔的标识符列表，用于描述元素的外观。使用class为元素指定视觉样式。您还可以使用class在UQuery中选择一组元素。
tooltip：当鼠标悬停在元素上时显示的工具提示字符串。
view-data-key ：一个字符串，用于定义用于序列化元素的键。

UXML模板示例未定义用户界面的可视方面。建议您定义样式信息，例如用于绘制UI
的尺寸，字体和颜色中的单独USS文件（请参阅样式和Unity样式表）。

向UXML添加样式

在引用样式表文件后，UXML文件可以在元素声明下使用<Style>元素。

例如，如果您在同一文件夹中有UXML文件和名为“styles.uss”的USS文件：

<engine:UXML ...>
    <engine:VisualElement class="root">
        <Style src="styles.uss" />
    </engine:VisualElement>
</engine:UXML>

#root {
    width: 200px;
    height: 200px;
    background-color: red;
}

注意： Unity不支持根元素<UXML>下的<Style>元素。

您还可以直接声明内联式的Style，作为UXML元素的属性：

<engine:UXML ...>
    <engine:VisualElement style="width: 200px; height: 200px; background-color: red;" />
</engine:UXML>

重用UXML文件

您可以在一个UXML文件中通过简单的定义来创建组件（class），而后在另一个UXML文件中使用<Template>和<Instance>来导入它们。

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

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

例如，假设您在文件Assets/Portrait.uxml中有一个Portrait组件：

<engine:UXML ...>
    <engine:VisualElement class="portrait">
        <engine:Image name="portaitImage" style="--unity-image: url(\"a.png\")"/>
        <engine:Label name="nameLabel" text="Name"/>
        <engine:Label name="levelLabel" text="42"/>
    </engine:VisualElement>
</engine:UXML>

接着，您可以将Portrait组件嵌入到其他UXML模板中，如下所示：

<engine:UXML ...>
    <engine:Template src="/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引用其他文件

UXML文件可以通过元素引用其他UXML文件和USS文件。

两个<Template>和<Style>元素接受任一种“src”属性或“路径”属性。

该src属性允许相对路径，在导入时提供错误消息（例如，缺少文件时），并确保Unity正确包含您的UXML文件在播放器构建中引用的资产。

该path属性允许使用Unity资源机制，但在导入时不提供错误报告，并且不允许相对路径。

`src`属性

该src属性要求文件路径相对于项目根目录或包含该UXML文件的文件夹。您必须包含文件扩展名。在以下示例中，UXML文件位于Assets \ Editor \ UXML，USS文件位于Assets \ Editor \ USS。

根据该UXML文件的位置，可以使用以下相对路径：src="../USS/styles.uss"或src="template.uxml"
根据项目文件夹的位置，可以使用以下绝对路径：src="/Assets/Editor/USS/styles.uss"或src="project:/Assets/Editor/UXML/template.uxml"。

`path`属性

path属性接受位于Resources文件夹或Editor Default Resources文件夹中的文件，其中包含以下规则：

如果文件位于Resources文件夹中，请不要包含文件扩展名。例如，path="template"代表位于Assets / Resources / template.uxml的文件。
如果文件位于Editor Default Resources文件夹中，则必须包含文件扩展名。例如，path="template.uxml"代表位于Assets / Editor Default Resources / template.uxml的文件。