Unity及UI Toolkit中自定义格式化派生数据绑定实现方法

问题描述 #

Unity UI Toolkit 提供了便捷的数据绑定功能，但在特定场景下的用法存在适配需求：

• 游戏中代表角色的GameObject带有取值范围为[0, 1]的float类型health字段，对应0%到100%的生命值百分比区间，需要在UI中以百分比格式展示该数值
• 直接通过binding-path做简单绑定会直接展示未格式化的原始浮点数，不符合展示要求
• 期望实现派生绑定能力：源数值变化时，先走自定义格式化逻辑生成派生值，再将派生值绑定到UI控件
• 现有实现通过TrackPropertyValue手动监听属性变化、更新UI文本，写法繁琐，希望通过配置binding-path的声明式方式完成绑定，寻找符合Unity框架惯例的最优实现

现有可运行但待优化的代码：

var label = row.Q<Label>(className: "pawn-health");
label.RegisterCallback<SerializedPropertyChangeEvent>(evt => {
    label.text = evt.changedProperty.floatValue.ToString("0.0%");
});
label.TrackPropertyValue(obj.FindProperty(nameof(Pawn.health)));

推荐实现方案 #

UI Toolkit 原生就支持派生绑定能力，不需要手动写属性追踪逻辑，根据项目架构选下面两种方案即可，都是官方推荐的标准写法：

方案1：使用原生值转换器（ConverterGroups），完全保留声明式绑定 #

这是最贴合「通过binding-path配置绑定」需求的方案，不需要改动原有数据层代码，只需要给绑定配置值转换规则，绑定系统会在源值更新时自动执行格式化逻辑再传给UI控件。

1. 首先实现自定义值转换器：

   using System.Globalization;
   using Unity.Properties;
   
   // 泛型参数依次是源类型、目标类型
   public class FloatToPercentConverter : IValueConverter<float, string>
   {
       // 源值同步到UI时执行的转换逻辑
       public string Convert(float value, CultureInfo culture)
       {
           return value.ToString("0.0%");
       }
   
       // UI值同步回源时执行的反向转换，单向绑定不需要实现
       public float ConvertBack(string value, CultureInfo culture)
       {
           throw new System.NotSupportedException("仅支持单向绑定，反向转换未实现");
       }
   }
   

2. 配置绑定时添加转换器，正常指定绑定路径即可：

   var label = row.Q<Label>(className: "pawn-health");
   var healthBinding = new DataBinding
   {
       dataSourcePath = new PropertyPath(nameof(Pawn.health)),
       bindingMode = BindingMode.ToTarget // 配置为数据源到UI的单向绑定
   };
   // 注册我们写的百分比转换器
   healthBinding.sourceToUiConverters.AddConverter(new FloatToPercentConverter());
   // 给Label的text属性设置绑定
   label.SetBinding(Label.textProperty, healthBinding);
   

如果是直接在UXML文件里写绑定，还可以把转换器注册为全局资源，直接在UXML标签里引用，完全不需要写C#绑定代码。

方案2：ViewModel层定义派生属性（适合MVVM架构项目） #

如果项目已经在用UI Toolkit的MVVM模式（使用Observable属性、源生成器做数据通知），可以直接在数据层定义派生的展示字段，格式化逻辑内聚在数据层，绑定直接指向派生字段即可：

using CommunityToolkit.Mvvm.ComponentModel;

public partial class PawnViewModel : ObservableObject
{
    // 原始生命值字段
    [ObservableProperty] private float _health;

    // 供UI绑定的百分比文本派生属性
    public string HealthPercentDisplay => Health.ToString("0.0%");

    // 原始值变化时，同步通知UI派生属性更新
    partial void OnHealthChanged(float value)
    {
        OnPropertyChanged(nameof(HealthPercentDisplay));
    }
}

这种方式绑定的时候binding-path直接填HealthPercentDisplay即可，不需要额外配置转换器，逻辑更集中。

补充说明：2022及更早版本的UI Toolkit对值转换器的支持不完善，这类旧版本才需要用TrackPropertyValue手动监听更新；2023及之后的版本，值转换器是官方推荐的绑定格式化标准方案，不需要手写回调逻辑。

内容的提问来源于stack exchange，提问作者Max