防崩溃，AOT修复，文档完善

Author: StarryXYJ

.gitignore

@@ -67,4 +67,6 @@ coverage/
 # dev
 AgentHelper/
 Task.md
-manual/dev
+manual/dev
+build.ps1
+build.sh

Demo/AutoSettingUI.Avalonia.CrossPlatform.Demo/AutoSettingUI.Avalonia.CrossPlatform.Demo/App.axaml.cs

@@ -6,6 +6,8 @@
 using Avalonia.Markup.Xaml;
 using AutoSettingUI.Avalonia.CrossPlatform.Demo.ViewModels;
 using AutoSettingUI.Avalonia.CrossPlatform.Demo.Views;
+using AutoSettingUI.Core.Registry;
+using AutoSettingUI.Generated;
 
 namespace AutoSettingUI.Avalonia.CrossPlatform.Demo;
 
@@ -23,13 +25,17 @@ public override void OnFrameworkInitializationCompleted()
             // Avoid duplicate validations from both Avalonia and the CommunityToolkit. 
             // More info: https://docs.avaloniaui.net/docs/guides/development-guides/data-validation#manage-validationplugins
             DisableAvaloniaDataAnnotationValidation();
+
             desktop.MainWindow = new MainWindow
             {
                 DataContext = new MainViewModel()
             };
         }
         else if (ApplicationLifetime is ISingleViewApplicationLifetime singleViewPlatform)
         {
+            var provider = new GeneratedSettingProvider();
+            AotSettingRegistry.Provider = provider;
+            AotSettingRegistry.Accessor = provider;
             singleViewPlatform.MainView = new MainView
             {
                 DataContext = new MainViewModel()
@@ -51,4 +57,4 @@ private void DisableAvaloniaDataAnnotationValidation()
             BindingPlugins.DataValidators.Remove(plugin);
         }
     }
-}
+}

Demo/AutoSettingUI.Ursa.Demo/App.axaml.cs

@@ -4,6 +4,8 @@
 using Avalonia.Data.Core.Plugins;
 using System.Linq;
 using Avalonia.Markup.Xaml;
+using AutoSettingUI.Core.Registry;
+using AutoSettingUI.Generated;
 using AutoSettingUI.Ursa.Demo.ViewModels;
 using AutoSettingUI.Ursa.Demo.Views;
 
@@ -23,6 +25,7 @@ public override void OnFrameworkInitializationCompleted()
             // Avoid duplicate validations from both Avalonia and the CommunityToolkit. 
             // More info: https://docs.avaloniaui.net/docs/guides/development-guides/data-validation#manage-validationplugins
             DisableAvaloniaDataAnnotationValidation();
+
             desktop.MainWindow = new MainWindow
             {
                 DataContext = new MainWindowViewModel(),
@@ -44,4 +47,4 @@ private void DisableAvaloniaDataAnnotationValidation()
             BindingPlugins.DataValidators.Remove(plugin);
         }
     }
-}
+}

Demo/AutoSettingUI.Ursa.Demo/Models/ApplicationSettings.cs

@@ -344,7 +344,6 @@ public class ExtendedControlsSettings
     [TimePicker]
     public TimeSpan PreferredTime { get; set; } = DateTime.Now.TimeOfDay;
 
-    [Title("Toggle Feature")]
     [CheckBox]
     public bool EnableAdvancedFeature { get; set; } = true;
 

README.md

@@ -30,77 +30,122 @@ Install the package for your preferred UI framework:
 
 ## Quick Start
 
-### 1. Define Your Settings Class
+This section shows a minimal end-to-end setup using the current demos as reference. It covers Avalonia, Ursa, and WPF, plus AOT support.
+
+### 1. Add Packages / References
+
+```xml
+<!-- Avalonia -->
+<PackageReference Include="AutoSettingUI.Avalonia" Version="1.0.0" />
+
+<!-- Ursa (Avalonia with Ursa theme) -->
+<PackageReference Include="AutoSettingUI.Ursa" Version="1.0.0" />
+
+<!-- WPF -->
+<PackageReference Include="AutoSettingUI.WPF" Version="1.0.0" />
+```
+
+If you want AOT support, also reference the generator in your **app** project:
+
+```xml
+<ProjectReference Include="..\..\src\AutoSettingUI.Generator\AutoSettingUI.Generator.csproj"
+                  OutputItemType="Analyzer"
+                  ReferenceOutputAssembly="false" />
+```
+
+### 2. Define a Settings Model
 
 ```csharp
 using AutoSettingUI.Core.Attributes;
+using AutoSettingUI.Avalonia.Attributes; // or AutoSettingUI.Ursa.Attributes
 
-[SettingUI(Category = "General", Order = 0)]
-[MainHeader("Application Settings")]
-public class AppSettings
+[SettingUI]
+public sealed class AppSettings
 {
-    [Title("App Name")]
-    public string Name { get; set; } = "My App";
+    [Title("Volume")]
+    [ControlBinding(typeof(Avalonia.Controls.Slider), "Value", nameof(CreateVolume))]
+    public double Volume { get; set; } = 50;
 
-    [Title("Enable Dark Mode")]
-    public bool DarkMode { get; set; }
+    public Avalonia.Controls.Slider CreateVolume()
+        => new Avalonia.Controls.Slider { Minimum = 0, Maximum = 100, Value = 50 };
 
-    [Title("Volume"), Range(0, 100)]
-    public int Volume { get; set; } = 50;
+    [Title("Enable Feature")]
+    [CheckBox]
+    public bool EnableFeature { get; set; } = true;
 
-    [Title("Language")]
-    [ItemsSource(typeof(AppSettings), nameof(AvailableLanguages))]
-    public string Language { get; set; } = "en-US";
+    [Title("Font Size")]
+    [NumericUpDown(Minimum = 8, Maximum = 32, Increment = 1)]
+    public int FontSize { get; set; } = 14;
 
-    public static string[] AvailableLanguages => ["en-US", "zh-CN", "ja-JP"];
+    [Title("Tags")]
+    public System.Collections.ObjectModel.ObservableCollection<string> Tags { get; set; }
+        = new() { "Important", "Work" };
 }
 ```
 
