PowerToys MouseHighlighter 的 DSC 声明式配置属性详解与三种落地方式【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys本文基于 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 通过 DSCDesired State Configurationv3 协议把各模块的设置暴露为一个settings资源实现“配置即代码”。在 SettingsResource.cs 的构造函数中每个受支持模块都映射到一个强类型设置配置其中 MouseHighlighter 的注册行为{ nameof(ModuleType.MouseHighlighter), CreateModuleFunctionDataMouseHighlighterSettings },这意味着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之下属性类型取值/格式文档默认值说明ActivationShortcutobjectwin/ctrl/alt/shift布尔code虚拟键码整数key按键名字符串WinShiftH切换高亮开关的键盘快捷键LeftButtonClickColorstring#RRGGBB十六进制颜色#BFFF00绿左键点击高亮颜色RightButtonClickColorstring#RRGGBB十六进制颜色#00BFFF蓝右键点击高亮颜色HighlightOpacityinteger0–100160点击高亮的透明度HighlightRadiusinteger1–500像素20点击高亮圆形的半径HighlightFadeDelayMsinteger0–10000毫秒500高亮保持可见的时间淡出前延迟HighlightFadeDurationMsinteger0–10000毫秒250淡出动画持续时长AutoActivatebooleantrue/falsefalse是否在演示时自动激活高亮激活快捷键对象的结构ActivationShortcut是一个对象由四个修饰键布尔量加一个按键标识组成。在设置模型中它对应HotkeySettings其默认值定义于 MouseHighlighterProperties.cs[CmdConfigureIgnore] public HotkeySettings DefaultActivationShortcut new HotkeySettings(true, false, false, true, 0x48); // WinShiftH0x48 为 H 的虚拟键码code字段即 Windows 虚拟键码例如0x48对应 H 键key字段是同一按键的可读名称两者在 JSON 中同时出现。默认值的实现事实核对需要特别注意文档中的默认值半径20、延迟500ms、时长250ms与当前仓库源码中的默认值存在差异。源码中两处定义如下渲染层默认值MouseHighlighter.hconst 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.csHighlightRadius 30、HighlightFadeDelayMs 400、HighlightFadeDurationMs 400、LeftButtonClickColor #a6BFFF00、RightButtonClickColor #a600BFFF。以当前仓库为准半径默认 30 像素、延迟与时长均为 400 毫秒且颜色默认值实际带透明度前缀ARGB 格式前两位a6约等于 65% 不透明度。如果你的目标系统返回的默认值与本文文档值不同以上述源码路径为准。此外源码还暴露了文档未逐一列出的扩展属性见第六节DSC 输入的properties对象整体走 JSON 反序列化因此这些属性同样可以通过 DSC 配置。三、三种落地方式与完整示例方式 1PowerToys.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 中做配置一致性断言。方式 2DSC 配置文件.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/getstdin 方法、set/testJSON 输入方法set带 pretest 能力以及schema命令。你可以随时用以下命令查看 MouseHighlighter 属性的机器可读定义PowerToys.DSC.exe schema --resource settings --module MouseHighlighter方式 3WinGet 配置安装 配置一体化winget configure可以在一份 YAML 中先安装 PowerToys再声明式配置 MouseHighlighter是演示环境批量准备的推荐做法。原文档示例 3winget 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.0metadata.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.0HighlightFadeDelayMs: 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_castfloat(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消息排队而非直接回调。六、设置模型全貌文档之外还支持的属性MouseHighlighterPropertiesMouseHighlighterProperties.cs是 DSCproperties对象反序列化的目标类型其完整属性集比文档列出的更多且每个属性带有JsonPropertyName决定了 JSON 键名注意DSC 输入使用 PascalCase 属性名匹配 C# 属性而settings.json落盘使用 snake_case 键名C# 属性JSON 键settings.json类型源码默认值说明ActivationShortcutactivation_shortcutHotkeySettingsWinShiftH切换快捷键LeftButtonClickColorleft_button_click_colorstring#a6BFFF00左键高亮色RightButtonClickColorright_button_click_colorstring#a600BFFF右键高亮色HighlightOpacityhighlight_opacityint166透明度1.2 版起已并入颜色见下AlwaysColoralways_colorstring#00FF0000光标常显颜色Alpha 为 0 即关闭HighlightRadiushighlight_radiusint30高亮半径像素HighlightFadeDelayMshighlight_fade_delay_msint400淡出前延迟HighlightFadeDurationMshighlight_fade_duration_msint400淡出时长AutoActivateauto_activateboolfalse演示时自动激活SpotlightModespotlight_modeboolfalse聚光灯模式RippleModeripple_modebooltrue涟漪波纹模式RippleSizeripple_sizeint60涟漪尺寸RippleIntensityripple_intensitydouble0.7涟漪强度RippleDurationMsripple_duration_msint480涟漪动画时长RippleShowDragTrailripple_show_drag_trailbooltrue长按拖动时涟漪跟随光标RippleShowReleasePulseripple_show_release_pulsebooltrue松开按键时的脉冲效果两点实现细节值得注意HighlightOpacity的迁移语义MouseHighlighterSettings.cs 的UpgradeSettingsConfiguration显示v1.0 时代透明度是独立的 0–255 值v1.1 起改为 0–100 百分比v1.2当前模型版本把透明度直接并入 ARGB 颜色的 Alpha 通道。该属性被标记[CmdConfigureIgnore]意味着在命令通道中它主要服务于版本迁移实际调透明度建议直接设置带 Alpha 前缀的颜色值。涟漪模式的按压判定从源码结构看快点击按住时间 180msHOLD_RIPPLE_THRESHOLD_MS会发射一个自包含的单涟漪超过阈值则进入“长按指示器 松开淡出”的序列MouseHighlighter.cpp。因此ripple_duration_ms与HighlightFadeDurationMs分属两套动画前者驱动涟漪后者驱动经典圆点淡出。七、验证、排错与测试查当前状态PowerToys.DSC.exe get --resource settings --module MouseHighlighterexport与get等价输出可直接与期望值比对。只做漂移检测PowerToys.DSC.exe test --resource settings --module MouseHighlighter --input $config输出含inDesiredState与 diff不产生写入。行为级验证仓库自带的 UI 测试用dsc config set应用同一份 DSC YAML 再核对设置界面状态见 MouseHighlighterTests.cs 及其辅助类 MouseHighlighterSettings.csDSC 资源本身的 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 模块。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PowerToys MouseHighlighter 的 DSC 声明式配置：属性详解与三种落地方式
PowerToys MouseHighlighter 的 DSC 声明式配置属性详解与三种落地方式【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys本文基于 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 通过 DSCDesired State Configurationv3 协议把各模块的设置暴露为一个settings资源实现“配置即代码”。在 SettingsResource.cs 的构造函数中每个受支持模块都映射到一个强类型设置配置其中 MouseHighlighter 的注册行为{ nameof(ModuleType.MouseHighlighter), CreateModuleFunctionDataMouseHighlighterSettings },这意味着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之下属性类型取值/格式文档默认值说明ActivationShortcutobjectwin/ctrl/alt/shift布尔code虚拟键码整数key按键名字符串WinShiftH切换高亮开关的键盘快捷键LeftButtonClickColorstring#RRGGBB十六进制颜色#BFFF00绿左键点击高亮颜色RightButtonClickColorstring#RRGGBB十六进制颜色#00BFFF蓝右键点击高亮颜色HighlightOpacityinteger0–100160点击高亮的透明度HighlightRadiusinteger1–500像素20点击高亮圆形的半径HighlightFadeDelayMsinteger0–10000毫秒500高亮保持可见的时间淡出前延迟HighlightFadeDurationMsinteger0–10000毫秒250淡出动画持续时长AutoActivatebooleantrue/falsefalse是否在演示时自动激活高亮激活快捷键对象的结构ActivationShortcut是一个对象由四个修饰键布尔量加一个按键标识组成。在设置模型中它对应HotkeySettings其默认值定义于 MouseHighlighterProperties.cs[CmdConfigureIgnore] public HotkeySettings DefaultActivationShortcut new HotkeySettings(true, false, false, true, 0x48); // WinShiftH0x48 为 H 的虚拟键码code字段即 Windows 虚拟键码例如0x48对应 H 键key字段是同一按键的可读名称两者在 JSON 中同时出现。默认值的实现事实核对需要特别注意文档中的默认值半径20、延迟500ms、时长250ms与当前仓库源码中的默认值存在差异。源码中两处定义如下渲染层默认值MouseHighlighter.hconst 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.csHighlightRadius 30、HighlightFadeDelayMs 400、HighlightFadeDurationMs 400、LeftButtonClickColor #a6BFFF00、RightButtonClickColor #a600BFFF。以当前仓库为准半径默认 30 像素、延迟与时长均为 400 毫秒且颜色默认值实际带透明度前缀ARGB 格式前两位a6约等于 65% 不透明度。如果你的目标系统返回的默认值与本文文档值不同以上述源码路径为准。此外源码还暴露了文档未逐一列出的扩展属性见第六节DSC 输入的properties对象整体走 JSON 反序列化因此这些属性同样可以通过 DSC 配置。三、三种落地方式与完整示例方式 1PowerToys.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 中做配置一致性断言。方式 2DSC 配置文件.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/getstdin 方法、set/testJSON 输入方法set带 pretest 能力以及schema命令。你可以随时用以下命令查看 MouseHighlighter 属性的机器可读定义PowerToys.DSC.exe schema --resource settings --module MouseHighlighter方式 3WinGet 配置安装 配置一体化winget configure可以在一份 YAML 中先安装 PowerToys再声明式配置 MouseHighlighter是演示环境批量准备的推荐做法。原文档示例 3winget 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.0metadata.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.0HighlightFadeDelayMs: 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_castfloat(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消息排队而非直接回调。六、设置模型全貌文档之外还支持的属性MouseHighlighterPropertiesMouseHighlighterProperties.cs是 DSCproperties对象反序列化的目标类型其完整属性集比文档列出的更多且每个属性带有JsonPropertyName决定了 JSON 键名注意DSC 输入使用 PascalCase 属性名匹配 C# 属性而settings.json落盘使用 snake_case 键名C# 属性JSON 键settings.json类型源码默认值说明ActivationShortcutactivation_shortcutHotkeySettingsWinShiftH切换快捷键LeftButtonClickColorleft_button_click_colorstring#a6BFFF00左键高亮色RightButtonClickColorright_button_click_colorstring#a600BFFF右键高亮色HighlightOpacityhighlight_opacityint166透明度1.2 版起已并入颜色见下AlwaysColoralways_colorstring#00FF0000光标常显颜色Alpha 为 0 即关闭HighlightRadiushighlight_radiusint30高亮半径像素HighlightFadeDelayMshighlight_fade_delay_msint400淡出前延迟HighlightFadeDurationMshighlight_fade_duration_msint400淡出时长AutoActivateauto_activateboolfalse演示时自动激活SpotlightModespotlight_modeboolfalse聚光灯模式RippleModeripple_modebooltrue涟漪波纹模式RippleSizeripple_sizeint60涟漪尺寸RippleIntensityripple_intensitydouble0.7涟漪强度RippleDurationMsripple_duration_msint480涟漪动画时长RippleShowDragTrailripple_show_drag_trailbooltrue长按拖动时涟漪跟随光标RippleShowReleasePulseripple_show_release_pulsebooltrue松开按键时的脉冲效果两点实现细节值得注意HighlightOpacity的迁移语义MouseHighlighterSettings.cs 的UpgradeSettingsConfiguration显示v1.0 时代透明度是独立的 0–255 值v1.1 起改为 0–100 百分比v1.2当前模型版本把透明度直接并入 ARGB 颜色的 Alpha 通道。该属性被标记[CmdConfigureIgnore]意味着在命令通道中它主要服务于版本迁移实际调透明度建议直接设置带 Alpha 前缀的颜色值。涟漪模式的按压判定从源码结构看快点击按住时间 180msHOLD_RIPPLE_THRESHOLD_MS会发射一个自包含的单涟漪超过阈值则进入“长按指示器 松开淡出”的序列MouseHighlighter.cpp。因此ripple_duration_ms与HighlightFadeDurationMs分属两套动画前者驱动涟漪后者驱动经典圆点淡出。七、验证、排错与测试查当前状态PowerToys.DSC.exe get --resource settings --module MouseHighlighterexport与get等价输出可直接与期望值比对。只做漂移检测PowerToys.DSC.exe test --resource settings --module MouseHighlighter --input $config输出含inDesiredState与 diff不产生写入。行为级验证仓库自带的 UI 测试用dsc config set应用同一份 DSC YAML 再核对设置界面状态见 MouseHighlighterTests.cs 及其辅助类 MouseHighlighterSettings.csDSC 资源本身的 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 模块。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考