SuncodeSoftware.SuperSDK.UI 5.0.3

SuperSDK.UI

Avalonia UI 通用组件库，提供统一风格的 UI 组件和工具。

🎯 核心功能

1. 窗口组件

• GzTitleBarCtrl - 统一风格的自定义标题栏（必须使用）
• GzAboutView - 关于窗口
• GzLoggerView - 日志查看器
• GzSqlDebugView - SQL 调试工具

2. 自定义按钮组件（支持主题切换）

所有按钮默认 Auto 模式，自动跟随全局主题切换（Dark/Light）

• GzConfirmButton - 确认按钮（对勾图标，绿色）
• GzSaveButton - 保存按钮（对勾图标，绿色）
• GzDeleteButton - 删除按钮（X 图标，红色）
• GzCancelButton - 取消按钮（撤销箭头图标，橙色）
• GzAddButton - 添加按钮（加号图标，绿色）
• GzEditButton - 编辑按钮（笔图标，橙色）
• GzOpenFolderButton - 打开文件夹按钮（文件夹图标，橙黄色）
• GzFilterButton - 过滤按钮（漏斗图标，青色）
• GzGenerateButton - 生成按钮（闪电图标，粉色）
• GzLoadButton - 加载/下载按钮（下箭头图标，蓝色）
• GzRefreshButton - 刷新按钮（循环箭头图标，蓝色）
• GzRunButton - 运行按钮（播放图标，绿色）
• GzPreviewButton - 预览按钮（眼睛图标，紫色）
• GzSettingsButton - 设置按钮（齿轮图标，灰色）
• GzMoveUpButton - 上移按钮（向上箭头图标，蓝色）
• GzMoveDownButton - 下移按钮（向下箭头图标，蓝色）
• GzMoveLeftButton - 左移按钮（向左箭头图标，蓝色）
• GzMoveRightButton - 右移按钮（向右箭头图标，蓝色）
• GzSetDataButton - 设置数据按钮（列表图标，蓝色）
• GzSetHeaderButton - 设置表头按钮（文档表头图标，蓝色）
• GzSelectAllButton - 全选按钮（勾选框图标，蓝色）
• GzDeselectAllButton - 全不选按钮（空框图标，蓝色）

🎨 按钮色系统计表

所有按钮均支持 Dark/Light 主题自动切换，以下是各按钮使用的颜色（适用于自定义控件开发）：

色系使用建议：

• 绿色 - 表示成功、确认、添加等正向操作
• 红色 - 表示删除、危险、错误等警示操作
• 橙色 - 表示编辑、取消、警告等中性操作
• 蓝色 - 表示数据操作、导航、信息展示等常规操作
• 紫色 - 表示预览、查看等非修改操作
• 灰色 - 表示设置、配置等系统功能

3. 进度条组件

• GzProgressBar - 带渐变效果的进度条，支持主题切换（Dark/Light/Auto）

3. MVVM 基础

• ViewModelBase - ReactiveUI 基类，集成 MessageBus 自动清理

4. 主题管理

• ThemeManager - 全局主题管理器，支持 Dark/Light 模式切换
• UITheme - 主题枚举（Dark/Light/Auto）

5. 通知与对话框

• GzNotification - 轻量级通知（右上角弹窗）
• UIHelper - 模态对话框（错误/警告/信息）

6. 工具类

• UIThreadHelper - UI 线程调度

📐 UI 风格规范

✅ 必须遵守的规范

1. 使用 GzTitleBarCtrl 作为标题栏

<Window SystemDecorations="None"
        Background="Transparent"
        TransparencyLevelHint="Transparent">
    <Border Background="{DynamicResource SemiColorBackground1}" 
            CornerRadius="6"
            BorderBrush="{DynamicResource SemiColorBorder}"
            BorderThickness="1">
        <Grid RowDefinitions="Auto,*">
            <views:GzTitleBarCtrl Grid.Row="0"
                                  Title="我的窗口"
                                  IsMaxEnabled="True"
                                  IsMinEnabled="True"/>
            <ContentControl Grid.Row="1" Content="{Binding}" />
        </Grid>
    </Border>
