WinUI3自定义控件属性绑定失效问题及解决方法

我开发了一个用作Item View按钮的WinUI3自定义控件，遇到文本绑定失效的问题：在通过ContentFrame.Navigate()跳转的页面中使用时，TableName属性无法正常显示文本，但在复用实例的页面中能正常工作。最终发现是DependencyProperty未声明为public static readonly，添加修饰符后问题解决。

错误代码（未正确声明DependencyProperty） #

namespace CustomControls
{
    public sealed class CustomTableItem : Control
    {
        // 错误：缺少public static readonly修饰符
        DependencyProperty TableNameProperty = DependencyProperty.Register(
            nameof(TableName),
            typeof(string),
            typeof(CustomTableItem),
            new PropertyMetadata(null));

        public string TableName
        {
            get => (string)GetValue(TableNameProperty);
            set => SetValue(TableNameProperty, value);
        }

        // 构造函数...
    }
}

排查过程 #

排查中发现两个关键现象：

• Generic.xaml中的模板绑定配置无误，但绑定源始终为空
• 页面中创建多个控件实例时，仅最后一个能正常显示文本

修正后的代码（正确声明DependencyProperty） #

namespace CustomControls
{
    public sealed class CustomTableItem : Control
    {
        // 正确：添加public static readonly修饰符
        public static readonly DependencyProperty TableNameProperty = DependencyProperty.Register(
            nameof(TableName),
            typeof(string),
            typeof(CustomTableItem),
            new PropertyMetadata(null));

        public string TableName
        {
            get => (string)GetValue(TableNameProperty);
            set => SetValue(TableNameProperty, value);
        }

        // 构造函数...
    }
}

核心原因 #

在WinUI3（以及WPF/UWP）的依赖属性体系中，必须满足以下声明规则：

• static：依赖属性是类级别的注册项，所有控件实例共享同一属性定义，框架通过类静态成员识别属性
• readonly：确保依赖属性注册后不会被意外修改，保证属性体系的稳定性
• public：允许XAML解析器、绑定系统等外部组件访问该属性定义

缺少这些修饰符时，绑定系统无法正确定位和访问依赖属性，导致页面导航这类需要框架重新解析控件的场景中绑定失效，仅在实例复用的场景下因局部上下文巧合临时正常工作。

内容的提问来源于stack exchange，提问作者Arthur Buzas Baccan