Skip to content

Commit 2b22a57

Browse files
StarryXYJStarryXYJ
committed
文档
1 parent 1626041 commit 2b22a57

19 files changed

Lines changed: 1635 additions & 40 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ publish/
99
*.nupkg
1010
*.snupkg
1111
project.lock.json
12+
artifacts/
1213

1314
# IDE - JetBrains Rider
1415
.idea/

‎AutoSettingUI.Extension.Shared/AutoSettingUI.Extension.Shared.csproj‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,32 @@
1-
<Project Sdk="Microsoft.NET.Sdk">
1+
<Project Sdk="Microsoft.NET.Sdk">
22

33
<PropertyGroup>
44
<TargetFramework>net9.0</TargetFramework>
55
<ImplicitUsings>enable</ImplicitUsings>
66
<Nullable>enable</Nullable>
7+
<IsAotCompatible>true</IsAotCompatible>
8+
<EnableTrimAnalyzer>true</EnableTrimAnalyzer>
9+
10+
<!-- NuGet Packaging -->
11+
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
12+
<PackageId>AutoSettingUI.Extension.Shared</PackageId>
13+
<Version>1.0.0</Version>
14+
<Authors>AutoSettingUI Contributors</Authors>
15+
<Description>Shared utilities and helpers for AutoSettingUI framework extensions</Description>
16+
<PackageTags>settings;configuration;ui;shared;helpers</PackageTags>
17+
<PackageLicenseExpression>MIT</PackageLicenseExpression>
18+
<PackageProjectUrl>https://github.com/StarryXYJ/AutoSettingUI</PackageProjectUrl>
19+
<RepositoryUrl>https://github.com/StarryXYJ/AutoSettingUI.git</RepositoryUrl>
20+
<RepositoryType>git</RepositoryType>
21+
<PackageReadmeFile>README.md</PackageReadmeFile>
722
</PropertyGroup>
823

924
<ItemGroup>
1025
<ProjectReference Include="..\src\AutoSettingUI.Core\AutoSettingUI.Core.csproj" />
1126
</ItemGroup>
1227

28+
<ItemGroup>
29+
<None Include="README.md" Pack="true" PackagePath="\" />
30+
</ItemGroup>
31+
1332
</Project>