</Window>

2. 使用 DynamicResource 适配主题

❌ 错误示例（硬编码颜色）：

<Border Background="#1e1e1e" BorderBrush="#3f3f46">
    <TextBlock Foreground="#FFFFFF" Text="标题" />
</Border>

✅ 正确示例（使用 DynamicResource）：

<Border Background="{DynamicResource SemiColorBackground1}" 
        BorderBrush="{DynamicResource SemiColorBorder}">
    <TextBlock Foreground="{DynamicResource SemiColorText0}" Text="标题" />
</Border>

🎨 Semi.Avalonia 主题资源

🖱️ 交互样式示例

ListBox Hover 和 Selected：

<ListBox.Styles>
    <Style Selector="ListBoxItem:pointerover /template/ ContentPresenter">
        <Setter Property="Background" Value="{DynamicResource SemiColorFill0}"/>
    </Style>
    <Style Selector="ListBoxItem:selected /template/ ContentPresenter">
        <Setter Property="Background" Value="{DynamicResource SemiColorPrimary}"/>
    </Style>
</ListBox.Styles>

🚀 组件使用

1. 主题管理

切换主题

在 SuperApp 中切换主题：

// 切换主题（Dark ↔ Light）
SuperApp.ToggleTheme();

// 获取当前主题
var currentTheme = ThemeManager.CurrentTheme; // Dark 或 Light

手动设置主题：

// 设置为深色主题
ThemeManager.CurrentTheme = UITheme.Dark;

// 设置为浅色主题
ThemeManager.CurrentTheme = UITheme.Light;

获取主题颜色（兼容 ThemeManager）

使用 GetAvaloniaDynamicColor 方法：

如果你的组件需要在 C# 代码中根据当前主题获取颜色，使用 ThemeManager.GetAvaloniaDynamicColor() 方法：

using SuperSDK.UI;
using Avalonia.Media;

// 获取当前主题的文字颜色
var textColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorText0");
if (textColor.HasValue)
{
    var brush = new SolidColorBrush(textColor.Value);
    myTextBlock.Foreground = brush;
}

// 获取背景色
var bgColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorBackground1");
if (bgColor.HasValue)
{
    myBorder.Background = new SolidColorBrush(bgColor.Value);
}

// 获取边框色
var borderColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorBorder");

// 获取语义色
var primaryColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorPrimary");
var successColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorSuccess");
var dangerColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorDanger");

支持的颜色资源键：

响应主题变更：

// 订阅主题变更事件
ThemeManager.ThemeChanged += OnThemeChanged;

private void OnThemeChanged(object? sender, UITheme newTheme)
{
    // 主题变更时更新颜色
    var textColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorText0");
    if (textColor.HasValue)
    {
        myTextBlock.Foreground = new SolidColorBrush(textColor.Value);
    }
}

// 取消订阅（避免内存泄漏）
protected override void OnUnloaded(RoutedEventArgs e)
{
    ThemeManager.ThemeChanged -= OnThemeChanged;
}

实用示例：创建主题感知的自定义控件

public class MyCustomControl : UserControl
{
    private Border _border;
    private TextBlock _textBlock;

    public MyCustomControl()
    {
        _border = new Border();
        _textBlock = new TextBlock { Text = "Hello" };
        _border.Child = _textBlock;
        Content = _border;

        // 初始化颜色
        UpdateColors();

        // 订阅主题变更
        ThemeManager.ThemeChanged += (s, e) => UpdateColors();
    }

