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

Microsoft PowerToys 支持 DSC v3（Desired State Configuration）来声明式地管理各 PowerToy 的配置，而 PowerOCR 模块文档（doc/dsc/modules/PowerOCR.md）正是其中针对 Power OCR（Text Extractor，文本提取器）的配置参考。Power OCR 利用光学字符识别（OCR）从屏幕任意区域提取文本并复制到剪贴板，适用于从图片、视频、PDF 或任意屏幕内容中捕获文字。本文围绕该文档的完整内容展开：介绍 PowerOCR DSC 模块的两个可配置属性（激活快捷键与首选语言）、三种使用方式（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

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

子属性	类型	说明
win	boolean	是否按下 Windows 键
ctrl	boolean	是否按下 Ctrl 键
alt	boolean	是否按下 Alt 键
shift	boolean	是否按下 Shift 键
code	integer	虚拟键码（Virtual Key Code）
key	string	键名

示例中 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 不在其列。

小结与延伸阅读

PowerOCR DSC 模块将文本提取器最容易产生机器间差异的两项设置——激活快捷键与识别语言——纳入了声明式管理：用 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 模块名