Write UXML Templates

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 スタイルシート を参照してください)。

Add styles to 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> 要素をサポートしていません。

インラインスタイルを UXML 要素の属性として直接宣言することもできます。

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

Reuse UXML files

コンポーネントを 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>

Override UXML attributes

UXML テンプレートのインスタンスを作成すると、その要素のデフォルト属性値をオーバーライドすることができます。属性のオーバーライドで、インスタンスごとに異なる値を使って同じテンプレートを何度もインスタンス化できます。

属性をオーバーライドするには、以下を指定する必要があります。

• オーバーライドしたい属性を持つ要素の element-name 属性
• オーバーライドする属性の名前
• 新しい属性値

以下の例では

• player-name-label は、その要素の element-name 属性です。
• text はオーバーライドする属性です。
• Alice は新しい属性値です。

<AttributeOverrides element-name="player-name-label" text="Alice" />

属性のオーバーライドは、インスタンス全体に影響します。つまり、インスタンスに player-name-label という名前の 2 つの要素があり、どちらも text 属性を持っている場合、オーバーライドはその両方に影響します。

Attribute override example

例えば、ゲームを作っていて、各プレイヤーに同じ情報を表示させたいとします。再利用可能な 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>

Override multiple attributes

各オーバーライドで複数の属性を指定できます。例えば、以下の構文は、player-name-label という名前のインスタンスのすべての要素を検出します。

• text 属性のデフォルト値を、新しい値 Alice でオーバーライドします。
• tooltip 属性のデフォルト値を、新しい値 Tooltip 1 でオーバーライドします。

<AttributeOverrides element-name="player-name-label" text="Alice" tooltip="Tooltip 1" />

Nest attribute overrides

属性のオーバーライドは、要素の階層のネスト状のテンプレートを通して伝播します。例えば、テンプレート A がテンプレート B をインスタンス化し、テンプレート B がテンプレート C をインスタンス化する場合、テンプレート A とテンプレート B の両方がテンプレート C の属性をオーバーライドできます。

ネスト状のテンプレートで属性をオーバーライドする場合、最も深い位置のオーバーライドが優先されます。したがって、上記の例では、テンプレート A とテンプレート B の両方がテンプレート C の同じ属性をオーバーライドする場合、テンプレート B のオーバーライドが、描画された UI に実際に表示されるものを決定します。

制限

• 属性のオーバーライドは、指定した要素名に従って、一致する属性を見つけます。要素を一致させるために USS セレクター または UQUery を使うことはありません。
• 属性のオーバーライドはデータバインディングとは関係ありませんが、要素の binding-path 属性をオーバーライドすることは可能です。
• 要素の name や style 属性をオーバーライドすることはできません。

Reference other files from UXML

UXML ファイルは、要素を通して他の UXML ファイルと USS ファイルを参照できます。

<Template> 要素と <Style> 要素はどちらも、“src” 属性または “path” 属性を受け入れます。

src 属性は相対パスを許可し、インポート時にエラーメッセージを表示し (例えば、ファイルが欠落している場合)、Unity が UXML ファイルが参照するアセットをプレイヤービルドに適切に加えます。

path 属性は Unity Resources メカニズムの使用を許可しますが、インポート時にエラーレポートを提供せず、相対パスを許可しません。

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 フォルダーにある場合は、ファイル拡張子を含みません。例えば、 Assets/Resources/template.uxml にあるファイルには path="template" と書き込みます。
• ファイルが Editor Default Resources フォルダーにある場合は、ファイル拡張子を含む必要があります。例えば、Assets/Editor Default Resources/template.uxml にあるファイルには path="template.uxml" と書き込みます。