Version: 2020.3
レイアウトエンジン
UXML テンプレートの作成

UXML 形式

Unity Extensible Markup Language (UXML) files are text files that define the structure of the user interface. The UXML format is inspired by HTML, XAML, and XML. If you’ve worked with these formats before, you’ll find similarities with UXML. However, the UXML format includes small differences to provide an efficient way to work with Unity.

このセクションでは、Unity がサポートする UXML 形式について説明し、UXML テンプレートの記述、読み込み、定義の詳細について説明します。また、新しい要素の定義や UQuery の使い方に関する情報も提供します。

UXML makes it easier for less technical users to build a user interface within Unity. In UXML you can:

  • XMLでユーザーインターフェース (UI) の構造の定義
  • USS スタイルシートによる UI レイアウトを定義

これにより、開発者はアセットのインポート、ロジックの定義、データの処理などの技術的な作業を行うことができます。

Defining new elements

With UI Toolkit, you can define your own user interface components and elements.

UXML ファイルを使用して新しい要素を定義する前に、VisualElement かそのサブクラスの 1 つから新しいクラスを派生させ、次にこの新しいクラス内で適切な機能を実装する必要があります。新しいクラスにはデフォルトコンストラクターを実装する必要があります。

例えば、以下のコードは新しい StatusBar クラスを派生させ、デフォルトのコンストラクターを実装します。

class StatusBar : VisualElement
{
    public StatusBar()
    {
        m_Status = String.Empty;
    }

    string m_Status;
    public string status { get; set; }
}

In order for UI Toolkit to instantiate a new class when reading a UXML file, you must define a factory for your class. Unless your factory needs to do something special, you can derive the factory from UxmlFactoy<T>. It’s recommended that you put the factory class within your component class.

例えば、以下のコードは StatusBar クラスの Factory を UxmlFactory <T> から派生させてファクトリを定義する方法を示しています。 Factory は UxmlFactory という名前です。

class StatusBar : VisualElement
{
    public new class UxmlFactory : UxmlFactory<StatusBar> {}

    // ...
}

この Factory を定義すると、UXML ファイルの <StatusBar> 要素を使用することができます。

要素の属性の定義

新しいクラスに UXML の特性 (traits) を定義し、その特性を使用するように Factory を設定することができます。

For example, the following code demonstrates how to define a UXML traits class to initialize the status property as a property of the StatusBar class. The status property initializes from XML data.

class StatusBar : VisualElement
{
    public new class UxmlFactory : UxmlFactory<StatusBar, UxmlTraits> {}

    public new class UxmlTraits : VisualElement.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 つの目的があります。

  • The factory uses it to initialize the newly created object.
  • The schema generation process analyzes it to get information about the element. This information translates into XML schema directives.

上のサンプルコードは以下の処理を行います。

