更新readme · XFE Studio Git

@@ -1 +1,153 @@

1 # XFEExtension.NetCore.WinUIHelper

2

3

基于 .NET 8 的 WinUI 3 扩展库，提供了一系列便捷的帮助类、服务和扩展方法，旨在简化 WinUI 3 应用的开发流程。

4

5 ## 目录

6

7 - [特性](#特性)

8 - [快速开始](#快速开始)

9 - [1. 初始化配置](#1-初始化配置)

10 - [2. 构建 Shell 页](#2-构建-shell-页)

11 - [3. 使用服务](#3-使用服务)

12 - [核心功能](#核心功能)

13 - [ServiceManager](#servicemanager)

14 - [导航服务](#导航服务)

15 - [消息与对话框](#消息与对话框)

16 - [常用工具类](#常用工具类)

17

18 ## 特性

19

20 - **轻量级 IOC 容器**：内置 `ServiceManager`，支持服务注册与全局单例获取。

21 - **导航管理**：封装 `NavigationView` 和 `Frame`，提供基于 ViewModel 的导航体验。

22

- **UI交互服务**：提供 `DialogService`、`MessageService` (类似 InfoBar)、`LoadingService` 等常用交互服务。

23 - **MVVM 支持**：提供 `ObservableObject` 扩展及通用 ViewModel 基类。

24

25 ## 快速开始

26

27 ### 1. 初始化配置

28

29 在 `App.xaml.cs` 中进行初始化，包括注册页面和配置异常处理。

30

31 ```csharp

32 public App()

33 {

34 this.InitializeComponent();

35

36 // 设置应用主题

37 AppThemeHelper.Theme = ElementTheme.Dark;

38

39 // 注册导航页面 (PageManager)

40 // 必须在此处注册所有可通过字符串或类型导航的页面

41 PageManager.RegisterPage(typeof(AppShellPage));

42 PageManager.RegisterPage(typeof(MainPage));

43 PageManager.RegisterPage(typeof(TestPage));

44

45 // 全局异常捕获（可选）

46 UnhandledException += App_UnhandledException;

47 }

48

49 private void App_UnhandledException(object sender, Microsoft.UI.Xaml.UnhandledExceptionEventArgs e)

50 {

51 // 使用消息服务显示错误

52 if (ServiceManager.GetService<IMessageService>() is IMessageService messageService)

53 {

54 messageService.ShowMessage(e.Message, "发生错误", InfoBarSeverity.Error);

55 e.Handled = true;

56 }

57 }

58 ```

59

60 ### 2. 构建 Shell 页

61

62 创建一个包含 `NavigationView` 的 Shell 页（例如 `AppShellPage`），并绑定相关服务。

63

64 **AppShellPageViewModel.cs**:

65

66 ```csharp

67 public class AppShellPageViewModel : ObservableObject

68 {

69 // 使用 GetService 获取服务新实例

70

    public INavigationViewService NavigationViewService { get; set; } = ServiceManager.GetService<INavigationViewService>();

71 public IMessageService MessageService { get; set; } = ServiceManager.GetService<IMessageService>();

72 public ILoadingService LoadingService { get; set; } = ServiceManager.GetService<ILoadingService>();

73 }

74 ```

75

76 **AppShellPage.xaml.cs**:

77

78 ```csharp

79 public sealed partial class AppShellPage : Page

80 {

81 public AppShellPageViewModel ViewModel { get; set; } = new();

82

83 public AppShellPage()

84 {

85 Current = this;

86 this.InitializeComponent();

87

88 // 1. 初始化导航服务 (绑定 NavigationView 和 Frame)

89 ViewModel.NavigationViewService.Initialize(navigationView, navigationFrame);

90

91 // 2. 初始化消息服务 (绑定用于显示消息的 StackPanel)

92 ViewModel.MessageService.Initialize(messageStackPanel, DispatcherQueue);

93

94 // 3. 初始化加载服务 (绑定 Loading 控件)

95

        ViewModel.LoadingService.Initialize(loadingGrid, globalLoadingGrid, globalLoadingTextBlock, DispatcherQueue, ViewModel.NavigationViewService.NavigationService);

96

97 // 4. 初始导航

98 ViewModel.NavigationViewService.NavigateTo<MainPage>();

99 }

100 }

101 ```

102

103 ### 3. 使用服务

104

105

在子页面（如 `MainPage`）的 ViewModel 中，可以通过 `ServiceManager.GetGlobalService<T>()` 获取在 Shell 页已初始化的**全局服务实例**。

106

107 ```csharp

108 public partial class MainPageViewModel : ObservableObject

109 {

110 // 获取全局实例 (注意使用 GetGlobalService)

111

    public INavigationViewService? NavigationViewService { get; } = ServiceManager.GetGlobalService<INavigationViewService>();

112 public IMessageService? MessageService { get; } = ServiceManager.GetGlobalService<IMessageService>();

113

114 [RelayCommand]

115 void DoSomething()

116 {

117 // 显示消息

118 MessageService?.ShowMessage("操作成功！", "提示", InfoBarSeverity.Success);

119

120 // 页面跳转

121 NavigationViewService?.NavigateTo<TestPage>("传递的参数");

122 }

123 }

124 ```

125

126 ## 核心功能

127

128 ### ServiceManager (服务管理器)

129

130 简单的依赖注入及服务定位器。

131

132

- `GetService<T>()`: 获取服务实例。如果该服务类型遵循命名约定（如 `IMyService` -> `MyService`），则会自动创建实例。

133

- `GetGlobalService<T>()`: 获取**已注册**的全局单例服务。通常继承自 `GlobalServiceBase` 的服务在实例化时（如在 Shell 页初始化时）会自动注册为全局单例。

134

135 ### 导航服务 (INavigationViewService)

136

137 用于管理 `NavigationView` 的选中状态与 `Frame` 的页面跳转同步。

138

139 - `Initialize(...)`: 必须在使用前调用，绑定 UI 元素。

140 - `NavigateTo<TPage>(parameter)`: 导航到指定页面。

141 - `NavigationService.CanGoBack`: 检查是否可后退。

142

143 ### 消息与对话框

144

145

- **IMessageService**: 在界面特定区域显示非阻塞通知。需在 Shell 页的 XAML 中放置一个 `StackPanel` 作为容器。

146 - **IDialogService**: 显示内容对话框。

147 - **ILoadingService**: 管理加载状态，支持页面级遮罩和全局遮罩。

148

149 ## 常用工具类

150

151 - **PageManager**: 静态类，用于注册页面类型，使导航系统能通过 Type 找到对应的页面。

152 - **AppThemeHelper**: 用于管理应用的主题（Light/Dark/System）。

153 - **NavigationHelper**: 提供了 `SetParameter` 等方法用于页面间参数传递。

代码差异