返回提交历史
Modified
README.md
+64
-57
Added
README.zh-CN.md
+160
-0
XFEstudio/XFEExtension.NetCore.WinUIHelper
docs: add English README as main doc, rename Chinese to README.zh-CN.md, add badges
Agent-Logs-Url: https://github.com/XFEstudio/XFEExtension.NetCore.WinUIHelper/sessions/3ff1efdf-002c-4b5a-bde2-a40a4034e71a Co-authored-by: XFEstudio <132526994+XFEstudio@users.noreply.github.com>
3869e4d
代码差异
2 个文件
+224
-57
@@ -1,72 +1,79 @@
1
1
# XFEExtension.NetCore.WinUIHelper
2
2
3
基于 .NET 8 的 WinUI 3 扩展库，提供了一系列便捷的帮助类、服务和扩展方法，旨在简化 WinUI 3 应用的开发流程。
3
[](https://www.nuget.org/packages/XFEExtension.NetCore.WinUIHelper)
4
[](https://www.nuget.org/packages/XFEExtension.NetCore.WinUIHelper)
5
[](LICENSE.txt)
6
[](https://dotnet.microsoft.com/)
4
7
5
## 目录
8
> 📖 [中文文档](README.zh-CN.md)
6
9
7
- [特性](#特性)
8
- [快速开始](#快速开始)
9
- [1. 初始化配置](#1-初始化配置)
10
- [2. 构建 Shell 页](#2-构建-shell-页)
11
- [3. 使用服务](#3-使用服务)
12
- [核心功能](#核心功能)
10
A WinUI 3 extension library based on .NET 8, providing a set of convenient helper classes, services, and extension methods to streamline WinUI 3 application development.
11
12
## Table of Contents
13
14
- [Features](#features)
15
- [Quick Start](#quick-start)
16
- [1. Initialization](#1-initialization)
17
- [2. Build the Shell Page](#2-build-the-shell-page)
18
- [3. Using Services](#3-using-services)
19
- [Core Features](#core-features)
13
20
- [ServiceManager](#servicemanager)
14
- [导航服务](#导航服务)
15
- [消息与对话框](#消息与对话框)
16
- [常用工具类](#常用工具类)
21
- [Navigation Service](#navigation-service)
22
- [Messages and Dialogs](#messages-and-dialogs)
23
- [Utility Classes](#utility-classes)
17
24
18
## 特性
25
## Features
19
26
20
- **轻量级 IOC 容器**：内置 `ServiceManager`，支持服务注册与全局单例获取。
21
- **导航管理**：封装 `NavigationView` 和 `Frame`，提供基于 ViewModel 的导航体验。
22
- **UI交互服务**：提供 `DialogService`、`MessageService` (类似 InfoBar)、`LoadingService` 等常用交互服务。
23
- **MVVM 支持**：提供 `ObservableObject` 扩展及通用 ViewModel 基类。
27
- **Lightweight IoC Container**: Built-in `ServiceManager` supporting service registration and global singleton retrieval.
28
- **Navigation Management**: Wraps `NavigationView` and `Frame` to provide a ViewModel-driven navigation experience.
29
- **UI Interaction Services**: Offers `DialogService`, `MessageService` (similar to InfoBar), `LoadingService`, and other common interaction services.
30
- **MVVM Support**: Provides `ObservableObject` extensions and a general-purpose ViewModel base class.
24
31
25
## 快速开始
32
## Quick Start
26
33
27
### 1. 初始化配置
34
### 1. Initialization
28
35
29
在 `App.xaml.cs` 中进行初始化，包括注册页面和配置异常处理。
36
Initialize in `App.xaml.cs`, including page registration and exception handling setup.
30
37
31
38
```csharp
32
39
public App()
33
40
{
34
41
this.InitializeComponent();
35
42
36
// 设置应用主题
43
// Set application theme
37
44
AppThemeHelper.Theme = ElementTheme.Dark;
38
45
39
// 注册导航页面 (PageManager)
40
// 必须在此处注册所有可通过字符串或类型导航的页面
46
// Register navigation pages (PageManager)
47
// All pages navigable by string or type must be registered here
41
48
PageManager.RegisterPage(typeof(AppShellPage));
42
49
PageManager.RegisterPage(typeof(MainPage));
43
50
PageManager.RegisterPage(typeof(TestPage));
44
51
45
// 全局异常捕获（可选）
52
// Global exception handling (optional)
46
53
UnhandledException += App_UnhandledException;
47
54
}
48
55
49
56
private void App_UnhandledException(object sender, Microsoft.UI.Xaml.UnhandledExceptionEventArgs e)
50
57
{
51
// 使用消息服务显示错误
58
// Display error using the message service
52
59
if (ServiceManager.GetService<IMessageService>() is IMessageService messageService)
53
60
{
54
messageService.ShowMessage(e.Message, "发生错误", InfoBarSeverity.Error);
61
messageService.ShowMessage(e.Message, "An error occurred", InfoBarSeverity.Error);
55
62
e.Handled = true;
56
63
}
57
64
}
58
65
```
59
66
60
### 2. 构建 Shell 页
67
### 2. Build the Shell Page
61
68
62
创建一个包含 `NavigationView` 的 Shell 页（例如 `AppShellPage`），并绑定相关服务。
69
Create a Shell page (e.g. `AppShellPage`) containing a `NavigationView` and bind the relevant services.
63
70
64
71
**AppShellPageViewModel.cs**:
65
72
66
73
```csharp
67
74
public class AppShellPageViewModel : ObservableObject
68
75
{
69
// 使用 GetService 获取服务新实例
76
// Use GetService to obtain a new service instance
70
77
public INavigationViewService NavigationViewService { get; set; } = ServiceManager.GetService<INavigationViewService>();
71
78
public IMessageService MessageService { get; set; } = ServiceManager.GetService<IMessageService>();
72
79
public ILoadingService LoadingService { get; set; } = ServiceManager.GetService<ILoadingService>();
@@ -85,69 +92,69 @@ public sealed partial class AppShellPage : Page
85
92
Current = this;
86
93
this.InitializeComponent();
87
94
88
// 1. 初始化导航服务 (绑定 NavigationView 和 Frame)
95
// 1. Initialize navigation service (bind NavigationView and Frame)
89
96
ViewModel.NavigationViewService.Initialize(navigationView, navigationFrame);
90
97
91
// 2. 初始化消息服务 (绑定用于显示消息的 StackPanel)
98
// 2. Initialize message service (bind the StackPanel used to display messages)
92
99
ViewModel.MessageService.Initialize(messageStackPanel, DispatcherQueue);
93
100
94
// 3. 初始化加载服务 (绑定 Loading 控件)
101
// 3. Initialize loading service (bind loading controls)
95
102
ViewModel.LoadingService.Initialize(loadingGrid, globalLoadingGrid, globalLoadingTextBlock, DispatcherQueue, ViewModel.NavigationViewService.NavigationService);
96
103
97
// 4. 初始导航
104
// 4. Initial navigation
98
105
ViewModel.NavigationViewService.NavigateTo<MainPage>();
99
106
}
100
107
}
101
108
```
102
109
103
### 3. 使用服务
110
### 3. Using Services
104
111
105
在子页面（如 `MainPage`）的 ViewModel 中，可以通过 `ServiceManager.GetGlobalService<T>()` 获取在 Shell 页已初始化的**全局服务实例**。
112
In a child page's ViewModel (e.g. `MainPage`), use `ServiceManager.GetGlobalService<T>()` to retrieve the **global service instance** that was initialized in the Shell page.
106
113
107
114
```csharp
108
115
public partial class MainPageViewModel : ObservableObject
109
116
{
110
// 获取全局实例 (注意使用 GetGlobalService)
117
// Retrieve global instances (use GetGlobalService)
111
118
public INavigationViewService? NavigationViewService { get; } = ServiceManager.GetGlobalService<INavigationViewService>();
112
119
public IMessageService? MessageService { get; } = ServiceManager.GetGlobalService<IMessageService>();
113
120
114
121
[RelayCommand]
115
122
void DoSomething()
116
123
{
117
// 显示消息
118
MessageService?.ShowMessage("操作成功！", "提示", InfoBarSeverity.Success);
124
// Show a message
125
MessageService?.ShowMessage("Operation successful!", "Info", InfoBarSeverity.Success);
119
126
120
// 页面跳转
121
NavigationViewService?.NavigateTo<TestPage>("传递的参数");
127
// Navigate to another page
128
NavigationViewService?.NavigateTo<TestPage>("parameter to pass");
122
129
}
123
130
}
124
131
```
125
132
126
## 核心功能
133
## Core Features
127
134
128
### ServiceManager (服务管理器)
135
### ServiceManager
129
136
130
简单的依赖注入及服务定位器。
137
A simple dependency injection and service locator.
131
138
132
- `GetService<T>()`: 获取服务实例。如果该服务类型遵循命名约定（如 `IMyService` -> `MyService`），则会自动创建实例。
133
- `GetGlobalService<T>()`: 获取**已注册**的全局单例服务。通常继承自 `GlobalServiceBase` 的服务在实例化时（如在 Shell 页初始化时）会自动注册为全局单例。
139
- `GetService<T>()`: Gets a service instance. If the type follows the naming convention (e.g. `IMyService` → `MyService`), an instance is created automatically.
140
- `GetGlobalService<T>()`: Gets a **registered** global singleton service. Services inheriting from `GlobalServiceBase` automatically register themselves as global singletons when instantiated (e.g. during Shell page initialization).
134
141
135
### 导航服务 (INavigationViewService)
142
### Navigation Service
136
143
137
用于管理 `NavigationView` 的选中状态与 `Frame` 的页面跳转同步。
144
Manages `NavigationView` selection state and `Frame` page transition synchronization via `INavigationViewService`.
138
145
139
- `Initialize(...)`: 必须在使用前调用，绑定 UI 元素。
140
- `NavigateTo<TPage>(parameter)`: 导航到指定页面。
141
- `NavigationService.CanGoBack`: 检查是否可后退。
146
- `Initialize(...)`: Must be called before use to bind UI elements.
147
- `NavigateTo<TPage>(parameter)`: Navigates to the specified page.
148
- `NavigationService.CanGoBack`: Checks whether back navigation is available.
142
149
143
### 消息与对话框
150
### Messages and Dialogs
144
151
145
- **IMessageService**: 在界面特定区域显示非阻塞通知。需在 Shell 页的 XAML 中放置一个 `StackPanel` 作为容器。
146
- **IDialogService**: 显示内容对话框。
147
- **ILoadingService**: 管理加载状态，支持页面级遮罩和全局遮罩。
152
- **IMessageService**: Displays non-blocking notifications in a designated area of the UI. Requires a `StackPanel` container placed in the Shell page's XAML.
153
- **IDialogService**: Displays content dialogs.
154
- **ILoadingService**: Manages loading states, supporting both page-level overlays and global overlays.
148
155
149
## 常用工具类
156
## Utility Classes
150
157
151
- **PageManager**: 静态类，用于注册页面类型，使导航系统能通过 Type 找到对应的页面。
152
- **AppThemeHelper**: 用于管理应用的主题（Light/Dark/System）。
153
- **NavigationHelper**: 提供了 `SetParameter` 等方法用于页面间参数传递。
158
- **PageManager**: A static class used to register page types so the navigation system can locate them by `Type`.
159
- **AppThemeHelper**: Manages the application theme (Light / Dark / System).
160
- **NavigationHelper**: Provides methods such as `SetParameter` for passing parameters between pages.
@@ -0,0 +1,160 @@
1
# XFEExtension.NetCore.WinUIHelper
2
3
[](https://www.nuget.org/packages/XFEExtension.NetCore.WinUIHelper)
4
[](https://www.nuget.org/packages/XFEExtension.NetCore.WinUIHelper)
5
[](LICENSE.txt)
6
[](https://dotnet.microsoft.com/)
7
8
> 📖 [English Documentation](README.md) | 中文文档
9
10
基于 .NET 8 的 WinUI 3 扩展库，提供了一系列便捷的帮助类、服务和扩展方法，旨在简化 WinUI 3 应用的开发流程。
11
12
## 目录
13
14
- [特性](#特性)
15
- [快速开始](#快速开始)
16
- [1. 初始化配置](#1-初始化配置)
17
- [2. 构建 Shell 页](#2-构建-shell-页)
18
- [3. 使用服务](#3-使用服务)
19
- [核心功能](#核心功能)
20
- [ServiceManager](#servicemanager)
21
- [导航服务](#导航服务)
22
- [消息与对话框](#消息与对话框)
23
- [常用工具类](#常用工具类)
24
25
## 特性
26
27
- **轻量级 IOC 容器**：内置 `ServiceManager`，支持服务注册与全局单例获取。
28
- **导航管理**：封装 `NavigationView` 和 `Frame`，提供基于 ViewModel 的导航体验。
29
- **UI交互服务**：提供 `DialogService`、`MessageService` (类似 InfoBar)、`LoadingService` 等常用交互服务。
30
- **MVVM 支持**：提供 `ObservableObject` 扩展及通用 ViewModel 基类。
31
32
## 快速开始
33
34
### 1. 初始化配置
35
36
在 `App.xaml.cs` 中进行初始化，包括注册页面和配置异常处理。
37
38
```csharp
39
public App()
40
{
41
this.InitializeComponent();
42
43
// 设置应用主题
44
AppThemeHelper.Theme = ElementTheme.Dark;
45
46
// 注册导航页面 (PageManager)
47
// 必须在此处注册所有可通过字符串或类型导航的页面
48
PageManager.RegisterPage(typeof(AppShellPage));
49
PageManager.RegisterPage(typeof(MainPage));
50
PageManager.RegisterPage(typeof(TestPage));
51
52
// 全局异常捕获（可选）
53
UnhandledException += App_UnhandledException;
54
}
55
56
private void App_UnhandledException(object sender, Microsoft.UI.Xaml.UnhandledExceptionEventArgs e)
57
{
58
// 使用消息服务显示错误
59
if (ServiceManager.GetService<IMessageService>() is IMessageService messageService)
60
{
61
messageService.ShowMessage(e.Message, "发生错误", InfoBarSeverity.Error);
62
e.Handled = true;
63
}
64
}
65
```
66
67
### 2. 构建 Shell 页
68
69
创建一个包含 `NavigationView` 的 Shell 页（例如 `AppShellPage`），并绑定相关服务。
70
71
**AppShellPageViewModel.cs**:
72
73
```csharp
74
public class AppShellPageViewModel : ObservableObject
75
{
76
// 使用 GetService 获取服务新实例
77
public INavigationViewService NavigationViewService { get; set; } = ServiceManager.GetService<INavigationViewService>();
78
public IMessageService MessageService { get; set; } = ServiceManager.GetService<IMessageService>();
79
public ILoadingService LoadingService { get; set; } = ServiceManager.GetService<ILoadingService>();
80
}
81
```
82
83
**AppShellPage.xaml.cs**:
84
85
```csharp
86
public sealed partial class AppShellPage : Page
87
{
88
public AppShellPageViewModel ViewModel { get; set; } = new();
89
90
public AppShellPage()
91
{
92
Current = this;
93
this.InitializeComponent();
94
95
// 1. 初始化导航服务 (绑定 NavigationView 和 Frame)
96
ViewModel.NavigationViewService.Initialize(navigationView, navigationFrame);
97
98
// 2. 初始化消息服务 (绑定用于显示消息的 StackPanel)
99
ViewModel.MessageService.Initialize(messageStackPanel, DispatcherQueue);
100
101
// 3. 初始化加载服务 (绑定 Loading 控件)
102
ViewModel.LoadingService.Initialize(loadingGrid, globalLoadingGrid, globalLoadingTextBlock, DispatcherQueue, ViewModel.NavigationViewService.NavigationService);
103
104
// 4. 初始导航
105
ViewModel.NavigationViewService.NavigateTo<MainPage>();
106
}
107
}
108
```
109
110
### 3. 使用服务
111
112
在子页面（如 `MainPage`）的 ViewModel 中，可以通过 `ServiceManager.GetGlobalService<T>()` 获取在 Shell 页已初始化的**全局服务实例**。
113
114
```csharp
115
public partial class MainPageViewModel : ObservableObject
116
{
117
// 获取全局实例 (注意使用 GetGlobalService)
118
public INavigationViewService? NavigationViewService { get; } = ServiceManager.GetGlobalService<INavigationViewService>();
119
public IMessageService? MessageService { get; } = ServiceManager.GetGlobalService<IMessageService>();
120
121
[RelayCommand]
122
void DoSomething()
123
{
124
// 显示消息
125
MessageService?.ShowMessage("操作成功！", "提示", InfoBarSeverity.Success);
126
127
// 页面跳转
128
NavigationViewService?.NavigateTo<TestPage>("传递的参数");
129
}
130
}
131
```
132
133
## 核心功能
134
135
### ServiceManager (服务管理器)
136
137
简单的依赖注入及服务定位器。
138
139
- `GetService<T>()`: 获取服务实例。如果该服务类型遵循命名约定（如 `IMyService` -> `MyService`），则会自动创建实例。
140
- `GetGlobalService<T>()`: 获取**已注册**的全局单例服务。通常继承自 `GlobalServiceBase` 的服务在实例化时（如在 Shell 页初始化时）会自动注册为全局单例。
141
142
### 导航服务 (INavigationViewService)
143
144
用于管理 `NavigationView` 的选中状态与 `Frame` 的页面跳转同步。
145
146
- `Initialize(...)`: 必须在使用前调用，绑定 UI 元素。
147
- `NavigateTo<TPage>(parameter)`: 导航到指定页面。
148
- `NavigationService.CanGoBack`: 检查是否可后退。
149
150
### 消息与对话框
151
152
- **IMessageService**: 在界面特定区域显示非阻塞通知。需在 Shell 页的 XAML 中放置一个 `StackPanel` 作为容器。
153
- **IDialogService**: 显示内容对话框。
154
- **ILoadingService**: 管理加载状态，支持页面级遮罩和全局遮罩。
155
156
## 常用工具类
157
158
- **PageManager**: 静态类，用于注册页面类型，使导航系统能通过 Type 找到对应的页面。
159
- **AppThemeHelper**: 用于管理应用的主题（Light/Dark/System）。
160
- **NavigationHelper**: 提供了 `SetParameter` 等方法用于页面间参数传递。