UWP中如何创建List<Control>类型依赖属性并支持XAML赋值

问题场景 #

开发用于切换应用主题的自定义控件ModeSelector时，需要支持控件使用者在XAML中指定需要同步修改背景的目标元素，后台可直接获取配置的元素集合批量修改背景色。

预期实现的XAML写法（原伪代码存在语法错误） #

<Grid x:Name="Grid1" Grid.Column="1" Background="Black">
   <Button x:Name="Button1"/>
   <local:ModeSelector Grid.Row="1">
      <local:ModeSelector.Tools>
         <Button1/>
         <Grid1/>
         ... 
      </local:ModeSelector.Tools>
   </local:ModeSelector>
</Grid>

原有依赖属性实现的问题 #

public List<Control> Tools
{
    get { return (List<Control>)GetValue(ToolsProperty); }
    set { SetValue(ToolsProperty, new List<Control>()); }
}

public static readonly DependencyProperty ToolsProperty =
    DependencyProperty.Register("Tools", typeof(List<Control>), typeof(ModeSelector), new PropertyMetadata(new List<Control>()));

原有实现存在三个核心错误：

• 集合类型依赖属性在PropertyMetadata中传入默认集合实例，会导致所有ModeSelector实例共享同一个集合，出现多页面/多实例数据串扰
• 属性setter逻辑错误，赋值时直接新建空列表，会完全丢弃XAML中配置的元素；且XAML加载依赖属性时不会走自定义wrapper的set逻辑，这里写的代码完全不会执行
• 元素类型限定为Control，无法接收Grid这类继承自Panel的容器元素；且XAML中直接写<Button1/>是尝试新建同名类型实例，并非引用页面已有的命名元素

正确实现步骤 #

1. 修正依赖属性定义 #

集合类型依赖属性不要设置默认共享实例，改为在控件构造函数中为每个实例初始化独立集合；将集合元素类型改为DependencyObject以兼容所有UI元素；移除无效的自定义setter。

using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Media;
using System.Collections.Generic;
using Windows.UI.Xaml.Markup;

// 标记Tools为控件的默认内容属性，简化XAML写法
[ContentProperty(Name = nameof(Tools))]
public sealed partial class ModeSelector : UserControl
{
    public ModeSelector()
    {
        this.InitializeComponent();
        // 每个控件实例初始化独立的集合
        SetValue(ToolsProperty, new List<DependencyObject>());
    }

    public IList<DependencyObject> Tools
    {
        get => (IList<DependencyObject>)GetValue(ToolsProperty);
    }

    public static readonly DependencyProperty ToolsProperty =
        DependencyProperty.Register(
            nameof(Tools),
            typeof(IList<DependencyObject>),
            typeof(ModeSelector),
            new PropertyMetadata(null)
        );
}

2. 修正XAML引用语法 #

XAML中不能直接用元素名作为标签引用已有实例，需要使用x:Reference标记扩展指向已命名的页面元素：

<Grid x:Name="Grid1" Grid.Column="1" Background="Black">
   <Button x:Name="Button1"/>
   <!-- 因为加了ContentProperty特性，不需要再显式写<local:ModeSelector.Tools>标签 -->
   <local:ModeSelector Grid.Row="1">
      <x:Reference Name="Button1"/>
      <x:Reference Name="Grid1"/>
   </local:ModeSelector>
</Grid>

3. 后台批量修改背景逻辑 #

主题切换时遍历Tools集合，根据元素实际类型修改Background属性即可：

private void ApplyTheme(ElementTheme theme)
{
    Brush targetBackground = theme switch
    {
        ElementTheme.Dark => new SolidColorBrush(Colors.Black),
        ElementTheme.Light => new SolidColorBrush(Colors.White),
        _ => (Brush)Application.Current.Resources["ApplicationPageBackgroundThemeBrush"]
    };

    foreach (var item in Tools)
    {
        switch (item)
        {
            case Control control:
                control.Background = targetBackground;
                break;
            case Panel panel:
                panel.Background = targetBackground;
                break;
            case Border border:
                border.Background = targetBackground;
                break;
            // 可按需扩展其他带Background属性的元素类型
        }
    }
}

注意事项 #

• 依赖属性的wrapper（即C#属性的get/set块）只能写GetValue和SetValue逻辑，不要添加其他自定义逻辑，XAML解析时会直接调用底层GetValue/SetValue方法，不会走wrapper的自定义代码
• 所有集合类型的依赖属性都不要在PropertyMetadata中传入默认实例，必须在控件构造函数中为每个实例单独初始化集合
• 如果需要在集合元素新增/删除时触发逻辑，可以在构造函数中给Tools集合添加CollectionChanged事件监听

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