UXML 元素 Button

使用 Button 元素在 UI(用户界面) 允许用户与您的应用程序交互。Unity 目前支持三种 UI 系统。 更多信息
在 术语表 中查看 中创建可点击的按钮。例如，当用户点击 Button 元素时，会触发一个动作或事件，例如打开新窗口、提交表单或播放声音效果。

创建 Button

您可以使用 UI Builder、UXML 或 C# 创建 Button。以下 C# 示例创建了一个带有标签的 Button

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

向 Button 添加图标

您可以通过添加图标来增强 Button 的视觉效果，例如 Texture、Render Texture一种特殊的 Texture 类型，它在运行时创建和更新。要使用它们，首先创建一个新的 Render Texture，并指定您的摄像机之一渲染到其中。然后，您可以像使用普通 Texture 一样在材质中使用 Render Texture。 更多信息
在 术语表 中查看、Sprite二维图形对象。如果您习惯于使用 3D，则 Sprite 本质上只是标准纹理，但有一些特殊技术可以组合和管理精灵纹理，以提高开发过程中的效率和便利性。 更多信息
在 术语表 中查看 或项目中存在的矢量图像资产。有关如何引用图像资产的信息，请参阅 资产任何可用于游戏或项目的媒体或数据。资产可能来自在 Unity 之外创建的文件，例如 3D 模型、音频文件或图像。您也可以在 Unity 中创建某些资产类型，例如动画控制器、音频混合器或渲染纹理。 更多信息
在 术语表 中查看。

要使用 UI Builder 添加 Button 的图标

• 在 Button 的 InspectorUnity 窗口，显示有关当前选定 GameObject、资产或项目设置的信息，允许您检查和编辑值。 更多信息
  在 术语表 中查看 选项卡中，从 Icon Image 下拉列表中选择所需的图标。
• 或者，将图标从 Assets 窗口拖放到 Button 的 Inspector 选项卡中的 Icon Image 字段。

要使用 UXML 添加 Button 的图标，请将图像源提供给 icon-image 属性

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

要使用 C# 添加 Button 的图标，请将图像源分配给 iconImage 属性

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

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

更改 Button 图标位置

当您向 Button 添加图标时，它会向 Button 添加两个 只读 子元素

• 一个 Image 元素用于定义图标图像。
• 一个 TextElement 元素用于定义按钮文本。

您无法编辑子元素，但可以使用 Button 元素的 USS flex-direction 属性更改其布局。默认情况下，图标添加到按钮文本的左侧。

要重新定位按钮图标，请使用以下方法调整 Button 的 flex-direction

• 要将图标移到按钮文本的右侧，请将其设置为 row-reverse。
• 要将图标移到按钮文本的上方，请将其设置为 column。
• 要将图标放置在按钮文本下方，请将其设置为 column-reverse。

使用 Button 的子元素

Button 元素允许您使用 text、iconImage 属性和 background-image 样式属性向用户提供更多信息。与任何 视觉元素视觉树的节点，它实例化或派生自 C# VisualElement 类。您可以设置外观、定义行为，并将其显示在屏幕上，作为 UI 的一部分。 更多信息
在 术语表 中查看 一样，您也可以在 Button 的层次结构中添加子元素，例如 Label 或 Image，以便向用户提供更多信息，如果您希望对这些元素的外观和行为进行更细粒度的控制。

通常，在以下情况下使用子元素

• 自定义：使用子元素允许您分别自定义每个元素的外观和行为。例如，您可能希望对标签文本使用自定义字体或颜色，或向图像添加特定动画。当您向 Button 添加 Image 元素时，可以从您的 场景场景包含游戏环境和菜单。将每个唯一的场景文件视为一个唯一的关卡。在每个场景中，您放置您的环境、障碍物和装饰，本质上是按部分设计和构建您的游戏。 更多信息
  在 术语表 中查看 中直接添加该元素。此外，Image 元素还支持缩放模式和重复模式。
• 动态内容：如果标签或图像的内容是动态的，使用子元素允许您分别更新每个元素的内容，而不会影响按钮的其他属性。
• 交互：如果您希望向按钮中的特定元素添加交互性，例如允许用户仅单击标签（忽略对按钮其他元素的点击）以触发操作，使用子元素就可以实现这一点。

将属性用于以下目的

• 简单设计：如果按钮的设计很简单，不需要自定义或动态内容，建议使用属性。
• 性能：如果您的 UI 中有许多按钮，对每个按钮使用子元素可能会对性能产生负面影响。在这种情况下，使用属性来设置按钮的外观效率更高。
• 一致性：如果您希望在整个 UI 中保持一致性，使用属性可以确保所有按钮具有相同的外观和行为。

示例

以下 UXML 示例创建了一个 Button

<UXML xmlns="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements">
    <Button text="UXML Button" name="the-uxml-button" />
</UXML>

以下 C# 示例说明了 Button 的一些可自定义功能

/// <sample>
// Action to perform when button is pressed.
// Toggles the text on all buttons in 'container'.
Action action = () =>
{
    container.Query<Button>().ForEach((button) =>
    {
        button.text = button.text.EndsWith("Button") ? "Button (Clicked)" : "Button";
    });
};

// Get a reference to the Button from UXML and assign it its action.
var uxmlButton = container.Q<Button>("the-uxml-button");
uxmlButton.RegisterCallback<MouseUpEvent>((evt) => action());

// Create a new Button with an action and give it a style class.
var csharpButton = new Button(action) { text = "C# Button" };
csharpButton.AddToClassList("some-styled-button");
container.Add(csharpButton);
/// </sample>

要实时在 Unity 中尝试此示例，请转到 窗口 > UI 工具包 > 示例。

C# 基类和命名空间

C# 类：Button
命名空间：UnityEngine.UIElements
基类：TextElement

成员 UXML 属性

此元素具有以下成员属性

继承的 UXML 属性

此元素从其基类继承以下属性

此元素还从 VisualElement 继承以下属性

USS 类

下表列出了所有 C# 公共属性名称及其相关的 USS 选择器。

您还可以使用 检查器或 UI 工具包调试器中的匹配选择器部分 查看哪些 USS 选择器会影响 VisualElement 各级层次结构中的组件。

其他资源

• UXML 元素 Image
• UXML 元素 TextElement
• UXML 元素 ToggleButtonGroup