  • m_Status の宣言は XML 属性 status を定義します。
  • uxmlChildElementsDescriptionStatusBar 要素に子がないことを示す空の IEnumerable を返します。
  • Init() メンバーは、XML パーサーからプロパティバッグの status 属性の値を読み込み、StatusBar.status プロパティにこの値に設定します。
  • StatusBar クラスの中に UxmlTraits クラスを置くことによって Init() メソッドが StatusBar のプライベートメンバーにアクセスできるようにします。
  • 新しい UxmlTraits クラスは基本クラス UxmlTraits を継承しているので、基本クラスの属性を共有します。
  • Init()base.Init() を呼び出して基本クラスのプロパティを初期化します。

The code example above declares a string attribute with the UxmlStringAttributeDescription class. UI Toolkit supports the following types of attributes and each links a C# type to an XML type:

属性 属性値
UxmlStringAttributeDescription 文字列
UxmlFloatAttributeDescription C# float 型の範囲の単精度浮動小数点値
UxmlDoubleAttributeDescription C# double 型の範囲の倍精度浮動小数点値
UxmlIntAttributeDescription C# int 型の範囲の整数値
UxmlLongAttributeDescription C# long 型の範囲の整数値
UxmlBoolAttributeDescription true または false
UxmlColorAttributeDescription 色を表す文字列 (#FFFFFF)
UxmlEnumAttributeDescription<T> EnumT 値の 1 つを表す文字列

上記のコード例では、uxmlChildElementsDescriptionStatusBar 要素が子を受け付けないことを示す空の IEnumerable を返します。

To have an element accept children of any type, you must override the uxmlChildElementsDescription property. For example, for the StatusBar element to accept children of any type, the uxmlChildElementsDescription property must be specified as follows:

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")]

You can do this at the root level (outside any namespace) of any C# file of the assembly.

スキーマ生成システムは以下を行います。

  • Checks for these attributes and uses them to generate the schema.
  • Adds the namespace prefix definition as an attribute of the <UXML> element in newly created UXML files
  • Includes the schema file location for the namespace in its xsi:schemaLocation attribute.

You should update the UXML schema of your project. Select Assets > Update UXML Schema to ensure that your text editor recognizes the new element.

The defined prefix is available in the newly created UXML by selecting Create > UI Toolkit > Editor Window in the Project/Assets/Editor folder.

より高度な使い方

UXML 名をカスタマイズする

IUxmlFactory.uxmlNameIUXmlFactory.uxmlQualifiedName プロパティをオーバーライドすることによって、UXML 名をカスタマイズできます。uxmlName が名前空間内で一意であり、uxmlQualifiedName がプロジェクト内で一意であることを確認してください。

If both names aren’t unique, an exception is thrown when you attempt to load your assembly.

次のサンプルコードは、UXML 名をオーバーライドしてカスタム化する方法を示しています。

public class FactoryWithCustomName : UxmlFactory<..., ...>
{
    public override string uxmlName
    {
        get { return "UniqueName"; }
    }

    public override string uxmlQualifiedName
    {
        get { return uxmlNamespace + "." + uxmlName; }
    }
}

要素の Factory を選択する

デフォルトでは、IUxmlFactory は要素をインスタンス化し、要素の名前を使用して要素を選択します。

IUXmlFactory.AcceptsAttributeBag をオーバーライドすることで、選択プロセスで要素の属性値を考慮させることができます。次に、要素の属性を調べて、UXML 要素のオブジェクトをインスタンス化できるかどうかを決定します。

This is useful if your VisualElement class is generic. In this case, the class factory for a specialization of your class could examine the value of a XML type attribute. Depending on the value, instantiation can be accepted or refused. For an example, see the implemenatation of PropertyControl<T>.

複数の Factory が要素をインスタンス化できる場合は、最初に登録された Factory が選択されます。

基本クラス属性のデフォルト値をオーバーライドする

基本クラスで宣言された属性のデフォルト値は UxmlTraits クラスの defaultValue を設定することで変更できます。

例えば、以下のコードは m_TabIndex のデフォルト値を変更する方法を示しています。

class MyElementTraits : VisualElement.UxmlTraits
    {
        public MyElementTraits()
        {
            m_TabIndex.defaultValue = 0;
        }
    }

任意の属性を受け入れる

デフォルトで、XML スキーマが生成されると、要素は任意の属性を持つことができます。

UxmlTraits クラスで宣言されたもの以外の属性の値は制限されません。これは、宣言された属性の値が宣言に一致するかどうかをチェックする XML バリデーターとは対照的です。

Additional attributes are included in the IUxmlAttributes bag that’s passed to the IUxmlFactory.AcceptsAttributBag() and IUxmlFactory.Init() functions. It’s up to the factory implementation to use these additional attributes. The default behavior is to discard additional attributes.

This means that these additional attributes aren’t attached to the instantiated VisualElement and you cannot query these attributes with UQuery.

新しい要素を定義するとき、 UxmlTraits コンストラクターで UxmlTraits.canHaveAnyAttribute プロパティを false に設定することによって、受け入れられた属性を明示的に宣言された属性に限定することができます。

Using Schema definitions

スキーマ定義ファイルは、属性と、各 UXML 要素が含むことのできる属性の子要素を指定します。正しいドキュメントを作成して、ドキュメントを検証するためのガイドとして、スキーマ定義ファイルを使用します。

In the UXML template file, the xsi:noNamespaceSchemaLocation and xsi:schemaLocation attributes of the <UXML> root element specify the location of the schema definition files.

Select Assets > Create > UI Toolkit > Editor Window to automatically update your schema definition with the latest information from the VisualElement sub-classes used by your project. To force an update of the UXML schema files, select Assets > Update UXML Schema.

Note: Some text editors don’t recognize the xsi:noNamespaceSchemaLocation attribute. If your text editor can’t find the schema definition files, you should also specify the xsi:schemaLocation attribute.

レイアウトエンジン
UXML テンプレートの作成