Version: 2022.2
言語: 日本語
Expose custom control to UXML and UI Builder
要素管理のベストプラクティス

UXML のタグ名と属性のカスタマイズ

UXML のタグ名をカスタマイズしたり、基本クラス属性のデフォルト値をオーバーライドしたり、カスタムコントロールに使用できる属性を制限したりすることができます。

UXML のタグ名のカスタマイズ

デフォルトでは、カスタムコントロールの UXML のタグ名は C# のクラス名です。タグに C# のクラス名と異なる名前を付けることは推奨されません。ただし、名前の競合がある場合は、タグ名をカスタマイズすることも可能です。

UXML のタグ名をカスタマイズするには、IUxmlFactory.uxmlName プロパティと IUXmlFactory.uxmlQualifiedName プロパティをオーバーライドします。以下に注意してください。

  • uxmlName は名前空間内で一意である必要があります。
  • uxmlQualifiedName はプロジェクト内で一意である必要があります。

両方の名前が一意でない場合、Unity が、アセンブリのロード時に例外をスローします。

以下のサンプルコードは、UXML 名をオーバーライドしてカスタマイズします。

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

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

要素の factory の選択

デフォルトでは、IUxmlFactory は、要素をインスタンス化し、要素の名前によって要素を選択します。要素の属性値を考慮して選択するには、IUXmlFactory.AcceptsAttributeBag() をオーバーライドします。factory は、要素の属性を調査して、その UXML 要素のオブジェクトをインスタンス化できるかどうかを決定します。

VisualElement クラスがジェネリックである場合、factory で要素の属性を調査すると場合によって役立ちます。この場合、クラスの特殊化のためのクラス factory は、UXML type 属性の値を調査できます。値によって、インスタンス化が許可または拒否されます。

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

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

基本クラスで宣言された属性のデフォルト値を変更するには、派生クラスの UxmlTraits クラス内に defaultValue を設定します。

以下のサンプルコードは、m_TabIndex のデフォルト値を変更します。

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

使用できる属性の制限

デフォルトでは、生成された UXML スキーマは、要素がどのような属性でも持つことができると記述します。これは、宣言された属性の値がその宣言と一致しているかどうかをチェックする XML バリデーターとは対照的です。

IUxmlAttributes のバッグには、IUxmlFactory.AcceptsAttributeBag() 関数と IUxmlFactory.Init() 関数に渡される追加の属性が含まれています。ファクトリの実装は、これらの追加属性を使用するかどうか決定します。デフォルトの動作は、追加属性を破棄することです。これらの追加属性は、インスタンス化されたVisualElement にアタッチされず、UQuery でクエリできません。

新しい要素を定義する際に、使用できる属性を IUxmlAttributes バッグで明示的に宣言されたものに限定するには、UxmlTraits コンストラクター内で UxmlTraits.canHaveAnyAttribute プロパティを false に設定します。

その他の参考資料

Expose custom control to UXML and UI Builder
要素管理のベストプラクティス