← Руководство

Кнопка

Используйте элемент Button для создания клавиатурных кнопок в UI. Например, когда пользователь нажимает или нажимает на элемент Button, он запускает действие или событие, такое как открытие нового окна, отправка формы или воспроизведение звукового эффекта.

Создать кнопку

Вы можете создать Кнопку с помощью UI Builder, UXML или C#. Следующий пример C# создает Кнопку с меткой:

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

Добавить значок к кнопке

Вы можете улучшить визуальную привлекательность своей Button, включив в нее значок, например, текстуру, текстуру отображения, спрайт или векторное изображение, которое существует в вашем проекте. Информацию о том, как ссылаться на изображение, см. в Активы.

Чтобы добавить значок для кнопки с UI Builder:

На вкладке Inspector кнопки выберите желаемый значок из раскрывающегося списка Icon Image.
Или перетащите значок из окна Assets в поле Icon Image, расположенное на вкладке Inspector кнопки.

Чтобы добавить значок для Кнопки с UXML, укажите источник изображения для атрибута icon-image:

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

Чтобы добавить значок для Кнопки с C#, назначьте источник изображения свойству iconImage:

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

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

Изменение положения значка кнопки

Когда вы добавляете иконку к Кнопке, она добавляет два только для чтения суб-элемента к Кнопке:

Элемент Изображение для определения изображения значка.
TextElement для определения текста кнопки.

Вы не можете редактировать субэлементы, но вы можете изменить их расположение, используя свойство USS flex-direction элемента Button. По умолчанию значок добавляется слева от текста кнопки.

Чтобы изменить положение значка кнопки, измените значок flex-direction кнопки следующим образом:

Чтобы переместить значок справа от текста кнопки, установите его на row-reverse.
Чтобы переместить значок над текстом кнопки, установите его на column.
Чтобы разместить значок под текстом кнопки, установите его на column-reverse.

Использование подэлементов Кнопки

Элемент Button позволяет предоставлять дополнительную информацию пользователю с помощью свойств text, iconImage и свойства стиля background-image. Как и в случае с любым визуальным элементом, вы также можете добавить субэлементы в иерархию Button, такие как Label или Image, чтобы предоставить дополнительную информацию пользователю, если вы хотите иметь более тонкий контроль над внешним видом и поведением этих элементов.

Как правило, подэлементы используются в следующих ситуациях:

Настройка: Использование суб-элементов позволяет вам настроить внешний вид и поведение каждого отдельного элемента отдельно. Например, вы можете использовать пользовательский шрифт или цвет для текста метки или добавить определенную анимацию к изображению. Когда вы добавляете элемент Image в Button, вы можете добавить элемент из вашей сцены напрямую. Кроме того, элемент Image также поддерживает режим масштабирования и режим повторения.
Динамическое содержимое: Если содержимое метки или изображения является динамичным, использование подэлементов позволяет обновлять содержимое каждого элемента отдельно, не влияя на другие свойства кнопки.
Взаимодействие: Если вы хотите добавить интерактивность к определенному элементу в кнопке, например, разрешить пользователю щелкнуть только метку (не считая щелчков по другим элементам кнопки) для запуска действия, использование суб-элементов делает это возможным.

Используйте свойства для следующих целей:

Простые дизайны: Если дизайн кнопки прост и не требует настройки или динамического контента, рекомендуется использовать свойства.
Производительность: Если у вас много кнопок в вашем UI, использование суб-элементов для каждой из них может негативно повлиять на производительность. В этом случае более эффективно использовать свойства для установки внешнего вида кнопки.
Последовательность: Если вы хотите поддерживать последовательность в вашем UI, использование свойств может обеспечить, чтобы все кнопки имели последовательный внешний вид и поведение.

Примеры

Следующий пример UXML создает Кнопку:

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

Следующий пример USS стилизует Кнопку:

.some-styled-button {
    -unity-font-style: bold;
}

Следующий пример C# иллюстрирует некоторые из настраиваемых функций Кнопки:

// 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);

Чтобы попробовать этот пример в Unity, перейдите в Окно > UI Toolkit > Образцы.

Базовый класс C# и пространство имён

C# класс: Button
Пространство имен: UnityEngine.UIElements
Базовый класс: TextElement

Атрибуты члена UXML

Этот элемент имеет следующие атрибуты члена:

Имя	Тип	Описание
`icon-image`	`Object`	Текстура, Sprite или VectorImage, которые будут представлять значок в элементе Button.
`text`	`string`	текст

Унаследованные атрибуты UXML