    private void UpdateColors()
    {
        // 根据当前主题更新颜色
        var bgColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorBackground1");
        var textColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorText0");
        var borderColor = ThemeManager.GetAvaloniaDynamicColor("SemiColorBorder");

        if (bgColor.HasValue)
            _border.Background = new SolidColorBrush(bgColor.Value);
        
        if (textColor.HasValue)
            _textBlock.Foreground = new SolidColorBrush(textColor.Value);
        
        if (borderColor.HasValue)
        {
            _border.BorderBrush = new SolidColorBrush(borderColor.Value);
            _border.BorderThickness = new Thickness(1);
        }
    }
}

2. 自定义按钮

基础使用（自动跟随主题）：

<Window xmlns:controls="clr-namespace:SuperSDK.UI.Controls;assembly=SuperSDK.UI">
    <StackPanel Spacing="10" Orientation="Horizontal">
        
        <controls:GzConfirmButton Command="{Binding ConfirmCommand}"/>
        
        
        <controls:GzSaveButton Command="{Binding SaveCommand}"/>
        
        
        <controls:GzDeleteButton Command="{Binding DeleteCommand}"/>
        
        
        <controls:GzAddButton Command="{Binding AddCommand}"/>
        
        
        <controls:GzEditButton Command="{Binding EditCommand}"/>
        
        
        <controls:GzRefreshButton Command="{Binding RefreshCommand}"/>
        
        
        <controls:GzRunButton Command="{Binding RunCommand}"/>
        
        
        <controls:GzPreviewButton Command="{Binding PreviewCommand}"/>
        
        
        <controls:GzOpenFolderButton Command="{Binding OpenFolderCommand}"/>
        
        
        <controls:GzFilterButton Command="{Binding FilterCommand}"/>
        
        
        <controls:GzGenerateButton Command="{Binding GenerateCommand}"/>
        
        
        <controls:GzLoadButton Command="{Binding LoadCommand}"/>
        
        
        <controls:GzSettingsButton Command="{Binding SettingsCommand}"/>
        
        
        <controls:GzMoveUpButton Command="{Binding MoveUpCommand}"/>
        
        
        <controls:GzMoveDownButton Command="{Binding MoveDownCommand}"/>
        
        
        <controls:GzMoveLeftButton Command="{Binding MoveLeftCommand}"/>
        
        
        <controls:GzMoveRightButton Command="{Binding MoveRightCommand}"/>
        
        
        <controls:GzSetDataButton Command="{Binding SetDataCommand}"/>
        
        
        <controls:GzSetHeaderButton Command="{Binding SetHeaderCommand}"/>
    </StackPanel>
</Window>

自定义按钮大小：

<controls:GzSaveButton />


<controls:GzSaveButton ButtonSize="24"/>


<controls:GzEditButton ButtonSize="32"/>


<controls:GzRefreshButton ButtonSize="56"/>

固定按钮主题（不跟随全局主题）：

<controls:GzSaveButton BtnTheme="Dark"/>


<controls:GzDeleteButton BtnTheme="Light"/>


<controls:GzAddButton BtnTheme="Auto"/>

3. 进度条 (GzProgressBar)

基础使用（自动跟随主题）：

<controls:GzProgressBar Value="65" 
                       Maximum="100"
                       Text="正在加载..."
                       BarHeight="28"/>

完整属性示例：

<controls:GzProgressBar Value="{Binding CurrentValue}" 
                       Maximum="100"
                       Text="{Binding StatusText}"
                       ShowPercentage="True"
                       BarHeight="32"
                       BarCornerRadius="16"
                       BarTheme="Auto"/>

固定进度条主题：

<controls:GzProgressBar Value="50" 
                       Maximum="100"
                       BarTheme="Dark"
                       Text="深色进度条"/>


<controls:GzProgressBar Value="75" 
                       Maximum="100"
                       BarTheme="Light"
                       Text="浅色进度条"/>


<controls:GzProgressBar Value="30" 
                       Maximum="100"
                       BarTheme="Auto"
                       Text="自动跟随主题"/>

自定义颜色：

