WPF 中 DependencyProperty 必须用 public static readonly 声明
DependencyProperty 不是普通字段，它本身是
DependencyProperty类型的静态只读字段，由
DependencyProperty.Register返回。如果声明成实例字段、非
readonly或非
static，XAML 加载时会直接抛出
XamlParseException，错误信息类似 “The property 'XXX' was not found in type 'YYY'”。
正确写法必须严格遵循命名约定：属性名 +
Property后缀，且注册名（第一个参数）必须与依赖属性包装器名称一致（不含
Property）：
public static readonly DependencyProperty IsExpandedProperty =
DependencyProperty.Register(
nameof(IsExpanded), // ← 必须是 "IsExpanded"，不是 "IsExpandedProperty"
typeof(bool),
typeof(MyControl),
new PropertyMetadata(false));依赖属性必须配对实现 .NET 属性包装器
仅声明
DependencyProperty字段无法在 C# 代码中以
obj.IsExpanded = true方式使用，必须提供标准的 get/set 访问器，内部调用
GetValue/
SetValue。否则编译不报错，但运行时赋值无效，绑定也不会响应。
常见错误包括：忘记
GetValue、误用
this.访问私有字段、或在 set 中调用 base.SetValue（WPF 控件应直接调用
SetValue）：
public bool IsExpanded
{
get => (bool)GetValue(IsExpandedProperty);
set => SetValue(IsExpandedProperty, value);
}
get 中必须显式转换类型，GetValue返回
objectset 中不能写
base.SetValue(...)（除非你继承的是
FrameworkElement且重写了该方法，一般不用） 不要在 set 中加逻辑判断再调用
SetValue——这会绕过 WPF 的变更通知和绑定系统
回调函数（PropertyChangedCallback）里不能直接访问 this.DataContext
当依赖属性值变化触发
PropertyChangedCallback时，回调执行在静态上下文中，此时
this不可用。传入的是
DependencyObject（通常是你的控件实例），需先强制转换才能访问实例成员：
static void OnIsExpandedChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
{
if (d is MyControl control)
{
// ✅ 正确：先转换再用
control.UpdateVisualState();
}
}容易踩的坑：
在回调里直接写this.DataContext→ 编译失败（
this不在作用域） 把回调写成实例方法（非
static）→ 注册失败，运行时报
ArgumentException：“The PropertyChangedCallback must be a static method” 在回调中调用
SetValue引发递归更新 → 需用
e.OldValue != e.NewValue判断，或改用
CoerceValueCallback
绑定到依赖属性时，BindingMode 默认不是 TwoWay
即使你实现了完整的 get/set 包装器，XAML 中的
Binding默认仍是
OneWay。比如
{Binding IsExpanded, ElementName=btn} 不会把用户点击结果写回源属性，除非显式指定 Mode=TwoWay或目标属性注册时设置了
FrameworkPropertyMetadataOptions.BindsTwoWayByDefault。
例如，自定义布尔属性想默认双向绑定，注册时要这样写：
new FrameworkPropertyMetadata(
false,
FrameworkPropertyMetadataOptions.BindsTwoWayByDefault,
OnIsExpandedChanged)否则 UI 改变不会触发你的
PropertyChangedCallback，看起来“绑定失效”。这不是代码错，是 WPF 的默认行为设计使然。
真正难调试的地方在于：所有语法都对，但 UI 行为和预期不符——这时候第一反应该查
BindingMode和
FrameworkPropertyMetadataOptions，而不是重写整个属性逻辑。
