PowerToys MouseJump 的 DSC 配置模块：用声明式配置管理激活快捷键与屏幕缩略预览

本文基于 PowerToys 仓库中的 DSC 模块参考文档 MouseJump.md，系统讲解 Microsoft.PowerToys/MouseJumpSettings 这一 DSC v3 配置资源的两个核心属性（ActivationShortcut 与 ThumbnailSize）、三种典型配置方式（PowerShell 直连 PowerToys.DSC.exe、dsc config set、winget configure），并结合 SettingsResource.cs、MouseJumpProperties.cs 等源码，说明配置项在系统内真实的落地形式与默认值来源。读完后你可以将 Mouse Jump 的快捷键与缩略图策略纳入自动化部署脚本（DSC / WinGet 配置文档），实现对大屏或多显示器环境的批量配置。

一、模块定位：Mouse Jump 是什么，DSC 资源做什么

Mouse Jump 是 PowerToys 中的鼠标辅助工具：激活后会显示所有显示器的微型缩略预览，你可以把鼠标光标快速"跳转"到预览中的任意位置。这在单台超大显示器或多显示器环境下尤其有用——原本需要长距离拖动鼠标的操作，可以一步完成。

PowerToys 的 DSC 层为这类设置提供了程序化入口。MouseJump DSC 模块的职责是管理 Mouse Jump 的配置状态，文档的 Synopsis 概括为：

Manages configuration for the Mouse Jump utility, which enables quick navigation across large or multiple displays.

在 DSC v3 体系中，该模块暴露的资源类型为 Microsoft.PowerToys/MouseJumpSettings。从源码结构看，SettingsResource.cs 中明确登记了模块映射：

{ nameof(ModuleType.MouseJump), CreateModuleFunctionData<MouseJumpSettings> },

也就是说，所有针对 --module MouseJump 的 get/set/test/export 操作，最终都路由到 MouseJumpSettings 这个设置模型上，由它负责读写 PowerToys 的模块配置（settings.json 中 MouseJump 节点）。

二、可配置属性详解

文档定义了 MouseJump 模块支持的两个可配置属性：ActivationShortcut（激活快捷键）与 ThumbnailSize（缩略图大小）。两者的结构、默认值如下。

2.1 ActivationShortcut：激活快捷键

设置 Mouse Jump 的激活键盘快捷键。

• 类型：object
• 属性：

字段	类型	说明
win	boolean	Windows 键修饰符
ctrl	boolean	Ctrl 键修饰符
alt	boolean	Alt 键修饰符
shift	boolean	Shift 键修饰符
code	integer	虚拟键码（Virtual key code）
key	string	键名

• 默认值：Win+Shift+D

这个默认值可以直接在源码中得到印证。MouseJumpProperties.cs 中定义了：

[CmdConfigureIgnore]
public HotkeySettings DefaultActivationShortcut => new HotkeySettings(true, false, false, true, 0x44);

构造函数参数依次对应 win=true, ctrl=false, alt=false, shift=true，虚拟键码 0x44 即字母 D——恰好就是文档声明的默认值 Win+Shift+D。

同时，MouseJumpSettings.cs 中通过 GetAllHotkeyAccessors() 把该快捷键暴露为唯一的热键访问器，并带有回退逻辑：当设置为空时，取 DefaultActivationShortcut（即 Win+Shift+D）作为兜底，保证快捷键始终有效：

new HotkeyAccessor(
    () => Properties.ActivationShortcut,
    value => Properties.ActivationShortcut = value ?? Properties.DefaultActivationShortcut,
    "MouseUtils_MouseJump_ActivationShortcut"),

这意味着通过 DSC 修改 ActivationShortcut 后，设置界面与快捷键注册逻辑都会读取同一份数据，不会出现"配置改了但 UI 不变"的分裂状态。

2.2 ThumbnailSize：缩略预览大小

设置屏幕缩略预览图的大小。

• 类型：string
• 允许值：

