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

Создание привязки времени выполнения в скриптах C#

Чтобы привязать свойство визуального элемента к источнику данных в C#, создайте экземпляр DataBinding. С помощью этого типа привязки можно определить dataSource и dataSourcePath непосредственно в экземпляре привязки.

Основной рабочий процесс

Чтобы создать привязку времени выполнения в C#, выполните следующие действия:

Создание привязки. Привязки — это объекты, которые можно создавать, регистрировать или отменять регистрацию визуального элемента с помощью уникального ID.
Определяет источник данных и путь к источнику данных для объекта привязки. Источник данных — это объект, содержащий свойство, к которому требуется привязать. Путь к источнику данных — это относительный путь от источника данных к свойству, к которому требуется привязать.
Определяет режим привязки и триггеры обновления для объекта привязки. Режим привязки определяет, как изменения реплицируются между источником данных и объектом привязки. UI. Триггер обновления определяет, когда обновлять объект привязки.
Зарегистрировать объект привязки к визуальному элементу.
При необходимости добавьте конвертер типов для преобразования типов данных между источником данных и UI.

Предположим, что у вас есть объект источника данных с именем ExampleMultiPropertiesObject, который содержит свойство Vector3 с именем vector3Value и свойство float с именем sumOfVector3Properties, которое является суммой компонентов x, yи z свойства vector3Value. Дополнительные сведения об этом объекте источника данных см. в разделе Создание актива источника данных примера Привязка к нескольким свойствам с привязкой времени выполнения.

Затем можно создать объект привязки и зарегистрировать его в визуальном элементе следующим образом:

using Unity.Properties;
using UnityEngine;
using UnityEngine.UIElements;

public class RuntimeBindingExample
{
    public VisualElement CreateBindingExample()
    {
        var dataSource = ScriptableObject.CreateInstance<ExampleMultiPropertiesObject>();

        var root = new VisualElement
        {
            name = "root",
            dataSource = dataSource
        };

        var vector3Field = new Vector3Field("Vec3 Field");

        vector3Field.SetBinding("value", new DataBinding
        {
            dataSourcePath = new PropertyPath(nameof(ExampleMultiPropertiesObject.vector3Value))
        });

        root.Add(vector3Field);

        var floatField = new FloatField("Float Field") { value = 42.2f };

        floatField.SetBinding("value", new DataBinding
        {
            dataSourcePath = new PropertyPath(nameof(ExampleMultiPropertiesObject.sumOfVector3Properties))
        });

        root.Add(floatField);

        return root;
    }
}

Это эквивалентно следующему UXML:

<engine:UXML xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:engine="UnityEngine.UIElements" xmlns:editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
    <engine:VisualElement data-source="MulPropertyObject.asset" name="VisualElement" style="flex-grow: 1;">
        <engine:Vector3Field label="Vec3 Field">
            <Bindings>
                <engine:DataBinding property="value" data-source-path="vector3Value" binding-mode="ToSource"/>
            </Bindings>
        </engine:Vector3Field>
        <engine:FloatField label="Float Field" name="FloatField">
            <Bindings>
                <engine:DataBinding property="value" data-source-path="sumOfVector3Properties" binding-mode="ToTarget"/>
            </Bindings>
        </engine:FloatField>
    </engine:VisualElement>
</engine:UXML>

Регистрация и отмена регистрации объектов привязки

Для управления объектами привязки можно использовать следующие методы:

Сообщить об изменении

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

Чтобы сообщить об изменении, вызовите метод NotifyPropertyChanged. Этот метод принимает BindingId, которые идентифицируют изменившееся свойство. BindingId обычно является именем целевого свойства элемента UI.

В следующем примере показано, как сообщить об изменении типа VisualElement:

public static readonly BindingId intValueProperty = nameof(intValue);

private int m_IntValue;

[CreateProperty]
public int intValue
{
    get => m_IntValue;
    set
    {
        if (m_IntValue == value)
            return;
        m_IntValue = value;
        
        // This instructs the binding system that a change occured.
        NotifyPropertyChanged(intValueProperty);
    }
}

Передовая практика

Для оптимизации производительности следуйте этим советам и рекомендациям:

Использовать правильную привязку IDs: Система привязки использует привязку ID для идентификации объекта привязки и целевого свойства элемента. Привязка ID должна быть целевым свойством элемента. Например, если вы хотите привязать свойство value элемента Vector3Field, привязка ID должна быть Vector3Field.valueProperty или value. Короче говоря, привязка ID должна соответствовать имени или пути поля или свойства.
Избегайте обновления внутренних данных через привязки: не используйте привязки для обновления внутренних данных визуального элемента. Например, не применяйте привязки, чтобы синхронизировать x, y, и z подэлементов для Vector3Field. Вместо этого используйте привязку для синхронизации value свойства Vector3Field с Vector3 свойство источника данных.

Известные ограничения

UI Toolkit не сообщает об изменениях в element.style и element.resolvedStyle. Поэтому вы можете использовать экземпляры привязки для нацеливания на разрешенный стиль элемента, но не можете отслеживать изменения в них.