優れたカスタムコントロールは抽象的で、自己完結型で、繰り返し使用できます。
スライドトグル は、カスタムコントロールの良い例です。
アプリケーションのメニューバーは、カスタムコントロールの良い例ではありません。
カスタムコントロールを作成したら、USS でスタイルを設定し、C# でイベントを処理するロジックを追加できます。
以下の手順でカスタムコントロールを作成します。
UxmlElement 属性を追加します 。VisualElement またはその派生クラスから継承します。例:
using UnityEngine;
using UnityEngine.UIElements;
[UxmlElement]
public partial class ExampleElement : VisualElement {}
作成したカスタムコントロールは UXML と UI Builder で使用できます。
以下の UXML ドキュメントの例では、カスタムコントロールを使用します。
<ui:UXML xmlns:ui="UnityEngine.UIElements">
<ExampleElement />
</ui:UXML>
デフォルトでは、カスタムコントロールは UI Builder の Library タブに表示されます。Library タブで非表示にする場合は、HideInInspector 属性を追加します。
カスタムコントロールは VisualElement から継承します。VisualElement は、ゲームオブジェクトの生存期間にバインドされず、以下のコールバックも受信しません。
Awake()OnEnable()OnDisable()OnDestroy()カスタムコントロールは、そのコンストラクターで初期化できます。ただし、アプリケーションで必要な場合は、カスタムコントロールが UI に追加されるまで、初期化を延期できます。それには、AttachToPanelEvent のコールバックを登録します。カスタムコントロールが UI から削除されたことを検出するには、DetachFromPanelEvent コールバックを使用します。
public CustomControl()
{
var myCustomElement = rootVisualElement.Q(className: "my-custom-element");
myCustomElement.RegisterCallback<AttachToPanelEvent>(e =>
{ /* do something here when element is added to UI */ });
myCustomElement.RegisterCallback<DetachFromPanelEvent>(e =>
{ /* do something here when element is removed from UI */ });
}
UI Toolkit はこれら 2 つのイベントをすべての要素にディスパッチします。カスタム VisualElement サブクラスは必要ありません。詳細は、パネルイベント を参照してください。
USS を使用して、ビルトインコントロールと同じ方法でカスタムコントロールの外観をカスタマイズできます。USS カスタムプロパティ を作成して、カスタムコントロールのスタイルを設定することもできます。
ノート: UI Builder の Inspector ウィンドウに USS カスタムプロパティは表示されません。USS カスタムプロパティを編集するには、テキストエディターを使用するか、USS ファイルを直接編集します。
C# でカスタムコントロールのカスタム USS プロパティを操作するには、CustomStyleProperty 構造体と CustomStylesResolvedEvent イベントを使用します。
CustomStyleProperty は、スタイルシートから読み取るプロパティの名前と型を示します。
UI Toolkit は、カスタム USS プロパティを直接受け取るすべての要素に CustomStylesResolvedEvent をディスパッチします。ルールにカスタムプロパティの値が含まれているセレクターで一致した要素のイベントをディスパッチします。UI Toolkit は、値を継承する要素にイベントをディスパッチしません。イベントは、ICustomStyle オブジェクトへのリファレンスを保持します。CustomStyleProperty の有効値を読み取るには、その TryGetValue() メソッドを使用する必要があります。このメソッドには、さまざまなタイプの CustomStyleProperty のオーバーロードがあります。
カスタムコントロールのカスタムスタイルの例については、カスタムコントロールのカスタムスタイルを作成する を参照してください。
ノート: カスタムスタイルプロパティの遷移は定義できません。
カスタムコントロールのイベント処理方法について、詳しくは イベントの処理 を参照してください。
ノート:
focus に関するプロパティを設定します 。カスタムコントロールが表すプロパティとその動作の他の機能面を UXML プロパティとして公開し、カスタムコントロールの外観に影響するプロパティを USS プロパティとして公開します。
短くて読みやすい一意の名前空間を使用して、他の要素との名前の衝突を避けます。
UXML 属性をプリミティブに保ちます。UXML で指定できるデータは、プリミティブなデータ型に制限されます。UXML は複雑なデータ構造体やコレクションをサポートしません。ランタイムに複雑なデータをカスタムコントロールに渡すには、UXML ではなく C# スクリプトまたはデータバインディングを使用します。
C# で USS クラスまたは名前を定数として公開します。これにより、UQuery を使用して、クラスまたは名前で要素を検索できます。
USS クラスに BEM スタンダード を適用します。これにより、クラスリストセレクターを使用してすべての要素に対応できます。
静的コールバックを使用して、メモリフットプリントを削減します。コールバックバックとして使用するインスタンスメソッドを登録すると、不要な割り当てが発生する場合があります。割り当てを回避するには、通常の C# 静的メソッドを呼び出す匿名の静的ラムダ関数を使用します。現在の要素のコンテキストは、EventBase.currentTarget プロパティを使用して取得できます。
カスタムコントロールの generateVisualContent コールバックを使用して、カスタムジオメトリをレンダリングします。部分的に塗りつぶした円をレンダリングする使用例については、RadialProgress の例 を参照してください。
カスタムコントロールは便利です。ただし、以下の方法でも同じ結果が得られる可能性があります。
MonoBehaviour を使用して、UI を保持する特定の UI Document に関連するロジックを追加します。(MonoBehaviour を使用して UI Document の UI を制御する方法については、リストビューのランタイム UI の作成 を参照してください。)カプセル化を実現するには、UQuery を使用して内部で VisualElement を取得しそれらのプロパティを操作するプロパティとメソッドを MonoBehaviour 内に作成します。