绑定 — D.A. Documentation

ULB 绑定会轮询组件中可读取的字段或属性，并将值写入受支持且已链接的 UI Toolkit 元素。

3.0.1 中的绑定为单向：从组件到 UI。编辑 UI 控件不会将值写回数据源成员。

支持的绑定器组件

文本和标量：UitkLabel、UitkTextField、UitkDoubleField、UitkFloatField、UitkIntegerField、UitkLongField、UitkEnumField。
控件：UitkProgressBar、UitkRadioButton、UitkSlider、UitkSliderInt。
向量：UitkVector2Field、UitkVector2IntField、UitkVector3Field、UitkVector3IntField、UitkVector4Field。
视觉内容：使用 Sprite 数据源的 UitkImage。

具体绑定器是否可用，取决于当前 Unity 版本中是否存在对应的 UI Toolkit 元素类型。

检查器设置

首先配置 UIDocument、链接模式和元素定位器。
启用 Binding Enabled。
将 GameObject 分配给 Binding > Target Object。数据源组件必须附加到该 GameObject。
打开 Member 弹出菜单并选择可读取的字段或属性。
可选：分配 UitkBindingSettings 资源以控制 Member 弹出菜单。
设置 Binding Rate Ms。

存储的成员路径使用斜杠分隔各段。第一段是组件类型名称，其余各段是字段或可读取的属性，例如 ValueUpdater/Player/Health。

更新频率

如果任一 Binding Rate Ms 值为 0 或负数，绑定将在每次调用 Update 时更新。
如果两个正值相等，该值就是固定间隔，单位为毫秒。
如果两个正值不同，ULB 会在每次更新后从两者之间选择一个新的随机间隔。

使用仍能保证 UI 响应流畅的最慢间隔。每次更新都会读取成员链并转换值。

以编程方式设置

using DA_Assets.ULB;
using UnityEngine;

public sealed class HealthProvider : MonoBehaviour
{
    public float Health = 100f;
}

public sealed class HealthBindingSetup : MonoBehaviour
{
    [SerializeField] private UitkProgressBar healthBar;
    [SerializeField] private HealthProvider provider;

    private void Start()
    {
        healthBar.BindingEnabled = true;
        healthBar.BindingRateMs = new Vector2Int(100, 100);
        healthBar.Binding = new MemberBinding
        {
            TargetObject = provider.gameObject,
            Member = $"{nameof(HealthProvider)}/{nameof(HealthProvider.Health)}"
        };
        healthBar.Initialize();
    }
}

在 Initialize 之前设置定位器和绑定字段。Initialize 会链接元素并缓存所选成员链。

值的应用方式

Bind 会解析组件，并缓存所选的公共、非公共、实例或静态字段和属性链。
每次更新都会读取缓存的成员链。如果数据源值为 null，则跳过该次 UI 更新。
ULB 将数据源值转换为链接器声明的可绑定类型。
INotifyValueChanged<T> 控件会直接接收值。ProgressBar 和 Image 有专用处理；其他目标使用基于反射的 value 属性回退机制。

数据源类型必须与绑定器类型兼容。转换失败时会记录日志，先前的 UI 值保持不变。

绑定设置

Max Depth：Member 弹出菜单公开的最大深度，范围为 0 到 4。
Show Primitive Type：在弹出菜单标签中添加基元类型名称。
Show Object Type：在弹出菜单标签中添加类或值类型名称。
Show To String：为支持的 Unity 结构体提供 [ToString] 选项。
Show Obsolete：包括已过时成员，但不包括标记为 Obsolete 且 IsError = true 的成员。

UitkBindingSettings 会影响 Member 弹出菜单中的成员发现和标签，但不会更改运行时更新间隔。

Show To String 涵盖 Color、Vector 类型、Rect、Bounds、Quaternion 和 Matrix4x4 等受支持的 Unity 类型。请验证所选值能否转换为目标绑定器类型。

在运行时更改绑定

更改 TargetObject 或 Member 后，调用 Bind 以重新构建缓存的成员链。如果 UIDocument 树或定位器也发生了变化，请配置所有字段并调用 Initialize。

2026-07-31 04:49:56