UXML の概要

UXML 形式は、HTML、XAML、XML にヒントを得ています。これらの形式を使ったことがある人は、UXML に似ていることに気づくでしょう。しかし、UXML 形式には、Unity との作業を効率的に行うための相違点があります。このページでは UXML の形式を例を挙げて紹介します。

以下は UXML ファイルの例です。ユーザーに選択を促すいくつかのビルトインの UI コントロールが含まれています。

<?xml version="1.0" encoding="utf-8"?>
<UXML ...>
    <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>

UXML 宣言

上記の UXML の例の最初の行は UXML 宣言です。この宣言は任意です。UXML 宣言を入れる場合は、1 行目に記述する必要があります。UXML 宣言には version が必要です。UXML 宣言では、encoding 属性は必須ではありません。encoding 属性を指定する場合は、ファイルの文字エンコーディングを宣言しなければなりません。

ドキュメントルート

次の行はドキュメントルート <UXML> を定義します。<UXML> 要素には、名前空間のプレフィックス定義の属性とスキーマ定義ファイルの場所が含まれます。これらの属性は特定の順番で指定することはできません。

名前空間

UI Toolkit では、各要素は 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 ファイルを作成するには、Asset > Create > UI Toolkit > UI Document を選択します。

ノート: 独自の要素を定義する場合は、UnityEngine.UIElements または UnityEditor.UIElements 名前空間でカスタムコントロールクラスを定義しないでください。さもないと、UI Builder はカスタムコントロールを非表示にします。

スキーマ定義

スキーマ定義は UXML ファイルを検証します。スキーマ定義では、各 UXML 要素に含まれる属性や子要素を指定します。

UXML ファイルでは、<UXML> ルート要素の xsi:noNamespaceSchemaLocation 属性か xsi:schemaLocation 属性が、スキーマ定義ファイルの場所を指定します。

最新のスキーマ定義で UXML ファイルを作成するには、Assets > Create > UI Toolkit > UI Document を選択します。これにより、ルート要素に xsi:noNamespaceSchemaLocation 属性を持つファイルが作成されます。

ノート: テキストエディターが xsi:noNamespaceSchemaLocation 属性を認識しない場合は、代わりに xsi:schemaLocation 属性を使用してください。

UXML スキーマ定義を強制的に更新するには、Assets > Update UXML Schema を選択します。

UXML 要素

UI の定義は <UXML> ルートの中にあります。UI 定義は一連のネストになった UXML 要素で、それぞれがビジュアル要素を表します。

要素名は、インスタンス化する要素の C# クラス名に対応します。ほとんどの要素は属性を持ち、その値は C# の対応するクラスプロパティーにマップされます。各要素には、親クラスから継承された属性に加えて、一揃いの独自の属性があります。VisualElement はすべての要素の基本クラスであり、すべての要素に対して以下の属性を提供します。

name: 要素の識別子。名前は一意である必要があります。
picking-mode: マウスイベントに応答するには Position に設定し、マウスイベントを無視するには Ignore に設定します。
focus-index: (古い機能) tabIndex と focusable を使用します。
tabindex: 現在の要素のタブ位置を定義する整数
focusable: 要素がフォーカス可能かどうかを示すブーリアン
class: 要素を特徴付ける識別子のスペース区切りのリスト。クラスを使用して要素にビジュアルスタイルを割り当てます。クラスを使用して、UQuery の一連の要素を選択することもできます。
tooltip: マウスオーバーするとツールチップとして表示される文字列。
view-data-key: 要素のシリアル化に使用されるキーを定義する文字列

その他の参考資料

UXML による UI の構築

UXML にスタイルを加える