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>
要素には、名前空間のプレフィックス定義の属性とスキーマ定義ファイルの場所が含まれます。これらの属性は特定の順番で指定することはできません。
UI Toolkit では、各要素は UnityEngine.UIElements
か UnityEditor.UIElements
名前空間のいずれかで定義されます。
UnityEngine.UIElements
名前空間には、Unity Runtime の一部として定義された要素が含まれています。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 テンプレートで使用したい場合は、名前空間の定義とスキーマファイルの場所を Unity の名前空間と共に <UXML>
タグに含む必要があります。
Asset > Create > UI Toolkit > Editor Window を選択して新しいUXML テンプレートアセットを作成すると、エディターが自動的に名前空間を定義します。
UI の定義は <UXML>
ルートの中にあります。UI 定義は一連のネストになった XML 要素で、それぞれが VisualElement
を表します。
要素名は、インスタンス化する要素の C# クラス名に対応します。ほとんどの要素は属性を持ち、その値は C# の対応するクラスプロパティにマップされます。各要素は親クラスの型の属性を継承し、それ自体の属性の集合を追加することができます。VisualElement
はすべての要素の基本クラスであり、すべての要素に対して以下の属性を提供します。
name
: 要素の識別子。名前は一意である必要があります。picking-mode
: マウスイベントに応答するには Position
に設定し、マウスイベントを無視するには Ignore
に設定します。focus-index
: (古い機能) tabIndex
と focusable
を使用します。tabindex
: 現在の要素のタブ位置を定義する整数focusable
: 要素がフォーカス可能かどうかを示すブーリアンclass
: 要素を特徴付ける識別子のスペース区切りのリスト。クラスを使用して要素にビジュアルスタイルを割り当てます。クラスを使用して、UQuery の一連の要素を選択することもできます。tooltip
: マウスオーバーするとツールチップとして表示される文字列。view-data-key
: 要素のシリアル化に使用されるキーを定義する文字列UXML テンプレートの例では、ユーザー インターフェースの視覚的な特性は定義されていません。UI を描画するための寸法、フォント、色などのスタイル情報は、別の USS ファイルで定義する必要があります (スタイルと Unity スタイルシート を参照してください)。
スタイルシートファイルを参照するために、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>
要素をサポートしていません。
インラインスタイルを UXML 要素の属性として直接宣言することもできます。
<engine:UXML ...>
<engine:VisualElement style="width: 200px; height: 200px; background-color: red;" />
</engine:UXML>
コンポーネントを UXML ファイルで定義するだけでコンポーネントを作成し、他の UXML ファイルの <Template>
と <Instance>
要素を使ってインポートできます。
大規模なユーザーインターフェースを設計する場合、UI の一部を定義するテンプレート UXML ファイルを作成できます。
同じ UI 定義を多くの場所で使用できます。例えば、画像、名前、ラベルを持つ横向きの UI 要素があるとします。UXML テンプレートファイルを作成して、横向きの UI 要素を他の UXML ファイルで再利用することができます。
例えば、ファイル 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 テンプレートのインスタンスを作成すると、その要素のデフォルト属性値をオーバーライドすることができます。属性のオーバーライドで、インスタンスごとに異なる値を使って同じテンプレートを何度もインスタンス化できます。
属性をオーバーライドするには、以下を指定する必要があります。
element-name 属性
以下の例では
player-name-label
は、その要素の element-name
属性です。text
はオーバーライドする属性です。Alice
は新しい属性値です。<AttributeOverrides element-name="player-name-label" text="Alice" />
属性のオーバーライドは、インスタンス全体に影響します。つまり、インスタンスに player-name-label
という名前の 2 つの要素があり、どちらも text
属性を持っている場合、オーバーライドはその両方に影響します。
例えば、ゲームを作っていて、各プレイヤーに同じ情報を表示させたいとします。再利用可能な 1 つのテンプレートを作成し、属性のオーバーライドを使用してプレイヤー固有のインスタンスを作成することができます。
例えば、以下のようなテンプレートを作成したとします。
<UXML xmlns="UnityEngine.UIElements">
<Label name="player-name-label" text="default name" />
<Label name="player-score-label" text="default score" />
</UXML>
別の UXML ファイルからインスタンスを作成し、その属性をオーバーライドして、各プレイヤーの名前とスコアを表示します。
<UXML xmlns="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements">
<Template src="MyTemplate.uxml" name="MyTemplate" />
<Instance name="player1" template="MyTemplate">
<AttributeOverrides element-name="player-name-label" text="Alice" />
<AttributeOverrides element-name="player-score-label" text="2" />
</Instance>
<Instance name="player2" template="MyTemplate">
<AttributeOverrides element-name="player-name-label" text="Bob" />
<AttributeOverrides element-name="player-score-label" text="1" />
</Instance>
</UXML>
各オーバーライドで複数の属性を指定できます。例えば、以下の構文は、player-name-label
という名前のインスタンスのすべての要素を検出します。
text
属性のデフォルト値を、新しい値 Alice
でオーバーライドします。tooltip
属性のデフォルト値を、新しい値 Tooltip 1
でオーバーライドします。<AttributeOverrides element-name="player-name-label" text="Alice" tooltip="Tooltip 1" />
属性のオーバーライドは、要素の階層のネスト状のテンプレートを通して伝播します。例えば、テンプレート A がテンプレート B をインスタンス化し、テンプレート B がテンプレート C をインスタンス化する場合、テンプレート A とテンプレート B の両方がテンプレート C の属性をオーバーライドできます。
ネスト状のテンプレートで属性をオーバーライドする場合、最も深い位置のオーバーライドが優先されます。したがって、上記の例では、テンプレート A とテンプレート B の両方がテンプレート C の同じ属性をオーバーライドする場合、テンプレート B のオーバーライドが、描画された UI に実際に表示されるものを決定します。
binding-path
属性をオーバーライドすることは可能です。name
や style
属性をオーバーライドすることはできません。UXML ファイルは、要素を通して他の UXML ファイルと USS ファイルを参照できます。
<Template>
要素と <Style>
要素はどちらも、“src” 属性または “path” 属性を受け入れます。
src
属性は相対パスを許可し、インポート時にエラーメッセージを表示し (例えば、ファイルが欠落している場合)、Unity が UXML ファイルが参照するアセットをプレイヤービルドに適切に加えます。
path
属性は Unity Resources メカニズムの使用を許可しますが、インポート時にエラーレポートを提供せず、相対パスを許可しません。
src
属性src
属性はファイルパスがプロジェクトのルートか、UXML ファイルを含むフォルダーのどちらかに相対的であることを前提にしています。ファイル拡張子を入れる必要があります。以下の例では、UXML ファイルは Assets\Editor\UXML に置かれ、USS ファイルは Assets\Editor\USS に置かれています。
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 フォルダーにあるファイルを受け入れます。
path="template"
と書き込みます。path="template.uxml"
と書き込みます。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.