-### 2. Add the Panel to Your UI
+### 3. Bind the Panel
 
-#### Avalonia
+Avalonia:
 
 ```xml
 <Window xmlns:auto="clr-namespace:AutoSettingUI.Avalonia.Controls;assembly=AutoSettingUI.Avalonia">
-    <auto:AvaloniaAutoSettingPanel
-        Title="Settings"
-        Targets="{Binding SettingsList}"
-        ShowNavigation="True" />
+    <auto:AvaloniaAutoSettingPanel Targets="{Binding Targets}" />
 </Window>
 ```
 
-#### Ursa
+Ursa:
 
 ```xml
 <Window xmlns:ursa="clr-namespace:AutoSettingUI.Ursa.Controls;assembly=AutoSettingUI.Ursa">
-    <ursa:UrsaAutoSettingPanel
-        Title="Settings"
-        Targets="{Binding SettingsList}"
-        UseCardBorderTheme="True" />
+    <ursa:UrsaAutoSettingPanel Targets="{Binding Targets}" />
 </Window>
 ```
 
-#### WPF
+WPF:
 
 ```xml
 <Window xmlns:auto="clr-namespace:AutoSettingUI.WPF.Controls;assembly=AutoSettingUI.WPF">
-    <auto:WpfAutoSettingPanel
-        Title="Settings"
-        Targets="{Binding SettingsList}"
-        ShowNavigation="True" />
+    <auto:WpfAutoSettingPanel Targets="{Binding Targets}" />
 </Window>
 ```
 
-### 3. AOT Support (Optional)
+ViewModel:
+
+```csharp
+public class MainViewModel
+{
+    public IEnumerable<object> Targets { get; } = new object[]
+    {
+        new AppSettings()
+    };
+}
+```
+
+### 4. AOT Support (Optional)
 
-For Native AOT or trimming support, use the generated provider:
+For Native AOT or trimming, make sure the generator is referenced by the **app** project. In most cases the generated provider is picked up automatically. If you want to force it (or you see fallback-to-TextBox in AOT), do:
 
 ```csharp
-// The source generator creates this class automatically
-panel.DescriptorProvider = new AutoSettingUI.Generated.GeneratedSettingProvider();
-panel.PropertyAccessor = new AutoSettingUI.Generated.GeneratedSettingProvider();
+using AutoSettingUI.Core.Registry;
+using AutoSettingUI.Generated;
+
+var provider = new GeneratedSettingProvider();
+AotSettingRegistry.Provider = provider;
+AotSettingRegistry.Accessor = provider;
+```
+
+### 5. Publish AOT (Example)
+
+```bash
+# Ursa demo
+pwsh ./publish-demo.ps1 -Framework Avalonia -Mode AOT
 ```
 
+### Notes
+
+- Use `EmitCompilerGeneratedFiles=true` if you want to inspect generated code.
+- `CollectionEditor(AllowEditItems = false)` can make collection rows read-only.
+
 ## Extended Controls
 
 AutoSettingUI provides extended control attributes for specialized inputs:

README.zh-CN.md

@@ -30,77 +30,122 @@
 
 ## 快速上手
 
