PowerToys DSC PowerOCR 模块：用声明式配置管理 Power OCR（文本提取器）的快捷键与识别语言

PowerToys DSC PowerOCR 模块：用声明式配置管理 Power OCR（文本提取器）的快捷键与识别语言

【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys

Microsoft PowerToys 支持 DSC v3（Desired State Configuration）来声明式地管理各 PowerToy 的配置，而PowerOCR模块文档（doc/dsc/modules/PowerOCR.md）正是其中针对 Power OCR（Text Extractor，文本提取器）的配置参考。Power OCR 利用光学字符识别（OCR）从屏幕任意区域提取文本并复制到剪贴板，适用于从图片、视频、PDF 或任意屏幕内容中捕获文字。本文围绕该文档的完整内容展开：介绍PowerOCRDSC 模块的两个可配置属性（激活快捷键与首选语言）、三种使用方式（PowerToys.DSC.exe直接执行、DSC 配置文件、WinGet 配置）的完整示例，并结合开源仓库中的设置资源源码，说明这些配置项在 PowerToys 内部的真实落点。

模块定位：settings 资源如何映射到 PowerOCR

PowerToys DSC 通过PowerToys.DSC.exe命令行工具提供唯一的settings资源，统一管理所有 PowerToy 模块的配置；每个模块可独立配置，实现细粒度控制（参见 DSC 总览）。在设置资源源码中，各模块名与具体设置类型通过一张映射表绑定，PowerOCR 对应PowerOcrSettings类型：

{ nameof(ModuleType.PowerOCR), CreateModuleFunctionData<PowerOcrSettings> },

参见 SettingsResource.cs。

从源码结构看，PowerOcrSettings（PowerOcrSettings.cs）的默认Name为TextExtractor、Version为1，并且它实现了IHotkeyConfig接口，暴露了名为Activation_Shortcut的热键访问器——这解释了为什么 DSC 文档中ActivationShortcut是一个结构化对象，以及为什么该模块的快捷键能参与 PowerToys 的统一热键冲突检测。模块配置文件实际序列化时以TextExtractor为键（见 SndPowerOcrSettings.cs），即settings.json中该模块的段名是TextExtractor而非PowerOCR，这一点在用get/export查看当前状态时值得留意。

可配置属性详解

PowerOCR模块支持两个可配置属性。

ActivationShortcut：激活文本提取的键盘快捷键

类型：object默认值：Win+Shift+T

该对象描述一个完整的组合键，包含以下子属性：

示例中code = 84、key = "T"，两者是同一物理键的两种表达（84 是字母 T 的虚拟键码），配置时应保持一致。源码中该热键通过HotkeyAccessor注册到全局快捷键体系中（PowerOcrSettings.cs），当快捷键无法绑定时会回退到DefaultActivationShortcut（即默认的Win+Shift+T）。

PreferredLanguage：OCR 首选识别语言

类型：string默认值：系统语言

用于指定 OCR 识别时优先使用的语言（如en-US、fr-FR、es-ES）。对于混合语言内容，将语言设置为覆盖目标文本的语种可以显著改善识别效果。

使用方式与完整示例

方式一：PowerToys.DSC.exe 直接执行——配置激活快捷键

以下示例自定义 OCR 激活快捷键（完整继承自原文档示例 1）：