<controls:GzProgressBar Value="60" 
                       Maximum="100"
                       BackgroundColor="#2A2A2A"
                       ProgressColor="#52C176"
                       BarBorderBrush="#404040"
                       BarBorderThickness="1"
                       BarHeight="24"/>

属性说明： | 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | Value | double | 0.0 | 当前进度值 | | Maximum | double | 100.0 | 最大值 | | Text | string | "" | 进度条下方描述文字 | | ShowPercentage | bool | true | 是否显示百分比 | | BarHeight | double | 24.0 | 进度条高度 | | BarCornerRadius | CornerRadius | 12.0 | 圆角半径 | | BarTheme | ProgressBarTheme | Auto | 主题模式（Dark/Light/Auto）| | BackgroundColor | IBrush? | null | 自定义背景色（覆盖主题）| | ProgressColor | IBrush? | null | 自定义进度色（覆盖主题）| | BarBorderBrush | IBrush? | null | 自定义边框色 | | BarBorderThickness | Thickness | 0 | 边框粗细 |

4. ViewModelBase

public class MyViewModel : ViewModelBase
{
    private string _name = "";
    public string Name
    {
        get => _name;
        set => this.RaiseAndSetIfChanged(ref _name, value);
    }
    
    public override void RegisterMsg()
    {
        MessageBus.Subscribe<MyMessage>(this, OnMyMessage);
    }
}

5. GzNotification 通知

// 显示通知
GzNotification.Instance.Show(
    "操作成功", 
    "数据已保存", 
    NotificationType.Success
);

6. UIHelper 对话框

// 错误对话框
await UIHelper.GzShowErrorMsg(
    "加载错误", 
    "文件不存在",
    parentWindow: this
);

// 警告对话框
await UIHelper.GzShowWarningMsg("警告", "此操作无法撤销");

// 信息对话框
await UIHelper.GzShowInfoMsg("提示", "文件已保存");

// 确认对话框（返回 true/false）
var result = await UIHelper.GzShowConfirmDialog(
    "确认删除", 
    "是否确定删除该项？",
    this
);
if (result)
{
    // 用户点击确定
}

5. UIThreadHelper

// UI 线程执行
await UIThreadHelper.RunOnUIThread(() =>
{
    StatusText = "完成";
});

6. 窗口关闭事件处理

public partial class MyWindow : Window
{
    public MyWindow()
    {
        InitializeComponent();
        
        // 关闭前确认
        Closing += async (sender, args) =>
        {
            args.Cancel = true;
            var result = await UIHelper.GzShowConfirmDialog(
                "确认", "是否关闭？", this
            );
            if (result)
            {
                Closing -= Closing;
                Close();
            }
        };
    }
}

📝 完整窗口模板

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:views="clr-namespace:SuperSDK.UI.Views;assembly=SuperSDK.UI"
        SystemDecorations="None"
        Background="Transparent"
        TransparencyLevelHint="Transparent"
        CanResize="True">
    
    <Border Background="{DynamicResource SemiColorBackground1}"
            BorderBrush="{DynamicResource SemiColorBorder}"
            BorderThickness="1"
            CornerRadius="6">
        <Grid RowDefinitions="Auto,*,Auto">
            
            <views:GzTitleBarCtrl Grid.Row="0"
                                  Title="我的应用"
                                  IsMaxEnabled="True"
                                  IsMinEnabled="True"/>
            
            
            <Border Grid.Row="1" 
                    Background="{DynamicResource SemiColorBackground2}"
                    Padding="20">
                <TextBlock Text="内容"
                          Foreground="{DynamicResource SemiColorText0}"/>
            </Border>
            
            
            <Border Grid.Row="2"
                    Background="{DynamicResource SemiColorBackground0}"
                    BorderBrush="{DynamicResource SemiColorBorder}"
                    BorderThickness="0,1,0,0"
                    Padding="16,8">
                <Button Content="确定" Classes="Primary"/>
            </Border>
        </Grid>
    </Border>
</Window>