PowerToys MouseHighlighter 的 DSC 声明式配置：属性详解与三种落地方式

本文基于 PowerToys 仓库中 MouseHighlighter 模块的 DSC 配置参考文档（doc/dsc/modules/MouseHighlighter.md），系统讲解如何通过 PowerToys.DSC.exe、DSC v3 配置文档与 WinGet 配置三种方式，声明式地管理鼠标高亮工具（Mouse Highlighter）的点击颜色、高亮半径、淡出动画等全部属性，并结合仓库源码说明每个属性在设置模型与渲染引擎中的真实落地位置与默认值。

一、MouseHighlighter 模块与 DSC settings 资源

Mouse Highlighter 是 PowerToys MouseUtils 家族中的工具之一：它通过全局低级鼠标钩子捕获点击与移动事件，在全屏置顶的透明窗口上用 WinUI Composition 绘制圆形高亮，适用于演示、录屏教程与无障碍场景。其核心渲染逻辑位于 MouseHighlighter.cpp，默认参数定义在 MouseHighlighter.h。

PowerToys 通过 DSC（Desired State Configuration）v3 协议把各模块的设置暴露为一个 settings 资源，实现“配置即代码”。在 SettingsResource.cs 的构造函数中，每个受支持模块都映射到一个强类型设置配置，其中 MouseHighlighter 的注册行为：

{ nameof(ModuleType.MouseHighlighter), CreateModuleFunctionData<MouseHighlighterSettings> },

这意味着 PowerToys.DSC.exe 针对 MouseHighlighter 模块的 set/test/get/schema 操作，最终都序列化/反序列化为 Microsoft.PowerToys.Settings.UI.Library 中的 MouseHighlighterSettings 对象——DSC 文档里的 properties 字段与 PowerToys 设置界面读写的是同一份 settings.json 数据模型，保证声明式配置与 GUI 配置结果一致。

根据 PowerToys DSC 概览文档，PowerToys DSC 支持三种使用方式，下文示例均覆盖这三种路径。

二、可配置属性完整参考

原文档声明 MouseHighlighter 模块支持以下可配置属性，全部置于 DSC 输入 JSON 的 settings.properties 之下：

属性	类型	取值/格式	文档默认值	说明
ActivationShortcut	object	win/ctrl/alt/shift（布尔）+ code（虚拟键码，整数）+ key（按键名，字符串）	Win+Shift+H	切换高亮开关的键盘快捷键
LeftButtonClickColor	string	#RRGGBB 十六进制颜色	#BFFF00（绿）	左键点击高亮颜色
RightButtonClickColor	string	#RRGGBB 十六进制颜色	#00BFFF（蓝）	右键点击高亮颜色
HighlightOpacity	integer	0–100	160	点击高亮的透明度
HighlightRadius	integer	1–500 像素	20	点击高亮圆形的半径
HighlightFadeDelayMs	integer	0–10000 毫秒	500	高亮保持可见的时间（淡出前延迟）
HighlightFadeDurationMs	integer	0–10000 毫秒	250	淡出动画持续时长
AutoActivate	boolean	true/false	false	是否在演示时自动激活高亮

激活快捷键对象的结构

ActivationShortcut 是一个对象，由四个修饰键布尔量加一个按键标识组成。在设置模型中它对应 HotkeySettings，其默认值定义于 MouseHighlighterProperties.cs：

[CmdConfigureIgnore]
public HotkeySettings DefaultActivationShortcut =>
    new HotkeySettings(true, false, false, true, 0x48); // Win+Shift+H，0x48 为 'H' 的虚拟键码

code 字段即 Windows 虚拟键码（例如 0x48 对应 H 键），key 字段是同一按键的可读名称，两者在 JSON 中同时出现。

默认值的实现事实核对

需要特别注意：文档中的默认值（半径 20、延迟 500ms、时长 250ms）与当前仓库源码中的默认值存在差异。源码中两处定义如下：

• 渲染层默认值（MouseHighlighter.h）：

const winrt::Windows::UI::Color MOUSE_HIGHLIGHTER_DEFAULT_LEFT_BUTTON_COLOR  = ...FromArgb(166, 191, 255, 0);   // #a6BFFF00
const winrt::Windows::UI::Color MOUSE_HIGHLIGHTER_DEFAULT_RIGHT_BUTTON_COLOR = ...FromArgb(166, 0, 191, 255);  // #a600BFFF
constexpr int MOUSE_HIGHLIGHTER_DEFAULT_RADIUS = 30;
constexpr int MOUSE_HIGHLIGHTER_DEFAULT_DELAY_MS = 400;
constexpr int MOUSE_HIGHLIGHTER_DEFAULT_DURATION_MS = 400;

