Hua.Todo/src/Hua.Todo.Maui

Hua.Todo MAUI 跨平台快捷键功能

功能概述

本项目实现了基于 MAUI + WebView 架构的跨平台代办管理应用，支持全局快捷键快速唤醒功能。

支持的平台

• Windows: 完整支持，使用 Windows API 实现全局快捷键
• macOS: 完整支持，使用 AppKit API 实现全局快捷键
• Android: 基础支持，通过通知快捷方式实现
• iOS: 基础支持，通过通知快捷方式实现

核心功能

1. 全局快捷键

• Windows 默认快捷键: Alt + X
• macOS 默认快捷键: Cmd + Option + X
• 移动端: 通过通知快捷方式实现

2. 快捷键设置

• 用户可以自定义快捷键组合
• 支持多种修饰键组合（Alt、Control、Shift 等）
• 支持禁用/启用快捷键功能
• 设置持久化保存

3. WebView 集成

• 主界面嵌入 WebView，显示 Hua.Todo Web 应用
• 快捷键按下时自动激活窗口并聚焦 WebView
• 支持与本地 API 服务通信

项目结构

Hua.Todo.Maui/
├── Models/
│   └── HotKeyConfig.cs              # 快捷键配置模型
├── Services/
│   ├── IGlobalHotKeyService.cs      # 快捷键服务接口
│   ├── HotKeySettingsService.cs     # 设置存储服务
│   ├── GlobalHotKeyServiceFactory.cs # 平台工厂
│   └── Platforms/
│       ├── WindowsGlobalHotKeyService.cs  # Windows 实现
│       ├── MacGlobalHotKeyService.cs      # macOS 实现
│       └── MobileGlobalHotKeyService.cs    # 移动端实现
├── Views/
│   ├── MainPage.xaml                # 主页面（WebView）
│   ├── MainPage.xaml.cs
│   ├── HotKeySettingsPage.xaml      # 快捷键设置页面
│   └── HotKeySettingsPage.xaml.cs
├── App.xaml.cs                      # 应用入口
└── MauiProgram.cs                   # MAUI 配置

使用方法

1. 运行项目

Windows

cd Hua.Todo.Maui
dotnet build -f net10.0-windows10.0.19041.0
dotnet run -f net10.0-windows10.0.19041.0

Windows Debug 编译下，MAUI 内嵌 WebServer 会提供接口文档：

• Swagger UI：{HostUrl}/swagger
• OpenAPI JSON：{HostUrl}/swagger/v1/swagger.json 其中 {HostUrl} 来自 appsettings.json: WebServer.HostUrl（默认 http://localhost:5057）。 按默认配置，对应地址为：
• Swagger UI：http://localhost:5057/swagger
• OpenAPI JSON：http://localhost:5057/swagger/v1/swagger.json

Windows（三件套热更新：MAUI + Vite + Host）

该模式用于开发阶段获得最佳热更新体验：

• Hua.Todo.Host：提供 API（http://localhost:5173）
• Hua.Todo.Web：Vite dev server（http://localhost:5174），并将 /api 代理到 5173
• Hua.Todo.Maui：WebView 加载 5174 在该模式下，Swagger UI 地址为：http://localhost:5173/swagger（仅 ASPNETCORE_ENVIRONMENT=Development 时启用）。

.\start-dev.ps1

然后在 Visual Studio 中启动 Hua.Todo.Maui（F5）。

macOS

cd Hua.Todo.Maui
dotnet build -f net10.0-maccatalyst
dotnet run -f net10.0-maccatalyst

Android

cd Hua.Todo.Maui
dotnet build -f net10.0-android
dotnet run -f net10.0-android

2. 使用快捷键

1. 启动应用后，默认快捷键为 Alt + X（Windows）或 Cmd + Option + X（macOS）
2. 按下快捷键，应用窗口会自动激活并聚焦
3. 在 WebView 中可以直接输入任务内容

3. 自定义快捷键

1. 点击主界面右上角的"设置"按钮
2. 在设置页面中：
   • 切换"启用快捷键"开关
   • 选择想要的修饰键组合
   • 选择主键
   • 点击"保存设置"按钮
3. 设置会立即生效

4. 恢复默认设置

在设置页面点击"恢复默认"按钮，快捷键将恢复为默认配置。

技术实现细节

Windows 平台

• 使用 RegisterHotKey 和 UnregisterHotKey Windows API
• 支持全局快捷键监听
• 通过 WindowNative 获取窗口句柄

macOS 平台

• 使用 NSEvent.AddGlobalMonitorForEventsMatchingMask 监听全局事件
• 支持 Command、Option、Control、Shift 等修饰键
• 需要配置 com.apple.security.automation.apple-events 权限

移动端

• Android: 使用 ShortcutManagerCompat 创建通知快捷方式
• iOS: 使用 UIApplicationShortcutItem 实现快捷操作

数据持久化

• 使用 Microsoft.Maui.Storage.Preferences 存储配置
• JSON 序列化保存快捷键配置
• 支持重置为默认配置

依赖项

NuGet 包

• Microsoft.Maui.Controls
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Logging.Debug

平台特定

• Windows: Microsoft.Windows.SDK.BuildTools
• macOS: Microsoft.Maui.Controls.Compatibility

注意事项

1. macOS 权限: 首次运行时需要在系统设置中授予辅助功能权限
2. Windows UAC: 某些情况下可能需要管理员权限
3. 移动端限制: 移动端不支持真正的全局快捷键，使用通知快捷方式替代
4. WebView（开发）: 三件套模式下需要确保 Hua.Todo.Host 在 http://localhost:5173 运行，同时 Hua.Todo.Web 在 http://localhost:5174 运行
5. Windows WebView2 数据目录: WebView2 的缓存/存储写入 %LocalAppData%\Hua.Todo\WebView2，避免在安装目录生成 *.WebView2 文件夹
6. Windows WebView2 Runtime: 依赖系统安装的 Microsoft Edge WebView2 Runtime；若缺失应用会提示下载安装

后续计划

• 添加 Linux 平台支持
• 实现云同步功能
• 添加更多快捷键功能
• 优化性能和响应速度
• 添加快捷键冲突检测

许可证

AGPL-3.0 License (English | 中文)