Version: 2023.2
言語: 日本語
UQuery でビジュアル要素を検索する
カスタムコントロール

C# スクリプトによる UI の構築

高度な技術を持つユーザーは、C# スクリプトで直接 UI のレイアウトを定義することができます。

USS ファイルでコントロールの見た目を定義したり、C# スクリプトでコントロールのスタイルプロパティを変更する ことができます。

コントロールはインタラクティブで、変更可能な値を表します。例えば、FloatField は float 値を表します。C# スクリプトの作成によって、コントロールの値を変更したり、コールバックを登録したり、データバインディングを適用したりすることが可能です。

C# スクリプトで UI にコントロールを追加する

UI 内でコントロールを使用するには、それを ビジュアルツリー に追加します。

以下の例は、既存のビジュアルツリーに Button コントロールを追加します。

var newButton = new Button("Click me!");
rootVisualElement.Add(newButton);

UI 階層にコントロールを追加する時には、レイアウトエンジン が自動的にサイズと位置を処理します。また、ビジュアル要素のサイズと位置のオーバーライド も可能です。

コントロールの値の変更

コントロールの値にアクセスしたり、コントロールの値を変更するには、その value プロパティを使用します。

次の例は、Toggle コントロールと Button コントロールを作成します。ボタンをクリックするとトグルの値が反転します。

// トグルを作成してコールバックを登録
m_MyToggle = new Toggle("Test Toggle") { name = "My Toggle" };
rootVisualElement.Add(m_MyToggle);

// トグルの値を反転するボタンを作成
Button button01 = new Button() { text = "Toggle" };
button01.clicked += () =>
{
    m_MyToggle.value = !m_MyToggle.value;
};
rootVisualElement.Add(button01);

特定のコントロールのプロパティの詳細は、UI Toolkit のビルトインコントロールのリファレンス を参照してください。

コールバックの登録

value プロパティを持つコントロールは、値が変更されるとイベントを送信します。このイベントを受信するコールバックを登録することができます。

以下の例は、Toggle コントロールを作成し、コールバックを登録するものです。

// Create a toggle and register callback
m_MyToggle = new Toggle("Test Toggle") { name = "My Toggle" };
m_MyToggle.RegisterValueChangedCallback((evt) => { Debug.Log("Change Event received"); });
rootVisualElement.Add(m_MyToggle);

コールバックとイベントの詳細は、イベントの処理 を参照してください。

データバインディングの適用

コントロールはオブジェクトやシリアル化されたプロパティにバインドできます。例えば、FloatField コントロールを MonoBehaviour に属するパブリック float 変数にバインドすることができます。コントロールがプロパティにバインドされると、自動的にプロパティの値が表示されます。コントロールに変更を加えると、プロパティの値が更新されます。

同様に、コード経由でプロパティの値が変更されると、UI に更新された値が表示されます。この双方向の繋がりは、カスタムの Inspector ウィンドウを作成する場合に便利です。

データバインディングに関する詳細は、SerializedObject のデータバインディング を参照してください。

全てのコントロールがバインド可能というわけではありません。ビルトインコントロールの一覧と、バインディングのサポートの有無については、UI Toolkit ビルトインコントロールのリファレンス を参照してください。

Access properties of a control’s read-only children

Some controls have read-only child elements. For example, a ListView control has a ScrollView child. You can use UQuery to access the child’s properties and override their values.

The following example changes the scroll speed of a ListView control by overriding the mouseWheelScrollSize property of the ScrollView child:

var scrollView = listView.Q<ScrollView>();
scrollView.mouseWheelScrollSize = 55;

コントロールの状態の管理

コントロールには各種の状態があり、これを C# スクリプトで管理できます。例えば、コントロールを有効にしたり無効にしたりできます。

以下の例は、Toggle コントロールと Button コントロールを作成します。ボタンをクリックするとトグルが無効になります。

// Create a toggle.
Toggle myToggle = new Toggle("A Toggle");

// Create a button to disable the toggle.
Button button01 = new Button();
button01.text = "Button01";
button01.RegisterCallback<ClickEvent>(evt =>
{
    myToggle.SetEnabled(false);
});

擬似クラス を使用して、USS で状態が変化した時の視覚的なフィードバックの変化を実装することもできます。例えば、トグルを無効にするには、以下のように、disabled 擬似状態を持つセレクターを使用します。

.unity-button:disabled
{
    background-color: #000000;
}

その他の参考資料

UQuery でビジュアル要素を検索する
カスタムコントロール