ui/docs/architecture/data-models.md

Data Models

核心数据模型定义了控件库中业务逻辑层的数据结构。这些模型在 UI 控件层和业务逻辑层之间共享。

---

PropertyItem

用途：表示 PropertyGrid 中的单个属性项，封装属性的元数据和值。

关键属性：

• Name（string）- 属性名称，显示在左列标签
• Value（object）- 属性当前值，支持双向绑定
• PropertyType（Type）- 属性的 .NET 类型，用于选择合适的编辑器
• IsReadOnly（bool）- 是否只读，只读属性禁用编辑器
• Category（string?）- 分组类别，用于属性分组显示
• Description（string?）- 属性描述，可选的辅助说明
• DisplayName（string?）- 显示名称，如果为空则使用 Name

C# 类定义：

namespace Penguin.AvaloniaUI.Controls.PropertyGrid
{
    /// <summary>
    /// 表示 PropertyGrid 中的单个属性项
    /// </summary>
    public class PropertyItem : ReactiveObject
    {
        private object? _value;

        /// <summary>
        /// 属性名称
        /// </summary>
        public string Name { get; set; } = string.Empty;

        /// <summary>
        /// 属性显示名称（如果为空则使用 Name）
        /// </summary>
        public string? DisplayName { get; set; }

        /// <summary>
        /// 属性值（支持双向绑定）
        /// </summary>
        public object? Value
        {
            get => _value;
            set => this.RaiseAndSetIfChanged(ref _value, value);
        }

        /// <summary>
        /// 属性的 .NET 类型
        /// </summary>
        public Type PropertyType { get; set; } = typeof(object);

        /// <summary>
        /// 是否只读
        /// </summary>
        public bool IsReadOnly { get; set; }

        /// <summary>
        /// 分组类别（可选）
        /// </summary>
        public string? Category { get; set; }

        /// <summary>
        /// 属性描述（可选）
        /// </summary>
        public string? Description { get; set; }

        /// <summary>
        /// 原始 PropertyInfo（用于反射场景）
        /// </summary>
        public PropertyInfo? PropertyInfo { get; set; }
    }
}

关系：

• PropertyGrid 包含多个 PropertyItem（ObservableCollection<PropertyItem>）
• PropertyItem 通过 PropertyType 决定使用哪个编辑器控件

---

GuideStep

用途：表示 UserGuide 引导流程中的单个步骤。

关键属性：

• TargetControl（Control?）- 引导目标控件，Overlay 将聚焦此控件
• Title（string）- 步骤标题，显示在引导提示框顶部
• Content（string）- 步骤内容/提示文本，支持基础富文本
• Position（TooltipPosition）- 提示框相对于目标控件的位置
• Order（int）- 步骤顺序，用于排序

C# 类定义：

namespace Penguin.AvaloniaUI.Controls.UserGuide
{
    /// <summary>
    /// 提示框位置枚举
    /// </summary>
    public enum TooltipPosition
    {
        Bottom,
        Top,
        Left,
        Right
    }

    /// <summary>
    /// 表示 UserGuide 中的单个引导步骤
    /// </summary>
    public class GuideStep : ReactiveObject
    {
        /// <summary>
        /// 引导目标控件（可选，如果为空则显示全屏提示）
        /// </summary>
        public Control? TargetControl { get; set; }

        /// <summary>
        /// 步骤标题
        /// </summary>
        public string Title { get; set; } = string.Empty;

        /// <summary>
        /// 步骤内容（支持基础富文本）
        /// </summary>
        public string Content { get; set; } = string.Empty;

        /// <summary>
        /// 提示框位置
        /// </summary>
        public TooltipPosition Position { get; set; } = TooltipPosition.Bottom;

        /// <summary>
        /// 步骤顺序（用于排序）
        /// </summary>
        public int Order { get; set; }

        /// <summary>
        /// 是否允许跳过此步骤
        /// </summary>
        public bool Skippable { get; set; } = true;
    }
}

关系：

• UserGuide 包含多个 GuideStep（ObservableCollection<GuideStep>）
• GuideStep 通过 TargetControl 关联到具体的 UI 控件
• Overlay 根据 TargetControl 的位置和大小进行挖空显示

---

ThemeInfo（辅助模型）

用途：表示主题信息，用于 ThemeManager 管理主题切换。

关键属性：

• ThemeType（ThemeType）- 主题类型枚举（Light、Dark）
• ResourceUri（Uri）- 主题资源字典的 URI

C# 类定义：

namespace Penguin.AvaloniaUI.Themes
{
    /// <summary>
    /// 主题类型枚举
    /// </summary>
    public enum ThemeType
    {
        Light,
        Dark
    }

    /// <summary>
    /// 主题信息
    /// </summary>
    public class ThemeInfo
    {
        /// <summary>
        /// 主题类型
        /// </summary>
        public ThemeType Type { get; set; }

        /// <summary>
        /// 主题资源字典 URI
        /// </summary>
        public Uri ResourceUri { get; set; } = null!;

        /// <summary>
        /// 主题显示名称
        /// </summary>
        public string DisplayName { get; set; } = string.Empty;
    }
}

关系：

• ThemeManager 使用 ThemeInfo 管理可用主题
• 主题切换时通过 ResourceUri 加载对应的 ResourceDictionary

---