UXML 形式

C# から 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> 要素には、名前空間のプレフィックス定義の属性とスキーマ定義ファイルの場所が含まれます。これらの属性は特定の順番で指定することはできません。

UIElements では、各要素は 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 > UIElements 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 へスタイルを追加

スタイルシートファイルを参照するために、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 ファイルで定義するだけでコンポーネントを作成し、他の 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 から他のファイルを参照

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" と書き込みます。

2018–11–02 修正されたページ

UXML 形式

C# から UXML を読み込む

マニュアル

UXML テンプレートの作成

UXML へスタイルを追加

UXML ファイルの再利用

UXML から他のファイルを参照

src 属性

path 属性

`src` 属性

`path` 属性