-### 1. 定义设置类
+这部分基于 demo 的最小端到端使用示例，覆盖 Avalonia、Ursa、WPF，并包含 AOT 支持。
+
+### 1. 添加包 / 引用
+
+```xml
+<!-- Avalonia -->
+<PackageReference Include="AutoSettingUI.Avalonia" Version="1.0.0" />
+
+<!-- Ursa (带 Ursa 主题的 Avalonia) -->
+<PackageReference Include="AutoSettingUI.Ursa" Version="1.0.0" />
+
+<!-- WPF -->
+<PackageReference Include="AutoSettingUI.WPF" Version="1.0.0" />
+```
+
+如需 AOT 支持，请在 **应用项目** 中额外引用源代码生成器：
+
+```xml
+<ProjectReference Include="..\..\src\AutoSettingUI.Generator\AutoSettingUI.Generator.csproj"
+                  OutputItemType="Analyzer"
+                  ReferenceOutputAssembly="false" />
+```
+
+### 2. 定义设置模型
 
 ```csharp
 using AutoSettingUI.Core.Attributes;
+using AutoSettingUI.Avalonia.Attributes; // 或 AutoSettingUI.Ursa.Attributes
 
-[SettingUI(Category = "通用", Order = 0)]
-[MainHeader("应用设置")]
-public class AppSettings
+[SettingUI]
+public sealed class AppSettings
 {
-    [Title("应用名称")]
-    public string Name { get; set; } = "我的应用";
+    [Title("Volume")]
+    [ControlBinding(typeof(Avalonia.Controls.Slider), "Value", nameof(CreateVolume))]
+    public double Volume { get; set; } = 50;
 
-    [Title("启用深色模式")]
-    public bool DarkMode { get; set; }
+    public Avalonia.Controls.Slider CreateVolume()
+        => new Avalonia.Controls.Slider { Minimum = 0, Maximum = 100, Value = 50 };
 
-    [Title("音量"), Range(0, 100)]
-    public int Volume { get; set; } = 50;
+    [Title("Enable Feature")]
+    [CheckBox]
+    public bool EnableFeature { get; set; } = true;
 
-    [Title("语言")]
-    [ItemsSource(typeof(AppSettings), nameof(AvailableLanguages))]
-    public string Language { get; set; } = "zh-CN";
+    [Title("Font Size")]
+    [NumericUpDown(Minimum = 8, Maximum = 32, Increment = 1)]
+    public int FontSize { get; set; } = 14;
 
-    public static string[] AvailableLanguages => ["zh-CN", "en-US", "ja-JP"];
+    [Title("Tags")]
+    public System.Collections.ObjectModel.ObservableCollection<string> Tags { get; set; }
+        = new() { "Important", "Work" };
 }
 ```
 
-### 2. 在界面中添加面板
+### 3. 绑定面板
 
-#### Avalonia
+Avalonia:
 
 ```xml
 <Window xmlns:auto="clr-namespace:AutoSettingUI.Avalonia.Controls;assembly=AutoSettingUI.Avalonia">
-    <auto:AvaloniaAutoSettingPanel
-        Title="设置"
-        Targets="{Binding SettingsList}"
-        ShowNavigation="True" />
+    <auto:AvaloniaAutoSettingPanel Targets="{Binding Targets}" />
 </Window>
 ```
 
-#### Ursa
+Ursa:
 
 ```xml
 <Window xmlns:ursa="clr-namespace:AutoSettingUI.Ursa.Controls;assembly=AutoSettingUI.Ursa">
-    <ursa:UrsaAutoSettingPanel
-        Title="设置"
-        Targets="{Binding SettingsList}"
-        UseCardBorderTheme="True" />
+    <ursa:UrsaAutoSettingPanel Targets="{Binding Targets}" />
 </Window>
 ```
 
-#### WPF
+WPF:
 
 ```xml
 <Window xmlns:auto="clr-namespace:AutoSettingUI.WPF.Controls;assembly=AutoSettingUI.WPF">
-    <auto:WpfAutoSettingPanel
-        Title="设置"
-        Targets="{Binding SettingsList}"
-        ShowNavigation="True" />
+    <auto:WpfAutoSettingPanel Targets="{Binding Targets}" />
 </Window>
 ```
 
-### 3. AOT 支持（可选）
+ViewModel:
+
+```csharp
+public class MainViewModel
+{
+    public IEnumerable<object> Targets { get; } = new object[]
+    {
+        new AppSettings()
+    };
+}
+```
+
+### 4. AOT 支持（可选）
 
-如需支持 Native AOT 或裁剪发布，使用源生成器生成的提供者：
+如需 Native AOT 或裁剪发布，请确保生成器在 **应用项目** 中被引用。多数情况下会自动使用生成的 Provider。如果 AOT 下出现回退为 TextBox，可以手动指定：
 
 ```csharp
-// 源生成器会自动创建此类
-panel.DescriptorProvider = new AutoSettingUI.Generated.GeneratedSettingProvider();
-panel.PropertyAccessor = new AutoSettingUI.Generated.GeneratedSettingProvider();
+using AutoSettingUI.Core.Registry;
+using AutoSettingUI.Generated;
+
+var provider = new GeneratedSettingProvider();
+AotSettingRegistry.Provider = provider;
+AotSettingRegistry.Accessor = provider;
+```
+
+### 5. 发布 AOT（示例）
+
+```bash
+# Ursa demo
+pwsh ./publish-demo.ps1 -Framework Avalonia -Mode AOT
 ```
 
+### 说明
+
+- 需要查看生成代码时，可启用 `EmitCompilerGeneratedFiles=true`。
+- `CollectionEditor(AllowEditItems = false)` 可将集合行设为只读。
+
 ## 扩展控件
 
 AutoSettingUI 提供了多种扩展控件特性，用于特殊输入场景：