SuncodeSoftware.SuperSDK.UI 3.3.0

SuperSDK.UI

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

🎯 核心功能

1. 窗口组件

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

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

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

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

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;

2. 自定义按钮

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

<Window xmlns:controls="clr-namespace:SuperSDK.UI.Controls;assembly=SuperSDK.UI">
    <StackPanel Spacing="10" Orientation="Horizontal">
        
        <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>