值	效果
"small"	更小的缩略图，性能表现更好
"medium"	大小与性能平衡
"large"	更大的缩略图，可视性更好

• 默认值："medium"

需要结合当前仓库源码说明一个实现细节：在 MouseJumpThumbnailSize.cs 中，thumbnail_size 实际被序列化为一个 {width, height} 的对象，默认尺寸为 1600x1200，并支持 1600x1200 这类 宽x高 的命令行表示形式：

public MouseJumpThumbnailSize()
{
    Width = 1600;
    Height = 1200;
}

从源码结构看，文档中的 "small" / "medium" / "large" 是对应预设档位，最终写入配置文件的是具体的宽高数值；"medium" 档位与默认对象初始化后的尺寸相对应。因此在使用 DSC 配置时，可以按文档使用档位字符串；若直接编辑原始 settings.json，则看到的是 thumbnail_size: { width, height } 形式的数值。

三、三种配置方式与完整示例

文档给出了五组示例，覆盖了三类调用方式。以下完整保留其形态并补充解读。

3.1 方式一：PowerShell 直连 PowerToys.DSC.exe（直接执行）

适用于已经安装 PowerToys、希望就地修改配置的场景。核心流程是：构造 PowerShell 哈希表 → ConvertTo-Json 压缩为 JSON → 通过 --input 传入 PowerToys.DSC.exe set。

示例 1：修改激活快捷键

