support customed display order

StarryXYJ · StarryXYJ · commit e91a1db7ca92 · 2026-03-20T19:08:08.000+08:00
diff --git a/Demo/AutoSettingUI.Ursa.Demo/Models/ApplicationSettings.cs b/Demo/AutoSettingUI.Ursa.Demo/Models/ApplicationSettings.cs
@@ -262,14 +262,17 @@ public class NetworkSettings
     public int Port { get; set; } = 8080;
 
     [Title("Use HTTPS")]
+    [DisplayOrder(-1)]
     public bool UseHttps { get; set; } = false;
 
     [SubHeader("Authentication")]
     [Title("Username")]
+    [DisplayOrder(1)]
     public string Username { get; set; } = "";
 
     [Title("Timeout (seconds)")]
     [Range(1, 300)]
+    [DisplayOrder(1)]
     public int Timeout { get; set; } = 30;
 
     [SubHeader("Actions")]
diff --git a/README.md b/README.md
@@ -311,6 +311,7 @@ public class ThemeSettings
 | `[Placeholder]`    | Property  | Placeholder text for input                 |
 | `[Layout]`         | Property  | Custom layout (width, height)              |
 | `[Validation]`     | Property  | Custom validation method                   |
+| `[DisplayOrder]`   | Property  | Controls display order (lower = first)     |
 
 ## Custom Control Binding
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -237,6 +237,7 @@ public class ThemeSettings
 | `[Placeholder]`    | 属性      | 输入框占位文本             |
 | `[Layout]`         | 属性      | 自定义布局（宽度、高度）   |
 | `[Validation]`     | 属性      | 自定义验证方法             |
+| `[DisplayOrder]`   | 属性      | 控制显示顺序（数值小在前）|
 
 ## 自定义控件绑定
 
diff --git a/manual/attributes.md b/manual/attributes.md
@@ -147,3 +147,35 @@ Specifies a custom control type to use for rendering this specific property.
 [ControlBinding(typeof(ColorPicker), BindingProperty = "Color")]
 public Color AccentColor { get; set; }
 ```
+
+---
+
+## `[DisplayOrder]`
+
+Controls the display order of properties within a settings class. Properties with lower order values are displayed first. Properties with the same order value are displayed in their declaration order.
+
+**Target:** `Property`
+
+| Parameter      | Type  | Default | Description                                    |
+| -------------- | ----- | ------- | ---------------------------------------------- |
+| `order` (ctor) | `int` | `0`     | Display order value. Lower values appear first. |
+
+```csharp
+[SettingUI]
+public class AppSettings
+{
+    // Displayed third (order = 2)
+    [DisplayOrder(2)]
+    [Title("Advanced Options")]
+    public bool EnableAdvanced { get; set; }
+
+    // Displayed first (order = 0, default)
+    [Title("Application Name")]
+    public string AppName { get; set; }
+
+    // Displayed second (order = 1)
+    [DisplayOrder(1)]
+    [Title("Version")]
+    public string Version { get; set; }
+}
+```
diff --git a/src/AutoSettingUI.Core/Attributes/DisplayOrderAttribute.cs b/src/AutoSettingUI.Core/Attributes/DisplayOrderAttribute.cs
@@ -0,0 +1,26 @@
+namespace AutoSettingUI.Core.Attributes;
+
+/// <summary>
+/// Specifies the display order of a property in the settings UI.
+/// Properties with lower order values are displayed first.
+/// Properties with the same order value are displayed in their declaration order.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, Inherited = false, AllowMultiple = false)]
+public sealed class DisplayOrderAttribute : Attribute
+{
+    /// <summary>
+    /// Gets the display order value.
+    /// Lower values are displayed first.
+    /// Default is 0.
+    /// </summary>
+    public int Order { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DisplayOrderAttribute"/> class.
+    /// </summary>
+    /// <param name="order">The display order value. Lower values are displayed first.</param>
+    public DisplayOrderAttribute(int order)
+    {
+        Order = order;
+    }
+}
diff --git a/src/AutoSettingUI.Core/Models/PropertyDescriptor.cs b/src/AutoSettingUI.Core/Models/PropertyDescriptor.cs
@@ -184,6 +184,13 @@ public sealed class PropertyDescriptor
     /// </summary>
     public double NumericIncrement { get; }
 
+    /// <summary>
+    /// Gets the display order of the property.
+    /// Lower values are displayed first.
+    /// Properties with the same order are displayed in their declaration order.
+    /// </summary>
+    public int DisplayOrder { get; }
+
     /// <summary>
     /// Initializes a new instance of the <see cref="PropertyDescriptor"/> class.
     /// </summary>
@@ -221,7 +228,8 @@ public PropertyDescriptor(
         bool isNumericUpDown = false,
         double numericMinimum = 0,
         double numericMaximum = 0,
-        double numericIncrement = 0)
+        double numericIncrement = 0,
+        int displayOrder = 0)
     {
         PropertyName = propertyName;
         DisplayName = displayName;
@@ -257,6 +265,7 @@ public PropertyDescriptor(
         NumericMinimum = numericMinimum;
         NumericMaximum = numericMaximum;
         NumericIncrement = numericIncrement;
+        DisplayOrder = displayOrder;
     }
 }
 
diff --git a/src/AutoSettingUI.Core/Providers/ReflectionSettingDescriptorProvider.cs b/src/AutoSettingUI.Core/Providers/ReflectionSettingDescriptorProvider.cs
@@ -82,8 +82,26 @@ public bool HasDescriptor(string typeName)
         List<PropertyDescriptor>? currentSubProps = null;
         string? currentSubHeader = null;
 
-        foreach (var prop in type.GetProperties(BindingFlags.Public | BindingFlags.Instance))
+        // Get all properties with their declaration order
+        var props = type.GetProperties(BindingFlags.Public | BindingFlags.Instance)
+            .Select((prop, index) => new { Property = prop, DeclarationOrder = index })
+            .ToList();
+
+        // Sort by DisplayOrder, then by declaration order
+        var sortedProps = props
+            .Select(p => new
+            {
+                p.Property,
+                p.DeclarationOrder,
+                DisplayOrder = p.Property.GetCustomAttribute<DisplayOrderAttribute>()?.Order ?? 0
+            })
+            .OrderBy(p => p.DisplayOrder)
+            .ThenBy(p => p.DeclarationOrder)
+            .ToList();
+
+        foreach (var item in sortedProps)
         {
+            var prop = item.Property;
             // Skip hidden properties
             if (prop.GetCustomAttribute<HideAttribute>() is not null)
                 continue;
@@ -111,6 +129,7 @@ public bool HasDescriptor(string typeName)
             var placeholderAttr = prop.GetCustomAttribute<PlaceholderAttribute>();
             var descriptionAttr = prop.GetCustomAttribute<DescriptionAttribute>();
             var passwordAttr = prop.GetCustomAttribute<PasswordAttribute>();
+            var displayOrderAttr = prop.GetCustomAttribute<DisplayOrderAttribute>();
 
             // Pre-compute enum values to avoid runtime Enum.GetValues in non-AOT path
             string[]? enumValues = null;
@@ -166,7 +185,8 @@ public bool HasDescriptor(string typeName)
                 false,
                 0,
                 0,
-                0
+                0,
+                displayOrderAttr?.Order ?? 0
             );
 
             if (currentSubProps is not null)
diff --git a/src/AutoSettingUI.Generator/Incremental/AutoSettingGenerator.cs b/src/AutoSettingUI.Generator/Incremental/AutoSettingGenerator.cs
@@ -33,6 +33,7 @@ public class AutoSettingGenerator : IIncrementalGenerator
     private const string PasswordAttributeName = "PasswordAttribute";
     private const string NumericUpDownAttributeName = "NumericUpDownAttribute"; // Special handling needed - type depends on property type
     private const string ControlBindingDefaultsAttributeName = "ControlBindingDefaultsAttribute";
+    private const string DisplayOrderAttributeName = "DisplayOrderAttribute";
 
     // Diagnostic descriptors
     private static readonly DiagnosticDescriptor NonPublicClassWarning = new(
@@ -333,8 +334,17 @@ private static void AppendRegisterMethod(StringBuilder sb, INamedTypeSymbol cls,
         sb.AppendLine("            string? currentSubTitle = null;");
         sb.AppendLine();
 
-        foreach (var prop in GetPublicInstanceProperties(cls, context))
+        var allProps = GetPublicInstanceProperties(cls, context).ToList();
+        var propsWithOrder = allProps.Select((prop, index) => new
         {
+            Property = prop,
+            DisplayOrder = GetDisplayOrder(prop),
+            DeclarationOrder = prop.DeclarationOrder
+        }).ToList();
+
+        foreach (var item in propsWithOrder.OrderBy(p => p.DisplayOrder).ThenBy(p => p.DeclarationOrder))
+        {
+            var prop = item.Property;
             if (GetAttr(prop, HideAttributeName) != null) continue;
 
             var subHeaderAttr = GetAttr(prop, SubHeaderAttributeName);
@@ -514,6 +524,15 @@ private static void AppendRegisterMethod(StringBuilder sb, INamedTypeSymbol cls,
                 numericInc = TryGetNamedArgDouble(cbAttr, "Increment") ?? 1.0;
             }
 
+            // DisplayOrder
+            var displayOrderAttr = GetAttr(prop, DisplayOrderAttributeName);
+            int displayOrder = 0;
+            if (displayOrderAttr != null && displayOrderAttr.ConstructorArguments.Length > 0)
+            {
+                if (displayOrderAttr.ConstructorArguments[0].Value is int orderVal)
+                    displayOrder = orderVal;
+            }
+
             // CollectionEditor
             var collEditorAttr = GetAttr(prop, CollectionEditorAttributeName);
             string? collEditorTypeName = null;
@@ -615,7 +634,8 @@ private static void AppendRegisterMethod(StringBuilder sb, INamedTypeSymbol cls,
             sb.AppendLine($"                {(isNumericUpDown ? "true" : "false")},");
             sb.AppendLine($"                {numericMin},");
             sb.AppendLine($"                {numericMax},");
-            sb.AppendLine($"                {numericInc});");
+            sb.AppendLine($"                {numericInc},");
+            sb.AppendLine($"                {displayOrder});");
 
             var varName = $"pd_{safeName}_{EscapeName(prop.Name)}";
             sb.AppendLine($"            if (currentSub != null) currentSub.Add({varName}); else directProps.Add({varName});");
@@ -676,6 +696,7 @@ private sealed class PropertyInfo
         public Location? Location { get; }
         public bool IsFromObservableProperty { get; }
         public IFieldSymbol? SourceField { get; }
+        public int DeclarationOrder { get; }
 
         public PropertyInfo(
             string name,
@@ -685,7 +706,8 @@ public PropertyInfo(
             ImmutableArray<AttributeData> attributes,
             Location? location,
             bool isFromObservableProperty,
-            IFieldSymbol? sourceField)
+            IFieldSymbol? sourceField,
+            int declarationOrder = 0)
         {
             Name = name;
             Type = type;
@@ -695,11 +717,13 @@ public PropertyInfo(
             Location = location;
             IsFromObservableProperty = isFromObservableProperty;
             SourceField = sourceField;
+            DeclarationOrder = declarationOrder;
         }
     }
 
     private static IEnumerable<PropertyInfo> GetPublicInstanceProperties(INamedTypeSymbol cls, SourceProductionContext context)
     {
+        int order = 0;
         var properties = cls.GetMembers()
               .OfType<IPropertySymbol>()
               .Where(p => p.DeclaredAccessibility == Accessibility.Public && !p.IsStatic)
@@ -711,7 +735,8 @@ private static IEnumerable<PropertyInfo> GetPublicInstanceProperties(INamedTypeS
                   p.GetAttributes(),
                   p.Locations.FirstOrDefault(),
                   false,
-                  null));
+                  null,
+                  order++));
 
         var allFields = cls.GetMembers().OfType<IFieldSymbol>().ToList();
         var observableFields = new List<PropertyInfo>();
@@ -728,7 +753,8 @@ private static IEnumerable<PropertyInfo> GetPublicInstanceProperties(INamedTypeS
                     f.GetAttributes(),
                     f.Locations.FirstOrDefault(),
                     true,
-                    f));
+                    f,
+                    order++));
             }
         }
 
@@ -845,6 +871,17 @@ private static string GetPropertyNameFromField(string fieldName)
         });
     }
 
+    private static int GetDisplayOrder(PropertyInfo prop)
+    {
+        var attr = GetAttr(prop, DisplayOrderAttributeName);
+        if (attr != null && attr.ConstructorArguments.Length > 0)
+        {
+            if (attr.ConstructorArguments[0].Value is int orderVal)
+                return orderVal;
+        }
+        return 0;
+    }
+
     private static AttributeData? GetAttrInherited(ISymbol symbol, string baseName)
     {
         return symbol.GetAttributes().FirstOrDefault(a => 