Этот элемент наследует от своего базового класса следующие атрибуты:

Имя	Тип	Описание
`binding-path`	`string`	Путь к целевому свойству для привязки.
`display-tooltip-when-elided`	`boolean`	Если true, то tooltip отображает полную версию элидируемого текста, а также, если tooltip был ранее предоставлен, он будет перезаписан.
`double-click-selects-word`	`boolean`	Управляет тем, выбирает ли двойной щелчок слово под указателем мыши.
`emoji-fallback-support`	`boolean`	Указывает порядок, в котором система должна искать символы Emoji при отображении текста. Если этот параметр включен, поиск в глобальном резервном списке Emoji будет осуществляться сначала для символов, определенных как Emoji в стандарте Unicode 14.0.
`enable-rich-text`	`boolean`	Если установлено false, богатые текстовые теги не будут анализироваться.
`focusable`	`boolean`	Если false, то элемент не может быть фокусирован. Элемент может быть фокусирован только в том случае, если его свойство canGrabFocus имеет значение true.
`parse-escape-sequences`	`boolean`	Определяет, как будут отображаться последовательности спасения. При значении `true`последовательности спасения (такие как `\n`, `\t`) анализируются и преобразуются в соответствующие им символы. Например, '\n' вставляет новую строку. При значении `false`последовательности спасения отображаются как простой текст (например, `\n` отображается как символы '', за которыми следует 'n').
`selectable`	`boolean`	Возвращает true, если поле можно выбрать.
`tabindex`	`int`	Целое число, используемое для сортировки фокусируемых элементов в кольце фокуса. Должно быть больше или равно нулю. Установка значения `tabIndex` меньше `0` (например, `−1`) удаляет элемент из кольца фокуса и навигации по вкладкам.
`text`	`string`	Текст для отображения. Изменение этого значения косвенно вызывает сеттер `INotifyValueChanged_1.value`, который поднимает `ChangeEvent_1` типа строка.
`triple-click-selects-line`	`boolean`	Управляет тем, будет ли при трехкратном щелчке выбрана вся строка под указателем мыши.

Этот элемент также наследует следующие атрибуты от VisualElement:

Имя	Тип	Описание
`content-container`	`string`	Логический контейнер, в который добавляются дочерние элементы. Если к этому элементу добавляется дочерний элемент, то он добавляется в контейнер содержимого этого элемента. При итерации над `VisualElement.Children` При использовании элемента вместо самого элемента используется иерархия контейнера содержимого элемента. Это может привести к неожиданным результатам, например, к игнорированию элементов событиями навигации, если они не находятся непосредственно в иерархической структуре контейнера. См. `IFocusRing` для больше информации. Если контейнер содержимого совпадает с самим элементом, то дочерние элементы добавляются непосредственно к элементу. Это верно для большинства элементов, но может быть переопределено более сложными типами. `ScrollView`, например, имеет контейнер содержимого, отличающийся от самого себя. В этом случае дочерние элементы, добавленные к представлению прокрутки, добавляются вместо этого к его элементу контейнера содержа-`VisualElement.Hierarchy.parent`) дочерних элементов является элементом контейнера содержимого прокрутки, их логическим родителем (`VisualElement.parent`Поскольку некоторые фокусируемые дочерние объекты представления прокрутки не являются частью его логической иерархии, такие как его `Scroller` элементов, эти фокусируемые дочерние элементы не рассматриваются по умолчанию при использовании последовательной навигации. Как я могу изменить, какой элемент будет фокусироваться дальше для примера решения, если правила навигации по умолчанию не соответствуют вашим потребностям.
`data-source`	`Object`	Назначает источник данных этому VisualElement, который переопределяет любой унаследованный источник данных. Этот источник данных наследуется всеми дочерними объектами.
`data-source-path`	`string`	Путь от источника данных к значению.
`data-source-type`	`System.Type`	Возможный тип источника данных, присваиваемый этому VisualElement. Эта информация используется UI Builder только как подсказка для определенного заполнения поля пути источника данных, когда эффективный источник данных не может быть указан во время проектирования.
`enabled`	`boolean`	Возвращает true, если `VisualElement` разрешен локально. Этот флаг не изменяется, если VisualElement имплицитно отключен одним из родителей. Чтобы проверить это, используйте `enabledInHierarchy`.
`language-direction`	`UIElements.LanguageDirection`	Указывает направленность текста элемента. Значение будет распространяться на дочерей элемента. Установка `languageDirection` на `RTL` может получить только базовую поддержку RTL, такую как инверсия текста. Чтобы получить более полную поддержку RTL, такую как перерыв строки, перенос слов или формирование текста, вы должны включить Усовершенствованный текстовый генератор.
`name`	`string`	Имя этого VisualElement. Используйте это свойство для написания селекторов USS, которые нацелены на определенный элемент. Стандартная практика заключается в том, чтобы дать элементу уникальное имя.
`picking-mode`	`UIElements.PickingMode`	Определяет, может ли этот элемент быть целью событий указателя или выбран `IPanel.Pick` запросов. Элементы не могут быть выбраны, если: - Они невидимы. `style.display` установлен на `DisplayStyle.None` Элементы с режимом подбора `PickingMode.Ignore` никогда не получать псевдо-state.
`style`	`string`	Задает значения стиля на `VisualElement`. Возвращаемые данные стиля, рассчитанные из USS файлы или встроенные стили, записанные в этот объект в C#, не представляет полностью разрешенные стили, такие как окончательная высота и ширина VisualElement. Чтобы получить доступ к этим полностью разрешенным стилям, используйте `resolvedStyle`. Дополнительные сведения об использовании этого свойства и всех поддерживаемых USS свойства, см. Применить стили в C# сценарии и USS ссылка на свойства страницы руководства.
`tooltip`	`string`	Текст, который будет отображаться внутри информационного поля после того, как пользователь задержится над элементом небольшое время. Это поддерживается только в Редакторе UI.
`usage-hints`	`UIElements.UsageHints`	Комбинация значений подсказки, которые указывают высокоуровневые предполагаемые схемы использования для `VisualElement`. Это свойство может быть установлено только тогда, когда `VisualElement` еще не является частью `Panel`. Как только оно становится частью `Panel`, это свойство становится эффективно только для чтения, и попытки изменить его будут вызывать исключение. Указание правильного `UsageHints` заставляет систему принимать более правильные решения о том, как обрабатывать или ускорять определенные операции на основе предполагаемой схемы использования. Обратите внимание, что эти подсказки не влияют на поведение или визуальные результаты, а только влияют на общую производительность панели и элементов внутри нее. Рекомендуется всегда рассматривать возможность указания правильного `UsageHints`, но помните, что некоторые `UsageHints` могут быть внутренне проигнорированы при определенных условиях (e.g. из-за аппаратных ограничений на целевой платформе).
`view-data-key`	`string`	Используется для устойчивости данных представления, таких как развернутые состояния дерева, положение прокрутки или уровень масштаба. Этот ключ используется для сохранения и загрузки данных представления из хранилища данных представления. Если этот ключ не установлен, устойчивость отключена для связанного `VisualElement`. Дополнительные сведения см. в разделе Устойчивость данных представления в руководстве Unity.

Классы USS

В таблице ниже перечислены все открытые имена свойств C# и связанные с ними селекторы USS.

C# собственность	USS выбор	Описание
`ussClassName`	`.unity-button`	Имя USS-класса для элементов этого типа. Unity добавляет этот USS-класс к каждому экземпляру элемента Button. Любые стили, применённые к этому классу, влияют на все кнопки, расположенные рядом с таблицей стилей или ниже неё в визуальном дереве.
`iconUssClassName`	`.unity-button--with-icon`	Имя USS-класса для элементов Button со значком. Unity добавляет этот USS-класс к экземпляру элемента Button, если у этого экземпляра свойство `Button.iconImage` содержит допустимую Texture. Любые стили, применённые к этому классу, влияют на все кнопки со значком, расположенные рядом с таблицей стилей или ниже неё в визуальном дереве.
`iconOnlyUssClassName`	`.unity-button--with-icon-only`	Имя USS-класса для элементов Button только со значком, без текста. Unity добавляет этот USS-класс к экземпляру элемента Button, если у этого экземпляра свойство `Button.iconImage` содержит допустимую Texture и текст не задан. Любые стили, применённые к этому классу, влияют на все кнопки со значком, расположенные рядом с таблицей стилей или ниже неё в визуальном дереве.
`ussClassName`	`.unity-text-element`	Имя USS-класса для элементов этого типа.
`selectableUssClassName`	`.unity-text-element__selectable`	Имя USS-класса для выделяемых текстовых элементов.
`disabledUssClassName`	`.unity-disabled`	Имя USS-класса для локально отключённых элементов.

Вы также можете использовать раздел Соответствующие селекторы в отладчике Inspector или UI Toolkit, чтобы увидеть, какие селекторы USS влияют на компоненты VisualElement на каждом уровне его иерархии.