在 MAUI 中创建可绑定属性需四步：1. 声明 public static readonly BindableProperty 字段；2. 定义 .NET 属性包装器调用 GetValue/SetValue；3. 用 BindableProperty.Create 注册，指定名称、类型、宿主类、默认值等；4. 可选添加 propertyChanged 回调。
在 MAUI 中创建可绑定属性（BindableProperty）是实现数据绑定、自定义控件和响应式 UI 的核心技能。它不是普通 C# 属性，而是 MAUI 框架识别的“注册属性”，支持绑定、样式、动画、模板等高级功能。
为什么不能直接用普通属性？
普通 C# 属性（如 public string Title { get; set; }）无法被 MAUI 绑定系统识别，也不能参与属性值变更通知、默认值管理或属性继承。只有通过 BindableProperty.Create() 注册的属性，才能真正接入 MAUI 的绑定管道。
四步创建 BindableProperty（以自定义 Label 为例）
假设你要为一个继承自 Label 的自定义控件添加一个可绑定的 Subtitle 属性：
-
1. 声明静态 BindableProperty 字段：必须是
public static readonly，命名惯例为PropertyNameProperty -
2. 定义 .NET 属性包装器：提供简洁的 get/set 语法，内部调用
GetValue()和SetValue() - 3. 调用 BindableProperty.Create()：指定类型、宿主类型、默认值、绑定模式等关键参数
- 4. （可选）添加属性更改回调：用于监听值变化并触发 UI 更新或逻辑处理
完整代码示例：
public class CustomLabel : Label
{
// 1. 静态只读 BindableProperty 字段
public static readonly BindableProperty SubtitleProperty =
BindableProperty.Create(
propertyName: nameof(Subtitle),
returnType: typeof(string),
declaringType: typeof(CustomLabel),
defaultValue: string.Empty,
defaultBindingMode: BindingMode.OneWay,
propertyChanged: OnSubtitleChanged);
<pre class="brush:php;toolbar:false;">// 2. .NET 属性包装器
public string Subtitle
{
get => (string)GetValue(SubtitleProperty);
set => SetValue(SubtitleProperty, value);
}
// 3. 可选：值变更回调
private static void OnSubtitleChanged(BindableObject bindable, object oldValue, object newValue)
{
if (bindable is CustomLabel label)
{
// 在这里更新 UI 或触发逻辑，例如刷新布局
label.InvalidateLayout();
}
}}
常用参数说明与避坑点
BindableProperty.Create() 有多个重载，最常用的是带 6 个参数的版本：
- propertyName：必须与包装器属性名完全一致（包括大小写），否则绑定失败
-
returnType：属性实际类型，如
typeof(bool)、typeof(Color) -
declaringType：当前类类型（
typeof(MyControl)），不能写成基类 -
defaultValue：值类型传字面量（
0、false），引用类型建议用null或string.Empty，避免共享可变对象 -
defaultBindingMode：常用
OneWay（默认）、TwoWay（如输入控件）、OneTime -
propertyChanged：回调方法签名固定为
(BindableObject, object, object)，务必检查bindable类型再转型
在 XAML 中使用和绑定
注册完成后，你就能像内置属性一样使用：
<local:CustomLabel
Text="主标题"
Subtitle="{Binding MySubtitle}"
SubtitleProperty="副标题文本" />注意：无需额外标记或特性，MAUI 会自动发现 SubtitleProperty 字段并关联到 Subtitle 属性。
基本上就这些。只要记住：先注册字段、再写包装器、别拼错名字、默认值别传错类型——BindProperty 就不会“失灵”。
