UXML 要素 Button

Button 要素を使用して、UI にクリック可能なボタンを作成します。例えば、ユーザーが Button 要素をクリックまたはタップすると、新しいウィンドウを開いたり、フォームを送信したり、サウンドエフェクトを再生したりといったアクションやイベントを発生させます。

Create a Button

You can create a Button with UI Builder, UXML, or C#. The following C# example creates a Button with a label:

var button = new Button(() => { Debug.Log("Button clicked"); }) { text = "Click me" };

Add an icon to a Button

You can enhance the visual appeal of your Button by incorporating an icon, such as a Texture, Render Texture, Sprite, or Vector image asset that exists in your project. For information on how to reference an image asset, refer to Assets.

To add an icon for a Button with UI Builder:

• From the Button’s Inspector tab, choose the desired icon from the Icon Image dropdown list.
• Alternatively, drag the icon from the Assets window to the Icon Image field located in the Button’s Inspector tab.

To add an icon for a Button with UXML, provide the image source to the icon-image attribute:

<ui:Button name="Button" text="Button text" icon-image="/path/to/image-file.png" />

To add an icon for a Button with C#, assign the image source to the iconImage property:

Button myButton = new Button();
var buttonIconImage = Resources.Load<Texture2D>("image-file");

myButton.text = "Button text";
myButton.iconImage = buttonIconImage;

Change the Button icon position

When you add an icon to a Button, it adds two read-only sub-elements to the Button:

• An Image element to define the icon image.
• A TextElement to define the button text.

You can’t edit the sub-elements but you can change their layout using the USS flex-direction property for the Button element. By default, the icon is added on the left of the button text.

To reposition the button icon, adjust the Button’s flex-direction with the following:

• To shift the icon to the right of the button text, set it to row-reverse.
• To move the icon above the button text, set it to column.
• To place the icon below the button text, set it to column-reverse.

ボタンのサブ要素を使用する

The Button element allows you to provide additional information to the user with the text, iconImage properties, and the background-image style property. As with any visual element, you can also add sub-elements in a Button’s hierarchy, such as a Label or Image, to provide additional information to the user if you want to have more fine-grained control over the appearance and behavior of those elements.

一般的には、以下のような場合にサブ要素を使用します。

• カスタマイズ: サブ要素を使用することで、個々の要素の外観や動作を個別にカスタマイズすることができます。例えば、ラベルテキストにカスタムフォントやカスタム色を使用したり、画像に特定のアニメーションを加えたりすることができます。Button に Image 要素を加えると、シーンから直接要素を加えることができます。さらに、Image 要素は、スケールモードとリピートモードもサポートします。
• 動的コンテンツ: ラベルや画像のコンテンツが動的な場合、サブ要素を使用することで、ボタンの他のプロパティに影響を与えることなく、各要素のコンテンツを個別に更新することができます。
• 相互作用: 例えば、ユーザーがラベルだけをクリックして (ボタンの他の要素のクリックを無視して) アクションを発生させることができるようにするなど、ボタン内の特定の要素に対話性を追加したい場合、サブ要素を使用することでこれが可能になります。

プロパティを以下の目的で使用します。

• シンプルなデザイン: ボタンのデザインがシンプルで、カスタマイズや動的なコンテンツを必要としない場合は、プロパティを使用することを推奨します。
• パフォーマンス: UI に多くのボタンがある場合、それぞれのボタンにサブ要素を使用するとパフォーマンスに悪影響を及ぼす可能性があります。この場合、プロパティを使用してボタンの外観を設定する方が効率的です。
• 一貫性: UI 全体の一貫性を維持したい場合、プロパティを使用すると、すべてのボタンに一貫した外観と動作を持たせることができます。

例

The following UXML example creates a Button:

[!code-xml[(External/Resources/editor_resources/Assets/Editor Default Resources/UIPackageResources/Snippets/UXML/ButtonSnippet.uxml)]

The following C# example illustrates some of the customizable functionalities of the Button:

[!code-cs[(Modules/UIElementsSamplesEditor/Snippets/ButtonSnippet.cs#sample)]

To try this example live in Unity, go to Window > UI Toolkit > Samples.

C# の基本クラスと名前空間

C#クラス: ボタン
名前空間: UnityEngine.UIElements
基本クラス: TextElement

メンバー UXML 属性

この要素は以下のメンバー属性を持ちます。

名前	型	説明
icon-image	Object	The Texture, Sprite, or VectorImage that will represent an icon within a Button element.

継承された UXML 属性

この要素は基本クラスから以下の属性を継承します。

名前	型	説明
binding-path	string	バインドされるべきターゲットプロパティのパス。
display-tooltip-when-elided	boolean	true の場合、ツールチップは省略されたテキストの完全なバージョンを表示し、以前にツールチップが提供されていた場合は、それをオーバーライドします。
emoji-fallback-support	boolean	Specifies the order in which the system should look for Emoji characters when rendering text. If this setting is enabled, the global Emoji Fallback list will be searched first for characters defined as Emoji in the Unicode 14.0 standard.
enable-rich-text	boolean	false の場合、リッチテキストタグは解析されません。
focusable	boolean	要素がフォーカス可能である場合は true。
parse-escape-sequences	boolean	Specifies whether escape sequences are displayed as is or if they are replaced by the character they represent.
tabindex	int	フォーカスリング内でフォーカス可能なものをソートするために使用される整数。0 以上であることが必要です。
text	string	The text to be displayed. Changing this value will implicitly invoke the INotifyValueChanged_1.value setter, which will raise a ChangeEvent_1 of type string.

この要素は、VisualElement から以下の属性も継承します。

名前	型	説明
content-container	string	子要素はそれに追加されますが、通常は要素自体と同じです。
data-source	Object	Assigns a data source to this VisualElement which overrides any inherited data source. This data source is inherited by all children.
data-source-path	string	Path from the data source to the value.
name	string	この VisualElement の名前。 このプロパティを使用して、特定の要素を対象とする USS セレクターを記述します。要素には一意の名前を付けるのが標準的です。
picking-mode	UIElements.PickingMode	mouseEvents または IPanel.Pick クエリの間にこの要素を選択 (ピック) できるかどうかを決定します。
style	string	この要素のスタイルオブジェクトへの参照。 C# でこのオブジェクトに書き込まれた USS ファイルまたはインラインスタイルから計算されたデータが含まれます。
toolbar	string	ユーザーが要素をマウスオーバーした後、わずかな時間、情報ボックス内に表示するテキスト。これはエディター UI でのみサポートされます。
usage-hints	UIElements.UsageHints	VisualElement の高レベルの使用パターンを指定するヒント値の組み合わせ。このプロパティは、VisualElement がまだ Panel の一部でない場合にのみ設定できます。Panel の一部になると、このプロパティは事実上読み取り専用となり、変更しようとすると例外がスローされます。適切な UsageHints を指定することで、予想される使用パターンに基づいて、特定の操作をどのように処理するか、または高速化するかについて、システムがより適切な判断を下すようになります。これらのヒントは動作や視覚的な結果には影響しませんが、パネルとその中の要素の全体的なパフォーマンスにのみ影響することに注意してください。常に適切なUsageHints を指定することを考慮することをお勧めしますが、特定の条件下 (例えば、ターゲットプラットフォームのハードウェア制限など) では、いくつかの UsageHints が内部的に無視される可能性があることに留意してください。
view-data-key	string	Used for view data persistence, such as tree expanded states, scroll position, or zoom level. This key is used to save and load the view data from the view data store. If you don’t set this key, the persistence is disabled for the associated VisualElement. For more information, refer to View data persistence.

USS クラス

以下の表は、すべての C# パブリックプロパティ名と、それに関連する USS セレクターのリストです。

C# プロパティ	USS セレクター	説明
ussClassName	.unity-button	この型の要素の USS クラス名。 Unity はこの USS クラスを Button 要素の全てのインスタンスに加えます。このクラスに適用されるスタイルは、ビジュアルツリーでスタイルシートの横または下に位置するすべてのボタンに影響します。
iconUssClassName	.unity-button--with-icon	The USS class name for Button elements with an icon. Unity adds this USS class to an instance of the Button element if the instance’s Button.iconImage property contains a valid Texture. Any styling applied to this class affects every button with an icon located beside, or below the stylesheet in the visual tree.
ussClassName	.unity-text-element	この型の要素の USS クラス名。
selectableUssClassName	.unity-text-element__selectable	USS class name of selectable text elements.
disabledUssClassName	.unity-disabled	ローカルで無効にされた要素の USS クラス名。

また、Inspector や UI Toolkit Debugger の Matching Selectors セクション を使用して、どの USS セレクターが VisualElementのコンポーネントに影響するかを、階層のすべてのレベルで確認することもできます。

その他の参考資料

• UXML 要素 Image
• UXML element TextElement
• UXML element ToggleButtonGroup