在 C# 脚本中创建运行时绑定

绑定视觉元素实例化或派生自 C# 的可视化树的节点VisualElement类。您可以设置外观样式、定义行为并将其作为 UI 的一部分显示在屏幕上。更多信息
请参阅术语表到 C# 中的数据源，创建DataBinding.使用此绑定类型，您可以定义dataSource和dataSourcePath直接在绑定实例上。

基本工作流程

若要在 C# 中创建运行时绑定，请执行以下步骤：

创建绑定。绑定是可以通过唯一 ID 创建、注册或取消注册到视觉元素的对象。
定义绑定对象的数据源和数据源路径。数据源是包含要绑定到的属性的对象。数据源路径是从数据源到要绑定到的属性的相对路径。
定义绑定对象的绑定模式和更新触发器。绑定模式定义如何在数据源和 UI 之间复制更改。更新触发器定义何时更新绑定对象。
将绑定对象注册到视觉元素。
如有必要，添加类型转换器以在数据源和 UI 之间转换数据类型。

以下示例创建了一个绑定对象，并将其注册到视觉元素。

var dataSource = ScriptableObject.CreateInstance<ExampleObject>();

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

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

vector3Field.SetBinding("label", new DataBinding
{
    dataSourcePath = new PropertyPath(nameof(ExampleObject.vector3Label)),
    bindingMode = BindingMode.ToTarget
});

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

root.Add(vector3Field);

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

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

root.Add(floatField);

var label = new Label("Label")
{
    dataSourcePath = new PropertyPath(nameof(ExampleObject.dangerLevel))
};

// Here, we do not need to set the dataSourcePath because we will only use two bindings and they will use the same path,
// so we set the dataSourcePath on the Label directly instead.
var binding = new DataBinding
{
    bindingMode = BindingMode.ToTarget
};

// Add a custom float -> string converter
binding.sourceToUiConverters.AddConverter((ref float v) => 
{
    return v switch
    {
        >= 0 and < 1.0f/3.0f => "Danger",
        >= 1.0f/3.0f and < 2.0f/3.0f => "Neutral",
        _ => "Good"
    };
});

// Add a custom float -> StyleColor
binding.sourceToUiConverters.AddConverter((ref float v) => new StyleColor(Color.Lerp(Color.red, Color.green, v)));

// Since the binding is targeting the same data source property, we can reuse the same instance.
label.SetBinding("text", binding);
label.SetBinding("style.backgroundColor", binding);

root.Add(label);

它相当于以下 UXML：

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance" engine="UnityEngine.UIElements" 
editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
    <ui:VisualElement data-source="ExampleObject.asset" name="VisualElement" >
        <ui:Vector3Field label="Vec3 Field">
            <Bindings>
                <ui:DataBinding property="label" data-source-path="vector3Label" binding-mode="ToSource" />
                <ui:DataBinding property="value" data-source-path="vector3Value" />
            </Bindings>
        </ui:Vector3Field>
        <ui:FloatField label="Float Field" value="42.2">
            <Bindings>
                <ui:DataBinding property="value" data-source-path="sumOfVector3Properties" binding-mode="ToTarget" />
            </Bindings>
        </ui:FloatField>
        <ui:Label text="Label" data-source-path="dangerLevel">
            <Bindings>
                <ui:DataBinding property="text" binding-mode="ToTarget" source-to-ui-converters="Value To Progress" />
                <ui:DataBinding property="style.backgroundColor" binding-mode="ToTarget" source-to-ui-converters="Value To Progress" />
            </Bindings>
    </ui:Label>
    </ui:VisualElement>
</ui:UXML>

注册和注销绑定对象

可以使用以下方法来管理绑定对象：

报告更改

您可以像其他数据源一样创建可绑定属性，这意味着您还可以使用VisualElement类型作为数据源。之间的主要区别VisualElementtype 和其他数据源是VisualElement类型带有内置版本控制。您必须使用VisualElement类型以传播更改。

要报告更改，请调用NotifyPropertyChanged方法。此方法采用BindingId标识更改的属性。

以下示例演示如何报告VisualElement类型：

// Creates a static readonly BindingId that is unique to this type. This is used to identify the property. 
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);
    }
}

最佳做法

请遵循以下提示和最佳实践来优化性能：

使用正确的绑定 ID：绑定系统使用绑定 ID 来标识元素的绑定对象和目标属性。绑定 ID 必须是元素的目标属性。例如，如果要绑定到value属性Vector3Field，绑定 ID 必须是Vector3Field.valueProperty.
避免使用绑定更新内部数据：不要使用绑定来更新视觉元素的内部数据。例如，不要使用绑定来同步x,y和z子元素Vector3Field.相反，请使用绑定来同步value属性的Vector3Field使用Vector3数据源的属性。

已知限制

UI 工具包不报告element.style和element.resolvedStyle.因此，可以使用绑定实例来定位元素的已解析样式，但无法跟踪对它们的更改。

其他资源

运行时绑定入门

定义运行时绑定的数据源