$config = @{ settings = @{ properties = @{ ActivationShortcut = @{ win = $true ctrl = $false alt = $false shift = $true code = 84 key = "T" } } name = "PowerOCR" version = "1.0" } } | ConvertTo-Json -Depth 10 -Compress PowerToys.DSC.exe set --resource 'settings' --module PowerOCR ` --input $config

set操作的底层行为可以从 SettingsResource.cs 得到印证：它先GetState()读取当前状态，生成当前态与期望态的 diff，然后仅在TestState()判定存在差异时才调用SetState()落盘——也就是说set是幂等的，重复执行不会产生无谓的写操作。随后输出两行 JSON：应用后的状态与差异信息。

方式二：DSC 配置文件——设置首选识别语言

以下示例通过 DSC v3 配置文件设置 OCR 语言（原文档示例 2）：

dsc config set --file powerocr-language.dsc.yaml

# powerocr-language.dsc.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Configure Power OCR language type: Microsoft.PowerToys/PowerOCRSettings properties: settings: properties: PreferredLanguage: en-US name: PowerOCR version: 1.0

注意资源类型是Microsoft.PowerToys/PowerOCRSettings，这与manifest命令生成的清单命名规则一致：GenerateManifest()以"{module}Settings"作为资源类型名（SettingsResource.cs），因此 PowerOCR 的 DSC 资源类型即为Microsoft.PowerToys/PowerOCRSettings。

方式三：WinGet 配置——安装 PowerToys 并同时配置 Power OCR

以下示例将安装与配置合并在一个 WinGet 配置文件中执行（原文档示例 3），适合批量部署新机器：

winget configure winget-powerocr.yaml

# winget-powerocr.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 Power OCR type: Microsoft.PowerToys/PowerOCRSettings properties: settings: properties: PreferredLanguage: en-US name: PowerOCR version: 1.0

两个资源按声明顺序执行：先由 WinGet 安装Microsoft.PowerToys，再由 PowerToys 的 DSC 资源应用 OCR 语言配置。

多语言场景：配置法语文本提取

原文档示例 4 演示了面向多语言内容的配置，将首选语言指向法语：

dsc config set --file powerocr-multilingual.dsc.yaml

# powerocr-multilingual.dsc.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Multilingual OCR type: Microsoft.PowerToys/PowerOCRSettings properties: settings: properties: PreferredLanguage: fr-FR name: PowerOCR version: 1.0

典型用例

文档数字化——针对英文文档批量提取文本：

resources: - name: Document OCR type: Microsoft.PowerToys/PowerOCRSettings properties: settings: properties: PreferredLanguage: en-US name: PowerOCR version: 1.0

国际化内容——针对西班牙语等混合语言内容：

resources: - name: Multilingual OCR type: Microsoft.PowerToys/PowerOCRSettings properties: settings: properties: PreferredLanguage: es-ES name: PowerOCR version: 1.0

配套运维操作：get / test / schema / manifest

围绕 PowerOCR 模块，还可以使用 settings 资源的通用运维子命令（参考 Settings Resource）：

# 查看 PowerOCR 当前配置（export 与 get 等价） PowerToys.DSC.exe get --resource 'settings' --module PowerOCR PowerToys.DSC.exe export --resource 'settings' --module PowerOCR # 验证当前配置是否与期望状态一致 $desired = '{"settings":{"properties":{"PreferredLanguage":"en-US"},"name":"PowerOCR","version":"1.0"}}' PowerToys.DSC.exe test --resource 'settings' --module PowerOCR --input $desired

test输出的 JSON 中包含_inDesiredState布尔属性，指示配置是否处于期望状态；源码中该值由TestState()计算得出（SettingsResource.cs）。可以据此编写漂移检测脚本：若为false，则再执行一次set完成修正。

# 获取 PowerOCR 设置的 JSON Schema，了解全部可配置属性及类型 PowerToys.DSC.exe schema --resource 'settings' --module PowerOCR # 生成 DSC 资源清单（用于注册/引用资源） PowerToys.DSC.exe manifest --resource 'settings' --module PowerOCR

需要说明的是，PowerOCR的 DSC 支持是源码映射表中显式登记的能力（SettingsResource.cs）；同一映射表注释中列出了当前不受支持的模块（MouseWithoutBorders、PowerLauncher、NewPlus），PowerOCR 不在其列。

小结与延伸阅读

PowerOCRDSC 模块将文本提取器最容易产生机器间差异的两项设置——激活快捷键与识别语言——纳入了声明式管理：用 PowerShell 对象或 YAML 声明期望状态，通过PowerToys.DSC.exe、dsc或winget configure三种入口之一应用，并用test子命令持续验证漂移。配合 settings 资源的schema/manifest能力，可以将其纳入团队级的"配置即代码"流程。

进一步阅读：

• Settings Resource 参考：settings 资源的全部操作与多模块配置示例
• PowerToys DSC 总览：三种使用方式、支持模块列表与通用操作
• ZoomIt 模块：同一模块文档集下的另一个 DSC 配置参考
• SettingsResource 源码：get/set/test/export/schema/manifest 的实现入口
• PowerOcrSettings 源码：PowerOCR 设置模型、热键访问器与TextExtractor模块名

【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys