You can create a UXML file as a template and reuse it in other UXML files.
When you design a large user interface, you can create template UXML files that define parts of the UI, and use the <Template>
and <Instance>
elements to import it into another UXML file.
For example, if you have a portrait UI element that has an image, a name, and a label, you can create a UXML template file as Assets/Portrait.uxml
with the following content:
<ui:UXML ...>
<ui:VisualElement class="portrait">
<ui:Image name="portaitImage" style="--unity-image: url(\"a.png\")"/>
<ui:Label name="nameLabel" text="Name"/>
<ui:Label name="levelLabel" text="42"/>
</ui:VisualElement>
</ui:UXML>
You can then reuse the Portrait template like this:
<ui:UXML ...>
<ui:Template src="/Assets/Portrait.uxml" name="Portrait"/>
<ui:VisualElement name="players">
<ui:Instance template="Portrait" name="player1"/>
<ui:Instance template="Portrait" name="player2"/>
</ui:VisualElement>
</ui:UXML>
When you create instances of a UXML template, you can override the default attribute values of its elements. Attribute overrides allow you to instantiate the same template many times with different values for each instance.
You can override attributes with the UXML
tag. To override an attribute, specify the following:
element-name
attribute of the element whose attributes you want to overrideFor example, if you want to display the same set of information for each player in your game, you can create a UXML template, and use attribute overrides to create player-specific instances.
First, create a template, such as MyTemplate.uxml
, with the following content:
<UXML xmlns="Unityui.UIElements">
<Label name="player-name-label" text="default name" />
<Label name="player-score-label" text="default score" />
</UXML>
Then, instance it from another UXML file and override its attributes to display each player’s name and score:
<UXML xmlns="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements">
<Template src="MyTemplate.uxml" name="MyTemplate" />
<Instance name="player1" template="MyTemplate">
<!-- Alice is the new value of the text attribute for the player-name-label -->
<AttributeOverrides element-name="player-name-label" text="Alice" />
<!-- 2 is the new value of the text attribute for the player-score-label -->
<AttributeOverrides element-name="player-score-label" text="2" />
</Instance>
<Instance name="player2" template="MyTemplate">
<!-- Bob is the new value of the text attribute for the player-name-label -->
<AttributeOverrides element-name="player-name-label" text="Bob" />
<!-- 1 is the new value of the text attribute for the player-score-label -->
<AttributeOverrides element-name="player-score-label" text="1" />
</Instance>
</UXML>
您可以为每个覆盖指定多个属性。例如,以下语法查找名为 player-name-label
的实例中的任何元素,并且
Alice
覆盖其 text
属性的默认值。Tooltip 1
覆盖其 tooltip
属性的默认值。<AttributeOverrides element-name="player-name-label" text="Alice" tooltip="Tooltip 1" />
属性覆盖通过元素层级结构中的嵌套模板传播。例如,如果模板 A 实例化模板 B,而模板 B 实例化模板 C,则模板 A 和模板 B 都可以覆盖模板 C 中的属性。
When you override attributes in nested templates, the deepest override takes precedence. In the example above, if template A and template B both override the same attribute of template C, the override in template B determines what actually appears in the rendered UI.
If you’re creating instances of a UXML template, and an element in the template has an inline style defined with the style
attribute, you can’t use AttributeOverrides
to override that style
attribute. However, you can use USS selectors in a USS style sheet to override the styling of your template instances.
For example, if you have the following UXML template called Hotkeys.uxml
that defines a #Container
with two labels, and the #Container
has an inline style that defines the flex row direction:
<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" editor-extension-mode="False">
<ui:VisualElement name="Container" style="flex-direction: row;">
<ui:Label text="E" name="Hotkeys" />
<ui:Label text="Talk" name="Action" />
</ui:VisualElement>
</ui:UXML>
If you want to create two template instances with the second having a reversed flex row direction, you can’t use AttributeOverides
to override the style
attribute of the #Container
element in your second instance.
To override the style, do the following:
#Container
in the above UXML template (Hotkeys.uxml
).HotkeysXML
and ReversedHotkeysXML
.ContextHotkeys.uss
, to your UXML instance file.<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements">
<ui:Template name="HotkeysXML" src="HotkeysXML.uxml"/>
<Style src="ContextHotKeys.uss"/>
<ui:Instance template="HotkeysXML" name="HotkeysXML" />
<ui:Instance template="HotkeysXML" name="ReversedHotkeysXML" />
</ui:UXML>
You can then create ContextHotkeys.uss
to change the #Container
style according to the template instance name:
#ReversedHotkeysXML > #Container {
flex-direction: row-reverse;
}
#HotkeysXML > #Container {
flex-direction: row;
}
Attribute overrides have the following limitations:
binding-path
attribute, data binding doesn’t work with attribute overrides.class
, name
, or style
attributes.You can use the content-container
attribute of a visual element to specify where to nest child elements in a UXML template. For example, if you have the following UXML template file as Assets/MyTemplate.uxml
:
<ui:UXML xmlns:ui="UnityEngine.UIElements" ...>
<ui:Label text="Group Title" name="groupTitle" />
<ui:VisualElement name="group-container" content-container="anyValue">
<!--Add child elements here -->
</ui:VisualElement>
<ui:VisualElement/>
</ui:UXML>
You can then apply the template with nested child elements as this:
<ui:UXML xmlns:ui="UnityEngine.UIElements" ...>
<Template path="Assets/MyTemplate.uxml" name="my-template"/>
<ui:Instance template="my-template">
<ui:Label text="Test"/> <!--This label element will be instantiated inside the `group-container` element.-->
</ui:Instance>
<ui:Instance template="my-template">
<ui:Label text="Test"/> <!--This label element will be instantiated in the template -->
</ui:Instance>
</ui:UXML>
Note: You can provide any value to the content-container
attribute.