• 设置模型默认值（MouseHighlighterProperties.cs）：HighlightRadius = 30、HighlightFadeDelayMs = 400、HighlightFadeDurationMs = 400、LeftButtonClickColor = "#a6BFFF00"、RightButtonClickColor = "#a600BFFF"。

以当前仓库为准，半径默认 30 像素、延迟与时长均为 400 毫秒，且颜色默认值实际带透明度前缀（ARGB 格式，前两位 a6 约等于 65% 不透明度）。如果你的目标系统返回的默认值与本文文档值不同，以上述源码路径为准。此外源码还暴露了文档未逐一列出的扩展属性（见第六节），DSC 输入的 properties 对象整体走 JSON 反序列化，因此这些属性同样可以通过 DSC 配置。

三、三种落地方式与完整示例

方式 1：PowerToys.DSC.exe 直接执行

将目标状态构造成 PowerShell 哈希表，经 ConvertTo-Json 压缩为单行 JSON 后通过 --input 传入。原文档示例 1——自定义左右键点击颜色与透明度：

$config = @{
    settings = @{
        properties = @{
            LeftButtonClickColor = "#00FF00"
            RightButtonClickColor = "#FF0000"
            HighlightOpacity = 200
        }
        name = "MouseHighlighter"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

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

其内部执行链路是：SetCommand.cs 将输入交给 SettingsResource.SetState()，而 SettingsResource.SetState 的行为是幂等的——先读取当前状态，计算 diff，仅当期望状态与当前状态不一致时才真正写回：

// Capture the diff before updating the output
var diff = data.GetDiffJson();

// Only call Set if the desired state is different from the current state
if (!data.TestState())
{
    var inputSettings = data.Input.SettingsInternal;
    data.Output.SettingsInternal = inputSettings;
    data.SetState();
}

命令输出两行 JSON：写回后的完整状态与变更 diff，退出码 0 表示成功。同样的输入也可以交给 test 子命令只校验不写入，便于在 CI 中做配置一致性断言。

方式 2：DSC 配置文件（.dsc.yaml）

将声明写入 DSC v3 配置文档，用 dsc config set --file 应用。原文档示例 2——调整动画时序与外观：

dsc config set --file mousehighlighter-animation.dsc.yaml

# mousehighlighter-animation.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure Mouse Highlighter animation
    type: Microsoft.PowerToys/MouseHighlighterSettings
    properties:
      settings:
        properties:
          HighlightRadius: 30
          HighlightFadeDelayMs: 750
          HighlightFadeDurationMs: 400
        name: MouseHighlighter
        version: 1.0

资源类型统一为 Microsoft.PowerToys/<模块名>Settings，其中 <模块名> 即 MouseHighlighter。DSC 引擎会依据模块 manifest 把该资源分发到 PowerToys.DSC.exe。manifest 的生成逻辑见 SettingsResource.GenerateManifest：为每个模块产出 microsoft.powertoys.<module>.settings.dsc.resource.json，声明 export/get（stdin 方法）、set/test（JSON 输入方法，set 带 pretest 能力）以及 schema 命令。你可以随时用以下命令查看 MouseHighlighter 属性的机器可读定义：

PowerToys.DSC.exe schema --resource 'settings' --module MouseHighlighter

方式 3：WinGet 配置（安装 + 配置一体化）

winget configure 可以在一份 YAML 中先安装 PowerToys，再声明式配置 MouseHighlighter，是演示环境批量准备的推荐做法。原文档示例 3：

winget configure winget-mousehighlighter.yaml

# winget-mousehighlighter.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 Highlighter for presentations
    type: Microsoft.PowerToys/MouseHighlighterSettings
    properties:
      settings:
        properties:
          LeftButtonClickColor: "#FFD700"
          RightButtonClickColor: "#FF4500"
          HighlightOpacity: 220
          HighlightRadius: 25
          AutoActivate: true
        name: MouseHighlighter
        version: 1.0

metadata.winget.processor: dscv3 声明该文档交给 DSC v3 处理器执行；两个资源按序执行，先装包后配置，保证配置阶段 PowerToys.DSC.exe 已随安装包就位。

四、典型场景配方

原文档的“Use cases”章节给出两组针对具体场景的配方，均继承如下。

演示与演示直播：高可见度 + 自动激活

resources:
  - name: Presentation highlighting
    type: Microsoft.PowerToys/MouseHighlighterSettings
    properties:
      settings:
        properties:
          LeftButtonClickColor: "#FFD700"
          HighlightOpacity: 200
          HighlightRadius: 25
          AutoActivate: true
        name: MouseHighlighter
        version: 1.0

金色高亮（#FFD700）+ 25 像素半径 + AutoActivate: true，让高亮在演示中自动开启，观众视线可以持续跟随光标。

屏幕录制：稍长的高亮保持时间

resources:
  - name: Recording configuration
    type: Microsoft.PowerToys/MouseHighlighterSettings
    properties:
      settings:
        properties:
          HighlightOpacity: 180
          HighlightFadeDelayMs: 600
        name: MouseHighlighter
        version: 1.0

HighlightFadeDelayMs: 600 让点击高亮在镜头前停留更久，便于录屏中的观众看清点击位置。

其他两个可复制的配方

原文档示例 4（低调不打扰）与示例 5（无障碍高对比度）同样值得直接取用：

dsc config set --file mousehighlighter-subtle.dsc.yaml

# mousehighlighter-subtle.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Subtle mouse highlighting
    type: Microsoft.PowerToys/MouseHighlighterSettings
    properties:
      settings:
        properties:
          HighlightOpacity: 100
          HighlightRadius: 15
          HighlightFadeDelayMs: 300
        name: MouseHighlighter
        version: 1.0

# 高可见度、长停留（示例 5）
$config = @{
    settings = @{
        properties = @{
            LeftButtonClickColor = "#FFFFFF"
            RightButtonClickColor = "#FF0000"
            HighlightOpacity = 255
            HighlightRadius = 40
            HighlightFadeDelayMs = 1500
            HighlightFadeDurationMs = 500
        }
        name = "MouseHighlighter"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

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

五、参数如何驱动渲染：源码级印证

DSC 写入的属性值最终经由 ApplySettings 应用到渲染状态：

void Highlighter::ApplySettings(MouseHighlighterSettings settings)
{
    m_radius = static_cast<float>(settings.radius);
    m_fadeDelay_ms = settings.fadeDelayMs;
    m_fadeDuration_ms = settings.fadeDurationMs;
    m_leftClickColor = settings.leftButtonColor;
    m_rightClickColor = settings.rightButtonColor;
    ...
}

各参数的实际影响可以逐一对应：

• HighlightRadius → 圆形几何半径：AddDrawingPoint 中 circleGeometry.Radius({ m_radius, m_radius }) 直接以该值创建椭圆几何；按下按键时还有一个内置的“按压缩小”动画，半径会在 150ms 延迟后 180ms 内压缩到 70%（MouseHighlighter.cpp）。
• HighlightFadeDelayMs / HighlightFadeDurationMs → 颜色关键帧动画：StartDrawingPointFading 用 ColorKeyFrameAnimation 把填充色动画到透明，DelayTime 与 Duration 分别取这两个参数。源码对 0 值有保护：为 0 时强制改为 1ms，避免淡出动画失效。
• Left/RightButtonClickColor → 填充画笔：circleShape.FillBrush(m_compositor.CreateColorBrush(m_leftClickColor))，且当颜色 Alpha 为 0 时对应指针被整体禁用（m_leftPointerEnabled = settings.leftButtonColor.A != 0），所以“设为透明色”等价于“关闭该类高亮”。
• AutoActivate：在设置模型中对应 AutoActivate 布尔属性，控制演示态下的自动激活行为。

事件通路方面，StartDrawing 通过 SetWindowsHookEx(WH_MOUSE_LL, ...) 注册低级鼠标钩子（MouseHighlighter.cpp），钩子回调只做一件事——把事件写入容量为 128 的无锁环形队列并 PostMessage，实际绘制全部回到窗口消息循环中执行（QueueMouseEvent）。这种“钩子只入队、UI 线程统一消费”的设计，也解释了为什么 DSC 修改设置走 WM_APPLY_SETTINGS 消息排队而非直接回调。

六、设置模型全貌：文档之外还支持的属性

MouseHighlighterProperties（MouseHighlighterProperties.cs）是 DSC properties 对象反序列化的目标类型，其完整属性集比文档列出的更多，且每个属性带有 JsonPropertyName 决定了 JSON 键名（注意：DSC 输入使用 PascalCase 属性名匹配 C# 属性，而 settings.json 落盘使用 snake_case 键名）：

C# 属性	JSON 键（settings.json）	类型	源码默认值	说明
ActivationShortcut	activation_shortcut	HotkeySettings	Win+Shift+H	切换快捷键
LeftButtonClickColor	left_button_click_color	string	#a6BFFF00	左键高亮色
RightButtonClickColor	right_button_click_color	string	#a600BFFF	右键高亮色
HighlightOpacity	highlight_opacity	int	166	透明度（1.2 版起已并入颜色，见下）
AlwaysColor	always_color	string	#00FF0000	光标常显颜色（Alpha 为 0 即关闭）
HighlightRadius	highlight_radius	int	30	高亮半径（像素）
HighlightFadeDelayMs	highlight_fade_delay_ms	int	400	淡出前延迟
HighlightFadeDurationMs	highlight_fade_duration_ms	int	400	淡出时长
AutoActivate	auto_activate	bool	false	演示时自动激活
SpotlightMode	spotlight_mode	bool	false	聚光灯模式
RippleMode	ripple_mode	bool	true	涟漪（波纹）模式
RippleSize	ripple_size	int	60	涟漪尺寸
RippleIntensity	ripple_intensity	double	0.7	涟漪强度
RippleDurationMs	ripple_duration_ms	int	480	涟漪动画时长
RippleShowDragTrail	ripple_show_drag_trail	bool	true	长按拖动时涟漪跟随光标
RippleShowReleasePulse	ripple_show_release_pulse	bool	true	松开按键时的脉冲效果

两点实现细节值得注意：

1. HighlightOpacity 的迁移语义：MouseHighlighterSettings.cs 的 UpgradeSettingsConfiguration 显示，v1.0 时代透明度是独立的 0–255 值，v1.1 起改为 0–100 百分比，v1.2（当前模型版本）把透明度直接并入 ARGB 颜色的 Alpha 通道。该属性被标记 [CmdConfigureIgnore]，意味着在命令通道中它主要服务于版本迁移；实际调透明度建议直接设置带 Alpha 前缀的颜色值。
2. 涟漪模式的按压判定：从源码结构看，快点击（按住时间 < 180ms，HOLD_RIPPLE_THRESHOLD_MS）会发射一个自包含的单涟漪，超过阈值则进入“长按指示器 + 松开淡出”的序列（MouseHighlighter.cpp）。因此 ripple_duration_ms 与 HighlightFadeDurationMs 分属两套动画：前者驱动涟漪，后者驱动经典圆点淡出。

七、验证、排错与测试

• 查当前状态：PowerToys.DSC.exe get --resource 'settings' --module MouseHighlighter（export 与 get 等价），输出可直接与期望值比对。
• 只做漂移检测：PowerToys.DSC.exe test --resource 'settings' --module MouseHighlighter --input $config，输出含 inDesiredState 与 diff，不产生写入。
• 行为级验证：仓库自带的 UI 测试用 dsc config set 应用同一份 DSC YAML 再核对设置界面状态，见 MouseHighlighterTests.cs 及其辅助类 MouseHighlighterSettings.cs；DSC 资源本身的 set 命令单测见 SettingsResourceCommandTest.cs。
• 快捷键冲突：ActivationShortcut 若被其他 PowerToys 模块占用，集中式热键机制会报告冲突，可在设置界面查看冲突提示后调整其中一个模块的快捷键。

八、小结

MouseHighlighter 的 DSC 参考文档给出了 settings.properties 下 8 个核心属性（快捷键、双键点击颜色、透明度、半径、淡出时序、自动激活）的完整定义，并示范了 PowerToys.DSC.exe 直接执行、DSC YAML 文件、WinGet 一体化配置三条落地路径。对照仓库源码可以确认：这些属性经 SettingsResource 幂等地写入与 GUI 共享的 MouseHighlighterSettings 模型，再由 Highlighter::ApplySettings 映射为 Composition 几何半径、颜色画笔与动画时长；同时源码还揭示了文档未展开的 Spotlight / Ripple 系列属性与 ARGB 透明度迁移机制。以文档属性表为骨架、以源码默认值与 JSON 键名为校准，即可在任何版本差异下准确写出可验证的 MouseHighlighter 声明式配置。

相关文档：Settings Resource 参考、PowerToys DSC 概览、MousePointerCrosshairs 模块。