UXML ファイルは、ユーザーインターフェースの論理的構造を定義するテキストファイルです。 UXML ファイルで使用される形式は、HTML (HyperText Markup Language)、XAML (eXtensible Application Markup Language)、XML (eXtensible Markup Language) から発想を得ています。これらの良く知られた形式に精通している場合は、UXML に多くの類似点があることに気づくはずです。ただし、UXML 形式には、Unity を効率的に使用するための小さな違いがあります。
このセクションでは、Unity がサポートする UXML 形式について説明し、UXML テンプレートの記述、読み込み、定義の詳細について説明します。また、新しい要素の定義や UQuery の使い方に関する情報も提供します。
UXML を使用することで、技術的に精通していないユーザーが Unity 内でユーザーインターフェースを作成しやすくなります。UXMLでは以下のことが可能です。
これにより、開発者はアセットのインポート、ロジックの定義、データの処理などの技術的な作業を行うことができます。
UIElements は拡張可能です。独自のユーザーインターフェースコンポーネントと要素を定義することができます。
しかし、UXML ファイルを使用して新しい要素を定義する前に、VisualElement
かそのサブクラスの 1 つから新しいクラスを派生させ、次にこの新しいクラス内で適切な機能を実装する必要があります。新しいクラスにはデフォルトコンストラクターを実装する必要があります。
例えば、以下のコードは新しい StatusBar
クラスを派生させ、デフォルトのコンストラクターを実装します。
class StatusBar:VisualElement
{
public StatusBar()
{
m_Status = String.Empty;
}
string m_Status;
public string status {get; }
}
UXML ファイルを読み込むときに UIElements が新しいクラスをインスタンス化できるようにするには、クラスの Factory を定義する必要があります。Factory が特別なことを行う必要がない限り、UxmlFactoy <T>
から Factory を派生させることができます。また、Factory クラスをコンポーネントクラス内に配置することも推奨されます。
例えば、以下のコードは StatusBar
クラスの Factory を UxmlFactory <T>
から派生させてファクトリを定義する方法を示しています。 Factory は Factory
という名前です。
class StatusBar : VisualElement
{
public new class Factory : UxmlFactory<StatusBar> {}
// ...
}
この Factory を定義すると、UXML ファイルの <StatusBar>
要素を使用することができます。
注意: 2018.2 で Factory が改善されました。以前のバージョンで Factory を定義した場合は、現在廃止されている API を避けるために Factory を 2018.3 に移植する必要があります。
新しいクラスに UXML の特性 (traits) を定義し、その特性を使用するように Factory を設定することができます。
例えば、下のコードは UXML の Traits クラスを定義して status
プロパティを StatusBar
クラスのプロパティとして初期化する方法を示しています。status プロパティは XML データから初期化されます。
class StatusBar : VisualElement
{
public new class Factory : UxmlFactory<StatusBar, UxmlTraits> {}
public new class Traits : base.UxmlTraits
{
UxmlStringAttributeDescription m_Status = new UxmlStringAttributeDescription { name = "status" };
public override IEnumerable<UxmlChildElementDescription> uxmlChildElementsDescription
{
get { yield break; }
}
public override void Init(VisualElement ve, IUxmlAttributes bag, CreationContext cc)
{
base.Init(ve, bag, cc);
((StatusBar)ve).status = m_Status.GetValueFromBag(bag, cc);
}
}
// ...
}
UxmlTraits
には 2 つの目的があります。
新しく作成されたオブジェクトを初期化するために Factory で使用されます。
要素に関する情報を取得するためにスキーマの生成処理によって分析されます。この情報は XML スキーマディレクティブに変換されます。
上のサンプルコードは以下の処理を行います。
m_Status
の宣言は XML 属性 status
を定義します。uxmlChildElementsDescription
は StatusBar
要素に子がないことを示す空の IEnumerable
を返します。Init()
メンバーは、XML パーサーからプロパティバッグの status
属性の値を読み込み、StatusBar.status
プロパティにこの値に設定します。StatusBar
クラスの中に UxmlTraits
クラスを置くことによって Init()
メソッドが StatusBar
のプライベートメンバーにアクセスできるようにします。UxmlTraits
クラスは基本クラス UxmlTraits
を継承しているので、基本クラスの属性を共有します。Init()
は base.Init()
を呼び出して基本クラスのプロパティを初期化します。前述のコード例は UxmlStringAttributeDescription
クラスで文字列属性を宣言しています。UIElements は以下のタイプの属性をサポートし、それぞれが C# 型を XML 型にリンクします。
UxmlStringAttributeDescription
: 属性の値は文字列ですUxmlFloatAttributeDescription
: 属性値は、C# の float
型の範囲の単精度浮動小数点値でなければなりません。UxmlDoubleAttributeDescription
: 属性値は、C# double
型の範囲の倍精度浮動小数点値でなければなりません。UxmlIntAttributeDescription
: 属性値は C# int
型の範囲の整数値でなければなりません。UxmlLongAttributeDescription
: 属性値は C# long
型の範囲の整数値でなければなりません。UxmlBoolAttributeDescription
: 属性値は true
か false
でなければなりません。UxmlColorAttributeDescription
: 属性値は色 (#FFFFFF
) を表す文字列でなければなりません。。UxmlEnumAttributeDescription <T>
属性値は Enum
型 T
の値の 1 つを表す文字列でなければなりません。上記のコード例では、uxmlChildElementsDescription
は StatusBar
要素が子を受け付けないことを示す空の IEnumerable
を返します。
要素が任意の型の子を受け入れるには、uxmlChildElementsDescription
プロパティをオーバーライドする必要があります。例えば、StatusBar
要素が任意の型の子を受け入れるためには、uxmlChildElementsDescription
プロパティを以下のように指定する必要があります。
public override IEnumerable<UxmlChildElementDescription> uxmlChildElementsDescription
{
get
{
yield return new UxmlChildElementDescription(typeof(VisualElement));
}
}
C# で新しい要素を定義したら、要素を UXML ファイルで使用することができます。新しい要素が新しい名前空間で定義されている場合は、名前空間のプレフィックスを定義する必要があります。名前空間のプレフィックスはルートの <UXML>
要素への属性として宣言され、要素をスコープするときに完全な名前空間名を置き換えます。
名前空間プレフィックスを定義するには、定義したいそれぞれの名前空間プレフィックスのアセンブリに UxmlNamespacePrefix
属性を加えます。
[assembly:UxmlNamespacePrefix( "My.First.Namespace"、 "first")]
[assembly:UxmlNamespacePrefix( "My.Second.Namespace"、 "second")]
これは、アセンブリの C# ファイルのルートレベル (任意の名前空間の外側) で行います。
スキーマ生成システムは以下を行います。
<UXML>
要素の属性として名前空間プレフィックスの定義を加えます。xsi:schemaLocation
属性に名前空間のスキーマファイルの場所を含めます。プロジェクトの UXML スキーマを更新する必要があります。Assets > Update UIElements Schema を選択して、テキストエディターが新しい要素を認識できるようにします。
IUxmlFactory.uxmlName
と IUXmlFactory.uxmlQualifiedName
プロパティをオーバーライドすることによって、UXML 名をカスタマイズできます。uxmlName
が名前空間内で一意であり、uxmlQualifiedName
がプロジェクト内で一意であることを確認してください。
両方の名前が一意でない場合は、アセンブリをロードしようとすると例外がスローされます。
次のサンプルコードは、UXML 名をオーバーライドしてカスタム化する方法を示しています。
public class FactoryWithCustomName : UxmlFactory<..., ...>
{
public override string uxmlName
{
get { return "UniqueName"; }
}
public override string uxmlQualifiedName
{
get { return uxmlNamespace + "." + uxmlName; }
}
}
デフォルトでは、IUxmlFactory
は要素をインスタンス化し、要素の名前を使用して要素を選択します。
IUXmlFactory.AcceptsAttributeBag
をオーバーライドすることで、選択プロセスで要素の属性値を考慮させることができます。次に、要素の属性を調べて、UXML 要素のオブジェクトをインスタンス化できるかどうかを決定します。
これは、例えば、VisualElement
クラスがジェネリックである場合に便利です。この場合、クラスの特殊化のためのクラス Factory は XML の type
属性の値を調べることができます。値に応じて、インスタンス化を受け入れるか拒否するかを決定します。例は、PropertyControl <T>
の実装を参照してください。
複数の Factory が要素をインスタンス化できる場合は、最初に登録された Factory が選択されます。
基本クラスで宣言された属性のデフォルト値は UxmlTraits
クラスの defaultValue
を設定することで変更できます。
例えば、以下のコードは m_focusIndex
のデフォルト値を変更する方法を示しています。
class MyElementTraits:VisualElementUxmlTraits
{
public Traits()
{
m_focusIndex.defaultValue = 0;
}
}
デフォルトで、XML スキーマが生成されると、要素は任意の属性を持つことができます。
UxmlTraits
クラスで宣言されたもの以外の属性の値は制限されません。これは、宣言された属性の値が宣言に一致するかどうかをチェックする XML バリデーターとは対照的です。
追加の属性は IUxmlAttributes
の bag に含まれ、IUxmlFactory.AcceptsAttributBag()
と IUxmlFactory.Init()
関数に渡されます。これらの追加属性を使用するかどうかは、 Factory の実装によって異なります。デフォルトの動作では、追加属性を破棄します。
つまり、これらの追加の属性はインスタンス化された VisualElement
にアタッチされず、これらの属性は UQuery
でクエリできません。
新しい要素を定義するとき、 UxmlTraits
コンストラクターで UxmlTraits.canHaveAnyAttribute
プロパティを false
に設定することによって、受け入れられた属性を明示的に宣言された属性に限定することができます。
スキーマ定義ファイルは、属性と、各 UXML 要素が含むことのできる属性の子要素を指定します。正しいドキュメントを作成して、ドキュメントを検証するためのガイドとして、スキーマ定義ファイルを使用します。
UXML テンプレートファイルでは、<UXML>
ルート要素の xsi:noNamespaceSchemaLocation
属性と xsi:schemaLocation
属性は、スキーマ定義ファイルがどこにあるかを指定します。
Assets > Create > UIElements View の順に選択すると、プロジェクトで使用する VisualElement
サブクラスから収集された最新の情報で自動的にスキーマ定義を更新します。UXML スキーマファイルを強制的に更新するには、Assets > Update UIElements Schema を選択します。
ノート: テキストエディターの中には xsi:noNamespaceSchemaLocation
属性を認識できないものがあります。テキストエディターがスキーマ定義ファイルを見つけることができない場合は、xsi:schemaLocation
属性も指定する必要があります。
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.