Перейти к основному содержимому

VisualElement Extensions

Интерфейс UI Toolkit одной цепочкой вызовов — без отдельной строки на каждое свойство и стиль.

Быстрый старт​

До — Unity APIПосле — FastTools
var title = new Label("Ability Config");
title.style.fontSize = 14;

var header = new VisualElement();
header.style.paddingLeft = 12;
header.style.paddingRight = 12;
header.style.paddingTop = 10;
header.style.paddingBottom = 10;
header.Add(title);
var header = new VisualElement()
.SetPaddingX(12)
.SetPaddingY(10)
.AddChild(new Label("Ability Config")
.SetFontSize(14));

Методы настройки возвращают исходный элемент, сохраняя его тип. Все расширения, кроме расширений редактора, работают также в сборке плеера.

Свойства элемента​

UnityFastTools
tooltip = "Mana cost"SetTooltip("Mana cost")
isDelayed = trueSetDelayed(true)
bindItem = BindRowSetBindItem(BindRow)
text = "Ability Config"SetTextSelf("Ability Config")
SetEnabled(false)SetEnabledSelf(false)

Суффикс Self стоит у имён, которые Unity использует (или может начать использовать) для метода, возвращающего void. Такой метод имеет приоритет над расширением, поэтому цепочка через него не соберётся; метод FastTools возвращает элемент.

В Unity 6000.6 и новее у SetTextSelf больше перегрузок. Они задают текст через TextElement.SetText из Unity, который не выделяет память, поэтому тексту, меняющемуся каждый кадр, не нужен ToString():

fps.SetTextSelf(frameCount); // int, long или ulong
speed.SetTextSelf(velocity, "0.0"); // float с необязательным форматом
title.SetTextSelf(characters); // ReadOnlySpan<char>
log.SetTextSelf(builder); // StringBuilder
log.SetTextSelf(buffer, start, length); // фрагмент char[]

Пока элемент не подключён к панели, они задают строку: она выделяет память, а Unity не пишет предупреждение. Голый null в 6000.6 не компилируется; приведите его: SetTextSelf((string)null).

Полный список расширений — в справочнике API.

примечание

VisualElementExtensions и INotifyValueChangedExtensions называются так же, как классы UnityEngine.UIElements. На вызовы расширений это не влияет; вызов через имя класса требует namespace: Aspid.FastTools.UIElements.VisualElementExtensions.SetName(title, "Title").

Дочерние элементы​

UnityFastTools
Add(title)AddChild(title)
Insert(0, title)InsertChild(0, title)
Remove(title)RemoveChild(title)
RemoveAt(0)RemoveChildAt(0)
Clear()ClearChildren()

Методы возвращают родителя. Для нескольких элементов есть AddChildren, InsertChildren, RemoveChildren.

До — Unity APIПосле — FastTools
if (isFree)
body.Add(helpBox);
body.AddChildIf(isFree, helpBox);

У всех этих методов есть вариант с суффиксом If.

Стили​

все стороны

Остальные методы стилей работают по схожему принципу. Полный список — в справочнике API.

Цвет из строки и ассеты из Resources​

До — Unity APIПосле — FastTools
if (ColorUtility.TryParseHtmlString(
"#FFC24D", out var color))
badge.style.color = color;
badge.SetColor("#FFC24D");
var texture = Resources
.Load<Texture2D>("UI/Card");
if (texture != null)
root.style.backgroundImage = texture;
root.SetBackgroundImageFromResources(
"UI/Card");

Вариант …FromResources есть также у SetImage, SetSprite, SetVectorImage и у методов таблиц стилей.

SetBackgroundImage принимает также Sprite или VectorImage: icon.SetBackgroundImage(sprite). Чтобы убрать фон, передайте StyleKeyword.None: голый null не компилируется.

Жирный и курсив​

Добавление и удаление одного начертания сохраняет второе.

ВызовДействие
AddBoldUnityFontStyleAndWeight()Добавляет жирный
RemoveBoldUnityFontStyleAndWeight()Убирает жирный
AddItalicUnityFontStyleAndWeight()Добавляет курсив
RemoveItalicUnityFontStyleAndWeight()Убирает курсив
SetNormalUnityFontStyleAndWeight()Убирает оба начертания
примечание

Пресеты читают текущее значение из style элемента, а не итоговый стиль: начертание, заданное в USS, считается Normal.

Собственные свойства USS​

До — Unity APIПосле — FastTools
if (evt.customStyle.TryGetValue(
ThemeProperty, out var raw)
&& Enum.TryParse(raw,
ignoreCase: true,
out PreviewTheme theme))
ApplyTheme(theme);
if (evt.customStyle.TryGetByEnum(
ThemeProperty,
out PreviewTheme theme))
ApplyTheme(theme);

USS-классы и таблицы стилей​

UnityFastTools
AddToClassList("selected")AddClass("selected")
RemoveFromClassList("selected")RemoveClass("selected")
ToggleInClassList("selected")ToggleClass("selected")
EnableInClassList("selected", isFree)EnableClass("selected", isFree)
ClearClassList()ClearClasses()
styleSheets.Add(sheet)AddStyleSheet(sheet)
styleSheets.Insert(0, sheet)InsertStyleSheet(0, sheet)
styleSheets.Remove(sheet)RemoveStyleSheet(sheet)
styleSheets.Clear()ClearStyleSheets()
  • Методы для нескольких классов или таблиц стилей называются во множественном числе: AddClasses("selected", "free"), AddStyleSheets(baseSheet, themeSheet).
  • EnableClasses принимает флаг первым: EnableClasses(isFree, "selected", "free").
  • EnableStyleSheet(darkSheet, isDark) добавляет или убирает таблицу стилей, как EnableClass — класс.