‎AutoSettingUI.Extension.Shared/README.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# AutoSettingUI.Extension.Shared
2+
3+
Shared utilities and helpers for **AutoSettingUI** framework extensions. This package contains common code used by all UI framework implementations (Avalonia, Ursa, WPF).
4+
5+
[![NuGet](https://img.shields.io/nuget/v/ASettingUI.Extension.Shared.svg)](https://www.nuget.org/packages/AutoSettingUI.Extension.Shared/)
6+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7+
8+
## Installation
9+
10+
```xml
11+
<PackageReference Include="AutoSettingUI.Extension.Shared" Version="1.0.0" />
12+
```
13+
14+
> **Note:** This package is typically installed automatically as a dependency of the framework-specific packages.
15+
16+
## Features
17+
18+
### ValidationHelper
19+
20+
Provides unified validation logic for property values:
21+
22+
```csharp
23+
using AutoSettingUI.Extension.Shared;
24+
25+
// Validate a property value
26+
bool isValid = ValidationHelper.ValidateValue(propertyInfo, value, target, out string? errorMessage);
27+
```
28+
29+
Supported validations:
30+
- Required field validation
31+
- String length validation (MinLength/MaxLength)
32+
- Pattern matching (Regex)
33+
- Numeric range validation (MinValue/MaxValue)
34+
- Custom validation method invocation
35+
36+
### ExtendedControlHelper
37+
38+
Simplifies creating controls from `ControlBindingAttribute`:
39+
40+
```csharp
41+
using AutoSettingUI.Extension.Shared;
42+
43+
// Create a control from attribute
44+
var control = ExtendedControlHelper.CreateControl(attribute, propertyType);
45+
```
46+
47+
Features:
48+
- Factory method invocation (static and instance methods)
49+
- Control instantiation via reflection
50+
- Binding property resolution
51+
52+
### ControlFactoryBase
53+
54+
Base class for control factories providing common functionality:
55+
56+
```csharp
57+
public class MyControlFactory : ControlFactoryBase
58+
{
59+
// Inherits:
60+
// - Property value access via IPropertyValueAccessor
61+
// - Dynamic read-only state evaluation
62+
// - CanExecute delegate evaluation
63+
// - Type resolution from name strings
64+
}
65+
```
66+
67+
## Usage
68+
69+
This package is primarily used internally by the framework extensions. If you're creating a custom extension, you can reference it directly:
70+
71+
```csharp
72+
using AutoSettingUI.Extension.Shared;
73+
74+
public class MyCustomPanel
75+
{
76+
protected bool ValidateProperty(PropertyInfo prop, object? value, object target)
77+
{
78+
return ValidationHelper.ValidateValue(prop, value, target, out _);
79+
}
80+
81+
protected object? CreateExtendedControl(ControlBindingAttribute attr, Type propertyType)
82+
{
83+
return ExtendedControlHelper.CreateControl(attr, propertyType);
84+
}
85+
}
86+
```
87+
88+
## Related Packages
89+
90+
- **AutoSettingUI.Core** - Core attributes and interfaces
91+
- **AutoSettingUI.Generator** - Roslyn source generator
92+
- **AutoSettingUI.Avalonia** - Avalonia UI panel
93+
- **AutoSettingUI.Ursa** - Ursa-themed Avalonia panel
94+
- **AutoSettingUI.WPF** - WPF panel
95+
96+
## Documentation
97+
98+
- [GitHub Repository](https://github.com/StarryXYJ/AutoSettingUI)
99+
- [Architecture Documentation](https://github.com/StarryXYJ/AutoSettingUI/blob/main/manual/architecture.md)
100+
101+
## License
102+
103+
MIT

‎README.md‎

Lines changed: 181 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,34 @@
99
- ⚡ **AOT-compatible** — An Incremental Roslyn Source Generator (`AutoSettingUI.Generator`) generates a reflection-free `ISettingDescriptorProvider` + `IPropertyValueAccessor` at compile time, enabling full Native AOT and trimming support.
1010
- 🔌 **Extensible** — Inject your own `ISettingDescriptorProvider` or `IPropertyValueAccessor` to override the defaults.
1111
- 🧭 **Built-in navigation** — Sections are listed in a sidebar tree; clicking navigates directly to the section.
12+
- 🎯 **Extended Controls** — Built-in support for ColorPicker, DatePicker, TimePicker, NumericUpDown, and more.
13+
14+
## Installation
15+
16+
Install the package for your preferred UI framework:
17+
18+
```xml
19+
<!-- Avalonia -->
20+
<PackageReference Include="AutoSettingUI.Avalonia" Version="1.0.0" />
21+
22+
<!-- Ursa (Avalonia with Ursa theme) -->
23+
<PackageReference Include="AutoSettingUI.Ursa" Version="1.0.0" />
24+
25+
<!-- WPF -->
26+
<PackageReference Include="AutoSettingUI.WPF" Version="1.0.0" />
27+
```
28+
29+
> **Note:** `AutoSettingUI.Core` and `AutoSettingUI.Generator` are automatically included as dependencies.
1230
1331
## Quick Start
1432

33+
### 1. Define Your Settings Class
34+
1535
```csharp
36+
using AutoSettingUI.Core.Attributes;
37+
1638
[SettingUI(Category = "General", Order = 0)]
39+
[MainHeader("Application Settings")]
1740
public class AppSettings
1841
{
1942
[Title("App Name")]
@@ -24,32 +47,177 @@ public class AppSettings
2447

2548
[Title("Volume"), Range(0, 100)]
2649
public int Volume { get; set; } = 50;
50+
51+
[Title("Language")]
52+
[ItemsSource(typeof(AppSettings), nameof(AvailableLanguages))]
53+
public string Language { get; set; } = "en-US";
54+
55+
public static string[] AvailableLanguages => ["en-US", "zh-CN", "ja-JP"];
2756
}
2857
```
2958

59+
### 2. Add the Panel to Your UI
60+
61+
#### Avalonia
62+
63+
```xml
64+
<Window xmlns:auto="clr-namespace:AutoSettingUI.Avalonia.Controls;assembly=AutoSettingUI.Avalonia">
65+
<auto:AvaloniaAutoSettingPanel
66+
Title="Settings"
67+
Targets="{Binding SettingsList}"
68+
ShowNavigation="True" />
69+
</Window>
70+
```
71+
72+
#### Ursa
73+
3074
```xml
31-
<!-- Avalonia -->
32-
<avalonia:AvaloniaAutoSettingPanel
33-
Targets="{Binding Settings}"
34-
Title="Application Settings" />
75+
<Window xmlns:ursa="clr-namespace:AutoSettingUI.Ursa.Controls;assembly=AutoSettingUI.Ursa">
76+
<ursa:UrsaAutoSettingPanel
77+
Title="Settings"
78+
Targets="{Binding SettingsList}"
79+
UseCardBorderTheme="True" />
80+
</Window>
3581
```
3682

37-
The source generator will automatically create `GeneratedSettingProvider` in your project. Pass it in for full AOT:
83+
#### WPF
84+
85+
```xml
86+
<Window xmlns:auto="clr-namespace:AutoSettingUI.WPF.Controls;assembly=AutoSettingUI.WPF">
87+
<auto:WpfAutoSettingPanel
88+
Title="Settings"
89+
Targets="{Binding SettingsList}"
90+
ShowNavigation="True" />
91+
</Window>
92+
```
93+
94+
### 3. AOT Support (Optional)
95+
96+
For Native AOT or trimming support, use the generated provider:
3897

3998
```csharp
99+
// The source generator creates this class automatically
40100
panel.DescriptorProvider = new AutoSettingUI.Generated.GeneratedSettingProvider();
41-
panel.PropertyAccessor = new AutoSettingUI.Generated.GeneratedSettingProvider();
101+
panel.PropertyAccessor = new AutoSettingUI.Generated.GeneratedSettingProvider();
102+
```
103+
104+
## Extended Controls
105+
106+
AutoSettingUI provides extended control attributes for specialized inputs:
107+
108+
### ColorPicker (Avalonia/Ursa)
109+
110+
> **Important:** ColorPicker requires additional style reference in `App.axaml`:
111+
112+
```xml
113+
<Application.Styles>
114+
<FluentTheme />
115+
<StyleInclude Source="avares://Avalonia.Controls.ColorPicker/Themes/Fluent/Fluent.xaml"/>
116+
</Application.Styles>
117+
```
118+
119+
Usage:
120+
121+
```csharp
122+
using Avalonia.Media;
123+
using AutoSettingUI.Avalonia.Attributes; // or AutoSettingUI.Ursa.Attributes
124+
125+
[SettingUI]
126+
public class ThemeSettings
127+
{
128+
[Title("Accent Color")]
129+
[ColorPicker]
130+
public Color AccentColor { get; set; } = Colors.DodgerBlue;
131+
}
132+
```
133+
134+
### Other Extended Controls
135+
136+
| Attribute | Framework | Description |
137+
| ------------------ | --------- | ------------------------------------ |
138+
| `[CheckBox]` | All | Boolean property as CheckBox |
139+
| `[DatePicker]` | All | DateTime with date picker |
140+
| `[TimePicker]` | All | TimeSpan with time picker |
141+
| `[NumericUpDown]` | Avalonia | Numeric input with up/down buttons |
142+
| `[ColorPicker]` | Avalonia | Color selection |
143+
| `[TagInput]` | Ursa | String collection as tags |
144+
| `[IPv4Box]` | Ursa | IP address input |
145+
146+
## Available Attributes
147+
148+
| Attribute | Target | Description |
149+
| ------------------ | --------- | ------------------------------------------ |
150+
| `[SettingUI]` | Class | Marks class for UI generation |
151+
| `[MainHeader]` | Class | Sets section header title |
152+
| `[Title]` | Property | Sets property label |
153+
| `[SubHeader]` | Property | Creates a sub-section |
154+
| `[Hide]` | Property | Excludes from UI |
155+
| `[Range]` | Property | Numeric range (renders slider) |
156+
| `[ItemsSource]` | Property | Dropdown items source |
157+
| `[ControlBinding]` | Property | Custom control binding |
158+
| `[ReadOnly]` | Property | Makes property read-only |
159+
| `[Password]` | Property | Masks input (password box) |
160+
| `[Placeholder]` | Property | Placeholder text for input |
161+
| `[Layout]` | Property | Custom layout (width, height) |
162+
| `[Validation]` | Property | Custom validation method |
163+
164+
## Custom Control Binding
165+
166+
Create custom control attributes by inheriting from `ControlBindingAttribute`:
167+
168+
```csharp
169+
[AttributeUsage(AttributeTargets.Property)]
170+
public sealed class DatePickerAttribute : ControlBindingAttribute
171+
{
172+
public DatePickerAttribute()
173+
: base(typeof(CalendarDatePicker), "SelectedDate")
174+
{
175+
}
176+
}
177+
```
178+
179+
For complex controls, use factory methods:
180+
181+
```csharp
182+
public sealed class NumericUpDownAttribute : ControlBindingAttribute
183+
{
184+
public double Minimum { get; set; } = 0;
185+
public double Maximum { get; set; } = 100;
186+
187+
public NumericUpDownAttribute()
188+
: base(typeof(NumericUpDown), "Value", nameof(CreateControl))
189+
{
190+
}
191+
192+
public Control CreateControl(Type propertyType)
193+
{
194+
return new NumericUpDown
195+
{
196+
Minimum = (decimal)Minimum,
197+
Maximum = (decimal)Maximum
198+
};
199+
}
200+
}
42201
```
43202

44203
## Packages
45204

46-
| Package | Description |
47-
| ------------------------- | ----------------------------------------------- |
48-
| `AutoSettingUI.Core` | Attributes, interfaces, and models. |
49-
| `AutoSettingUI.Generator` | Roslyn Incremental Source Generator (Analyzer). |
50-
| `AutoSettingUI.Avalonia` | Avalonia UI panel extension. |
51-
| `AutoSettingUI.Ursa` | Ursa-themed Avalonia panel extension. |
52-
| `AutoSettingUI.WPF` | WPF panel extension. |
205+
| Package | Description |
206+
| ---------------------------- | ----------------------------------------------- |
207+
| `AutoSettingUI.Core` | Attributes, interfaces, and models. |
208+
| `AutoSettingUI.Generator` | Roslyn Incremental Source Generator (Analyzer). |
209+
| `AutoSettingUI.Extension.Shared` | Shared validation and control helpers. |
210+
| `AutoSettingUI.Avalonia` | Avalonia UI panel extension. |
211+
| `AutoSettingUI.Ursa` | Ursa-themed Avalonia panel extension. |
212+
| `AutoSettingUI.WPF` | WPF panel extension. |
213+
214+
## Documentation
215+
216+
- [Architecture](manual/architecture.md) — Project structure and data flow
217+
- [Attributes Reference](manual/attributes.md) — All available attributes
218+
- [Framework Extensions](manual/extensions.md) — Framework-specific usage
219+
- [AOT Source Generator](manual/aot-source-generator.md) — AOT support details
220+
53221

54222
## License
55223

0 commit comments

Comments
 (0)