$config = @{
    settings = @{
        properties = @{
            ActivationShortcut = @{
                win = $true
                ctrl = $false
                alt = $false
                shift = $true
                code = 68
                key = "D"
            }
        }
        name = "MouseJump"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

PowerToys.DSC.exe set --resource 'settings' --module MouseJump `
    --input $config

注意几点：

• code = 68 是 D 的十进制虚拟键码（0x44 = 68），与 key = "D" 冗余表达同一个键；
• 命令参数 --resource 'settings' 与 SettingsResource.cs 中的 ResourceName = "settings" 常量一致，--module MouseJump 对应 ModuleType.MouseJump；
• set 操作的执行语义在源码中有明确定义：SetState 会先读取当前状态、计算差异（diff），只有当期望状态与当前状态不一致时才会真正写入，并输出写入后的完整状态与 diff JSON。

示例 5：为大型 / 高 DPI 显示器配置大缩略图

$config = @{
    settings = @{
        properties = @{
            ThumbnailSize = "large"
        }
        name = "MouseJump"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

PowerToys.DSC.exe set --resource 'settings' --module MouseJump --input $config

一个值得注意的版本细节：文档示例中均使用 version = "1.0"，而 MouseJumpSettings.cs 的 UpgradeSettingsConfiguration() 会把 1.0 配置自动升级到 1.1——1.1 版本新增了预览样式相关字段（preview_type、background_color_1/2、border_thickness、border_color、border_3d_depth、border_padding、bezel_thickness、bezel_color、bezel_3d_depth、screen_margin、screen_color_1/2），默认采用 Bezelled（带边框）样式。因此用 1.0 提交配置是安全的，系统会自动补齐新字段的默认值并回写版本号，无需在 DSC 文档中显式写出这些样式字段。

3.2 方式二：dsc config set + DSC v3 配置文档（YAML）

适用于把配置纳入 DSC 声明式工作流、可版本化管理的场景。命令统一为 dsc config set --file <文件>，文档遵循 DSC v3 的 document.json schema。

示例 2：设置较大缩略图

dsc config set --file mousejump-size.dsc.yaml

# mousejump-size.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure Mouse Jump thumbnail
    type: Microsoft.PowerToys/MouseJumpSettings
    properties:
      settings:
        properties:
          ThumbnailSize: large
        name: MouseJump
        version: 1.0

示例 4：性能优先配置（小缩略图）

dsc config set --file mousejump-performance.dsc.yaml

# mousejump-performance.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Performance-optimized Mouse Jump
    type: Microsoft.PowerToys/MouseJumpSettings
    properties:
      settings:
        properties:
          ThumbnailSize: small
        name: MouseJump
        version: 1.0

两个 YAML 文档结构一致，差异仅在 ThumbnailSize 的档位：large 追求可视性，small 追求性能，可按硬件条件取舍。

3.3 方式三：winget configure 一站式安装 + 配置

适用于全新机器批量部署：同一个 WinGet 配置文档里先安装 PowerToys，再应用 Mouse Jump 配置。

示例 3：安装并配置

winget configure winget-mousejump.yaml

# winget-mousejump.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
metadata:
  winget:
    processor: dscv3
resources:
  - name: Install PowerToys
    type: Microsoft.WinGet.DSC/WinGetPackage
    properties:
      id: Microsoft.PowerToys
      source: winget

  - name: Configure Mouse Jump
    type: Microsoft.PowerToys/MouseJumpSettings
    properties:
      settings:
        properties:
          ThumbnailSize: medium
        name: MouseJump
        version: 1.0

关键点在于 metadata.winget.processor: dscv3——它告诉 WinGet 配置处理器把 Microsoft.PowerToys/* 类型的资源交给 DSC v3 协议执行；第一个 WinGetPackage 资源负责安装包，第二个 MouseJumpSettings 资源在包就绪后生效。DSC 资源的方法绑定（set/test 带 --input、get/export 走 stdin、schema 输出 JSON Schema）可以从 SettingsResource.cs 的 GenerateManifest 中直接看到，set 与 test 均声明了 stateAndDiff: true，即执行后同时返回状态与差异结果。

四、典型使用场景

文档归纳了两类典型部署场景，均只调整 ThumbnailSize 档位。

4.1 多显示器工作站

跨多台显示器高效导航时，使用平衡档 medium：

resources:
  - name: Multi-monitor configuration
    type: Microsoft.PowerToys/MouseJumpSettings
    properties:
      settings:
        properties:
          ThumbnailSize: medium
        name: MouseJump
        version: 1.0

4.2 大型显示器

超宽屏或 4K+ 显示器上，用 large 让缩略预览更容易看清目标位置：

resources:
  - name: Large display configuration
    type: Microsoft.PowerToys/MouseJumpSettings
    properties:
      settings:
        properties:
          ThumbnailSize: large
        name: MouseJump
        version: 1.0

这两段片段可以原样并入 3.2 节或 3.3 节的配置文档中，作为多显示器 / 大屏机型的策略模板。

五、适用前提与限制

结合仓库现状，使用本文配置方式时需注意：

1. 资源归属：MouseJump 的设置通过 settings 资源按 --module MouseJump 寻址（对应 SettingsResource.cs 中的 ResourceName = "settings" 常量），DSC 文档中的资源类型则写作 Microsoft.PowerToys/MouseJumpSettings，两者是同一入口的 CLI 形态与 DSC v3 文档形态；
2. 配置版本：提交 version: 1.0 即可，1.1 的预览样式字段（边框、边框条、屏幕填充色等）会在升级逻辑中自动补齐默认值，见 UpgradeSettingsConfiguration；
3. 不支持的模块对照：SettingsResource.cs 的注释列出了刻意排除在 DSC 管理之外的模块（MouseWithoutBorders、PowerLauncher、NewPlus），MouseJump 不在其中，其配置可安全地导出/导入；
4. 生效验证：set/test 操作会在输出中回显最终状态与 diff JSON，可用 test 命令在部署后校验实际状态是否与期望文档一致。

六、相关文档

• Settings Resource（settings 资源总览）
• PowerToys DSC Overview（DSC 集成总览）
• FindMyMouse 模块（同为鼠标定位辅助工具）

实现代码可进一步查阅：DSC settings 资源、MouseJump 设置模型、MouseJump 属性定义、缩略图尺寸模型，以及设置界面中的 MouseJumpPanel.xaml。