У всех этих методов есть вариант с суффиксом If. Когда у метода два флага, называйте аргументы: EnableClassIf(condition: isEditable, "selected", enable: isFree).

Значения и события​

UnityFastTools
value = 10SetValue(10)
SetValueWithoutNotify(10)SetValue(10, notify: false)
RegisterValueChangedCallback(OnChanged)AddValueChanged(OnChanged)
UnregisterValueChangedCallback(OnChanged)RemoveValueChanged(OnChanged)
clicked += RefreshAddClicked(Refresh)
clicked -= RefreshRemoveClicked(Refresh)

Для собственных типов значений доступны обобщённые SetValue<T, TValue>(…) и AddValueChanged<TField, TValue>(…).

Для типов Unity.Mathematics (float3, int2, quaternion) методам SetValue и AddValueChanged аргументы типа не нужны. Перегрузки лежат в отдельной сборке Aspid.FastTools.VisualElements.Math (справочник API), которая компилируется, когда установлен пакет com.unity.mathematics, а также в Unity 6000.5 и новее, где Unity.Mathematics входит в движок.

Методы Unity для обработчиков событий возвращают void, поэтому у их аналогов в FastTools суффикс Self:

UnityFastTools
RegisterCallback<ClickEvent>(OnClick)RegisterCallbackSelf<Button, ClickEvent>(OnClick)
RegisterCallbackOnce<ClickEvent>(OnClick)RegisterCallbackOnceSelf<Button, ClickEvent>(OnClick)
UnregisterCallback<ClickEvent>(OnClick)UnregisterCallbackSelf<Button, ClickEvent>(OnClick)

Эти методы принимают те же TrickleDown и пользовательские аргументы, что и методы Unity, и возвращают элемент, поэтому цепочка продолжается:

var apply = new Button()
.RegisterCallbackSelf((PointerEnterEvent evt) => Hover())
.SetTooltip("Apply");

Аргументы типа выводятся только из обработчика с типизированным параметром, как выше. Для группы методов или лямбды без типов параметров укажите оба: RegisterCallbackSelf<Button, ClickEvent>(OnClick).

Фокус​

UnityFastTools
Focus()FocusSelf()
Blur()BlurSelf()
До — Unity APIПосле — FastTools
if (manaCost.focusController?
.focusedElement == manaCost)
Refresh();
if (manaCost.IsFocused())
Refresh();
примечание

IsFocused() возвращает false для поля внутри другого поля (FloatField в Vector3Field) или в строке списка. Такое поле отслеживайте через FocusInEvent и FocusOutEvent.

Манипуляторы​

До — Unity APIПосле — FastTools
title.AddManipulator(
new Clickable(Refresh));
title.AddClickable(Refresh);

Для клавиатурной навигации и контекстного меню:

title.AddKeyboardNavigationManipulator(OnNavigate);
title.AddContextualMenuManipulator(BuildMenu);

Перегрузка с out позволяет сохранить манипулятор для удаления:

title.AddClickable(Refresh, out var clickable);

// Позже
title.RemoveManipulatorSelf(clickable);

Расширения редактора​

До — Unity APIПосле — FastTools
manaCost.bindingPath = "_manaCost";
manaCost.Bind(serializedObject);
manaCost.BindTo(
serializedObject, "_manaCost");
UnityFastTools
bindingPath = "_manaCost"SetBindingPath("_manaCost")
BindProperty(property)BindPropertyTo(property)
Unbind()UnbindFrom()

У PropertyField есть SetLabel и AddValueChanged / RemoveValueChanged с SerializedPropertyChangeEvent:

var manaCost = new PropertyField(
serializedObject.FindProperty("_manaCost"))
.SetLabel("Mana cost")
.AddValueChanged(_ => Refresh());

Открыть скрипт по двойному клику​

AddOpenScriptCommand открывает в IDE скрипт MonoBehaviour или ScriptableObject по двойному клику левой кнопкой; для других объектов ничего не добавляет:

title.AddOpenScriptCommand(target);

Окно элемента​

var window = title.GetOwnerWindow();

Возвращает окно элемента. Если оно не найдено — активное окно, затем окно под курсором; если нет ни одного — null.

Тема FastTools​

rootVisualElement
.AddAspidWindowTheme()
.AddStyleSheet(catalogSheet);

Окно получает цвета окон FastTools: тему из раздела Appearance в настройках FastTools, включая темы проекта, а на светлом скине редактора — светлую палитру. Новый выбор темы перекрашивает окно сразу. Свой стиль раскрашивайте токенами --aspid-colors-*:

.ability-sidebar {
background-color: var(--aspid-colors-surface-card);
}

Пример в пакете​

Окно каталога в примере EditorTools собрано на этих расширениях.

Окно Ability Catalog из примера EditorToolsОкно Ability Catalog из примера EditorTools