# mouse-update **Repository Path**: dongdong-git/mouse-update ## Basic Information - **Project Name**: mouse-update - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-18 - **Last Updated**: 2026-06-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MouseUpdate - Windows 鼠标光标自定义工具 一款 Windows 平台上的鼠标光标全方位自定义工具，支持**上传任意图片自动转换为光标**、**替换系统光标方案**、**方案管理与导入导出**。 --- ## 功能特性 - 🖼️ **图片转光标** — 上传 PNG/JPG/BMP/GIF 等图片，自动缩放裁剪生成 `.cur` 光标文件 - 🎨 **光标样式替换** — 替换 Windows 全部 18 种系统光标状态（箭头、忙、手形、文本等） - 📂 **批量导入** — 一次导入整个文件夹的图片，按文件名智能匹配光标状态 - 💾 **方案管理** — 保存/加载多套方案，支持导出为 `.zip` 包分享 - 🔄 **一键恢复** — 一键恢复 Windows 系统默认光标 - 📦 **单文件发布** — 打包为单个 exe，复制到任意 Win10/Win11 机器直接运行 --- ## 目录结构 ``` D:\work\mouseupdate\ ├── 项目分析报告.md # 完整需求、技术选型、架构分析文档 ├── src/ # 源代码 │ ├── MouseUpdate.sln # Visual Studio 解决方案文件 │ │ │ ├── MouseUpdate.App/ # WPF 用户界面层 │ │ ├── App.xaml / App.xaml.cs # 应用入口 + DI 注册 │ │ ├── MainWindow.xaml / .cs # 主窗口 UI 布局 │ │ ├── ViewModels/ │ │ │ └── MainViewModel.cs # MVVM 主 ViewModel │ │ ├── Converters/ │ │ │ └── Base64ImageConverter.cs # Base64 → ImageSource 转换器 │ │ └── MouseUpdate.App.csproj │ │ │ ├── MouseUpdate.Core/ # 核心业务逻辑层 │ │ ├── Enums/ │ │ │ ├── CursorState.cs # 18 种系统光标状态枚举 │ │ │ ├── CursorSize.cs # 光标尺寸枚举（32~128px） │ │ │ └── CursorSourceType.cs # 光标来源类型 │ │ ├── Models/ │ │ │ ├── CursorItem.cs # 单个光标项定义 │ │ │ ├── CursorScheme.cs # 完整光标方案 │ │ │ └── ImageConversionRequest.cs # 图片转换请求/结果 │ │ ├── Services/ │ │ │ ├── ICursorService.cs # 光标服务接口 │ │ │ ├── CursorService.cs # 光标服务实现 │ │ │ ├── ICursorImageProcessor.cs # 图片处理服务接口 │ │ │ ├── CursorImageProcessor.cs # 图片处理实现（含智能导入） │ │ │ ├── ICursorSchemeManager.cs # 方案管理接口 │ │ │ └── (实现见 Data 层) │ │ ├── Converters/ │ │ │ └── ImageToCursorConverter.cs # 图片 → .cur 格式转换器 │ │ └── MouseUpdate.Core.csproj │ │ │ ├── MouseUpdate.NativeInterop/ # Win32 原生互操作层 │ │ ├── Interop/ │ │ │ ├── NativeMethods.cs # P/Invoke → user32.dll / kernel32.dll │ │ │ └── NativeConstants.cs # OCR_*, SPI_* 常量 │ │ ├── Structs/ │ │ │ └── Win32Structs.cs # ICONDIR, BITMAPINFOHEADER 等结构体 │ │ ├── CursorNative.cs # 封装的 Win32 光标操作安全接口 │ │ └── MouseUpdate.NativeInterop.csproj │ │ │ ├── MouseUpdate.Data/ # 数据持久化层 │ │ ├── Repositories/ │ │ │ └── CursorSchemeRepository.cs # JSON 文件存储 + .zip 导入导出 │ │ └── MouseUpdate.Data.csproj │ │ │ └── (各项目 obj/ 目录 — 编译产物) │ ├── assets/ # 资源文件（默认光标/图标等） ├── scripts/ │ └── publish.ps1 # 打包单文件 exe 脚本 ├── tests/ # 单元测试（预留） └── .workbuddy/ # WorkBuddy 工作区配置 ``` --- ## 技术栈 | 层面 | 技术 | 说明 | |------|------|------| | 语言 | **C# 12** | 最新的 C# 语言特性 | | 运行时 | **.NET 8** | LTS 版本，Windows 原生集成最佳 | | UI 框架 | **WPF** | XAML 声明式 UI, MVVM 模式 | | 架构模式 | **MVVM** | CommunityToolkit.Mvvm 风格 | | 图片处理 | **System.Drawing.Common** | 图片缩放、裁剪、格式转换 | | Win32 API | **P/Invoke (LibraryImport)** | 调用 user32.dll 操作系统光标 | | 数据存储 | **JSON 文件** | 方案存储于 `%LOCALAPPDATA%\MouseUpdate\` | | 打包部署 | **自包含单文件发布** | 单个 exe，无需 .NET 运行时 | ### 关键 Windows API | API | 用途 | |-----|------| | `LoadCursorFromFileW` | 从 .cur/.ani 文件加载光标 | | `SetSystemCursor` | 替换系统光标 | | `CopyCursor` / `DestroyCursor` | 光标句柄管理 | | `SystemParametersInfoW(SPI_SETCURSORS)` | 恢复默认光标方案 | | `GetModuleHandleW` | 获取模块句柄 | --- ## 快速开始 ### 前置条件 - Windows 10 1809+ 或 Windows 11 - [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) （仅开发需要，运行不需要） ### 克隆 & 构建 ```bash # 进入项目目录 cd D:\work\mouseupdate\src # 还原依赖 dotnet restore # 构建（Debug） dotnet build # 构建（Release） dotnet build -c Release ``` ### 运行 ```bash # 直接运行 dotnet run --project src\MouseUpdate.App # 或运行编译后的 exe .\src\MouseUpdate.App\bin\Debug\net8.0-windows\MouseUpdate.App.exe ``` > ⚠️ **注意**：替换系统光标需要**管理员权限**。建议右键 exe → "以管理员身份运行"。 --- ## 打包为单文件 exe ### 方式一：使用发布脚本（推荐） ```powershell # PowerShell .\scripts\publish.ps1 # 产物在 dist\MouseUpdate.exe（约 70 MB） ``` ### 方式二：手动 dotnet publish ```bash cd D:\work\mouseupdate\src dotnet publish MouseUpdate.App\MouseUpdate.App.csproj \ -c Release \ -r win-x64 \ --self-contained true \ -o ..\dist \ /p:PublishSingleFile=true \ /p:IncludeNativeLibrariesForSelfExtract=true \ /p:EnableCompressionInSingleFile=true ``` > ⚠️ **注意**：由于 WPF + WinForms 使用大量反射，暂不启用 `PublishTrimmed` 以避免运行时错误。 ### 打包产物说明 ``` dist\ ├── MouseUpdate.exe ← 单个 exe，约 70 MB ├── *.pdb ← 调试符号（可删除） │ ↑ 包含 .NET 运行时、WPF 程序集、所有依赖包 ↑ 复制到任何 Win10/Win11 机器直接运行 ↑ 用户数据写入 %LOCALAPPDATA%\MouseUpdate\ ``` ### 验证结果 已实际测试打包并成功生成 `dist\MouseUpdate.exe`（69 MB），零错误零 warning。`dotnet publish` 构建耗时约 22 秒。 ### 关于管理员权限 由于 `SetSystemCursor` API 需要管理员权限，打包后的 exe 需要**以管理员身份运行**才能正常工作。可以通过以下方式： 1. **手动**：右键 exe → "以管理员身份运行" 2. **自动**：在 `app.manifest` 中添加 `` 3. **编译后**：使用 `signtool` 对 exe 签名，消除 SmartScreen 警告 --- ## 模块依赖关系 ``` MouseUpdate.App (WPF UI) ├── MouseUpdate.Core (业务逻辑) │ └── MouseUpdate.NativeInterop (Win32 API) └── MouseUpdate.Data (数据存储) └── MouseUpdate.Core ``` - `App` → `Core` + `Data`：UI 调用业务服务和数据仓储 - `Core` → `NativeInterop`：业务层通过 P/Invoke 调用系统 API - `Data` → `Core` + `NativeInterop`：仓储需要 Core 模型和 NativeInterop 读取系统光标 --- ## 核心工作流程 ### 图片转光标流程 ``` 用户选图 (PNG/JPG/BMP...) ↓ ImageToCursorConverter ├─ 验证格式 ├─ 加载图片 (Image.FromStream) ├─ 缩放/裁剪 (UniformCrop / UniformFill / Stretch) │ └─ 默认尺寸 48×48，可选 32/64/96/128 ├─ 构造 .cur 二进制文件 │ └─ ICONDIR + ICONDIRENTRY(含热点) + BITMAPINFOHEADER + 像素数据 └─ 生成缩略图预览 (Base64 PNG) ↓ 输出 .cur 文件 → 添加到方案 → 替换系统光标 ``` ### 光标替换流程 ``` 用户点击"应用到系统" ↓ CursorService.ApplyScheme() ├─ 遍历方案中所有光标项 ├─ CursorNative.SafeSetCursor(filePath, ocrId) │ ├─ LoadCursorFromFile → 加载 .cur │ ├─ CopyCursor → 复制句柄 │ ├─ SetSystemCursor → 替换系统光标 │ └─ DestroyCursor → 释放原始句柄 └─ 报告进度/结果 ``` --- ## 开发计划 ### Phase 1 — MVP ✅（已完成） - [x] 项目结构调整、模块化分层 - [x] 图片转 `.cur` 核心转换器 - [x] 光标服务（替换/恢复/验证） - [x] 方案管理（CRUD + 导入导出） - [x] WPF 主界面（MVVM） - [x] 编译通过，0 错误 0 警告 ### Phase 2 — 增强功能 - [ ] 按键映射（WH_MOUSE_LL 低级鼠标钩子） - [ ] 热点编辑器（拖拽调整光标热点） - [ ] 方案导出/导入的完善（.zip） - [ ] 开机自启 - [x] 单文件 exe 打包 ### Phase 3 — 远期 - [ ] 宏录制与回放 - [ ] DPI/加速度/滚轮设置 - [ ] 在线主题市场 - [ ] 云同步 --- ## 许可证 本项目仅供个人学习与使用。