PowerToys PowerAccent DSC 配置参考：用声明式方式管理 Quick Accent 设置

本文为 Microsoft PowerToys 的 PowerAccent（Quick Accent，快速重音字符选择）模块提供 DSC（Desired State Configuration）配置参考。读完本文，你将掌握 Microsoft.PowerToys/PowerAccentSettings DSC 资源的全部可配置属性（激活键、触发时长、工具条位置、排序与 Unicode 描述等）、三种标准用法（PowerToys.DSC.exe 直接执行、DSC 配置文档、winget configure）以及完整的可复制示例，并能结合仓库源码理解这些属性背后的实际设置模型与写入链路。

模块概览

PowerAccent DSC 模块用于管理 PowerToys Quick Accent（Power Accent）的配置。Quick Accent 是一个快速重音字符选择工具：按住某个键不放，再使用方向键或数字键，即可从该字母可用的重音变体中选择并输入目标字符，适合频繁输入多语言、带重音符号文本的场景。

从源码结构看，该模块在 PowerToys 中的注册名为 QuickAccent：模块接口实现 中 MODULE_NAME 定义为 L"QuickAccent"，启用时通过 CreateProcess 启动 WinUI3Apps\PowerToys.PowerAccent.exe（见 dllmain.cpp 中的 launch_process）。DSC 侧则通过 SettingsResource 注册了对 PowerAccent 的支持（见 SettingsResource.cs 中的模块映射），并据此生成名为 PowerAccentSettings 的资源清单。

DSC 资源支持的操作方法如下（由 GenerateManifest 定义）：

方法	说明	对应命令行
export / get	导出或获取当前配置	get --module PowerAccent --resource settings
set	写入期望配置（内置预测试，状态无变化时不重复写入）	set --module PowerAccent --resource settings --input <JSON>
test	测试当前状态是否与期望一致	test --module PowerAccent --resource settings --input <JSON>
schema	输出该模块配置的 JSON Schema	schema --module PowerAccent --resource settings

其中 set 方法声明了 implementsPretest: true 且返回 stateAndDiff。这一点在 SetState 实现 中可以得到印证：先调用 GetState 捕获差异，仅当 TestState() 判定状态不一致时才真正执行写入，随后输出当前状态与 diff 两行 JSON。

可配置属性

PowerAccent 模块支持以下可配置属性：

ActivationKey

设置哪个键触发重音字符选择。

• 类型： string
• 允许值：
  • "LeftRightArrow" — 按住左/右方向键
  • "Space" — 按住空格键
  • "Both" — 按住左/右方向键或空格键
• 默认值： "Both"

InputTime

设置激活键需要按住多久（毫秒）后才弹出重音选择工具条。

• 类型： integer
• 范围： 100 ~ 1000
• 默认值： 300

源码中该默认值由 PowerAccentSettings.cs 的 DefaultInputTimeMs = 300 常量确认，并注释要求与 PowerAccentKeyboardService.PowerAccentSettings.inputTime 保持一致。

ExcludedApps

列出 Power Accent 在这些应用中禁用的可执行文件名。

• 类型： string（换行分隔的可执行文件名列表）

ToolbarPosition

设置重音选择工具条相对光标的位置。

• 类型： string
• 允许值：
  • "Top" — 光标上方
  • "Bottom" — 光标下方
  • "Left" — 光标左侧
  • "Right" — 光标右侧
  • "Center" — 屏幕居中
• 默认值： "Top"

ShowUnicodeDescription

控制是否为每个重音字符显示 Unicode 描述（字符名称）。

• 类型： boolean
• 默认值： false

SortByUsageFrequency

控制重音字符是否按使用频率排序。

• 类型： boolean
• 默认值： false

StartSelectionFromTheLeft

控制选择光标是否从左侧开始。

• 类型： boolean
• 默认值： false

与设置模型源码的对应关系

上述 DSC 属性最终会写入 PowerToys 的统一设置文件。从 PowerAccentProperties.cs 的设置模型可以看到这些属性对应的真实 JSON 字段名与更多默认值：

DSC 属性	设置文件字段（JsonPropertyName）	类型	默认值
ActivationKey	activation_key	枚举	Both
InputTime	input_time_ms	int	300
ExcludedApps	excluded_apps	string	空
ToolbarPosition	toolbar_position	string	"Top center"
ShowUnicodeDescription	show_description	bool	false
SortByUsageFrequency	sort_by_usage_frequency	bool	false
StartSelectionFromTheLeft	start_selection_from_the_left	bool	false
（模块内部字段）	hold_duration_ms	int	500
（模块内部字段）	selected_lang	string	"ALL"
（模块内部字段）	do_not_activate_on_game_mode	bool	true

可以注意到两点差异：一是设置模型中 toolbar_position 的默认字符串为 "Top center"，DSC 文档将其归一为 "Top"；二是 hold_duration_ms、selected_lang、do_not_activate_on_game_mode 等字段存在于设置模型中，但未列入本文档的 DSC 可配置属性清单，说明当前 DSC 资源对外暴露的是上面 7 个核心属性。模块名的映射也值得留意：PowerAccentSettings.cs 中 ModuleName 为 "QuickAccent"，DSC 资源类型却命名为 PowerAccentSettings，两者分别对应「设置文件名」与「DSC 资源名」两个层面。

三种使用方式

PowerToys DSC 支持三种使用方式（详见 DSC 总览）：

1. 直接执行 PowerToys.DSC.exe：适合脚本化、即席修改；
2. DSC 配置文档（dsc config set）：适合纳入版本控制的声明式配置；
3. WinGet Configuration（winget configure）：适合在安装 PowerToys 的同一份清单中顺带配置模块。

下文示例将这三种方式全部覆盖。

示例

示例 1：直接执行配置激活方式

此示例将空格键设为激活键，并将触发时长设为 250 毫秒。

$config = @{
    settings = @{
        properties = @{
            ActivationKey = "Space"
            InputTime = 250
        }
        name = "PowerAccent"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

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

示例 2：用 DSC 配置工具条外观

此示例自定义工具条位置与显示选项。

dsc config set --file poweraccent-toolbar.dsc.yaml

# poweraccent-toolbar.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure Power Accent toolbar
    type: Microsoft.PowerToys/PowerAccentSettings
    properties:
      settings:
        properties:
          ToolbarPosition: Bottom
          ShowUnicodeDescription: true
          SortByUsageFrequency: true
        name: PowerAccent
        version: 1.0

示例 3：WinGet 安装并配置

此示例安装 PowerToys，并为多语言输入配置 Power Accent。

winget configure winget-poweraccent.yaml

# winget-poweraccent.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 Accent
    type: Microsoft.PowerToys/PowerAccentSettings
    properties:
      settings:
        properties:
          ActivationKey: Space
          InputTime: 300
          ToolbarPosition: Top
          SortByUsageFrequency: true
        name: PowerAccent
        version: 1.0

示例 4：快速触发配置

此示例针对快速选择重音字符进行优化，把触发时长压到 150 毫秒并启用按使用频率排序。

dsc config set --file poweraccent-fast.dsc.yaml

# poweraccent-fast.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Fast accent activation
    type: Microsoft.PowerToys/PowerAccentSettings
    properties:
      settings:
        properties:
          InputTime: 150
          SortByUsageFrequency: true
        name: PowerAccent
        version: 1.0

注意 InputTime 的合法范围是 100 ~ 1000，150 已接近下限；取值过低可能导致在正常打字停顿中误触发工具条。

示例 5：排除指定应用

此示例将特定应用排除在 Power Accent 之外，避免在记事本和 WordPad 中弹起重音选择。

$config = @{
    settings = @{
        properties = @{
            ExcludedApps = "notepad.exe`nWordPad.exe"
        }
        name = "PowerAccent"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

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

其中 `n 为 PowerShell 的换行符转义，符合「换行分隔可执行文件名列表」的格式约定。

典型使用场景

多语言内容创作

为高效的多语言打字进行配置：空格键激活、按使用频率排序、不显示 Unicode 描述。

resources:
  - name: Multilingual configuration
    type: Microsoft.PowerToys/PowerAccentSettings
    properties:
      settings:
        properties:
          ActivationKey: Space
          SortByUsageFrequency: true
          ShowUnicodeDescription: false
        name: PowerAccent
        version: 1.0

语言学习

面向语言学习的配置：显示 Unicode 描述帮助记忆字符名称，并把触发时长放宽到 400 毫秒以减少误触。

resources:
  - name: Learning configuration
    type: Microsoft.PowerToys/PowerAccentSettings
    properties:
      settings:
        properties:
          ShowUnicodeDescription: true
          InputTime: 400
        name: PowerAccent
        version: 1.0

配置写入链路与验证

从源码调用链看，一条 DSC 配置到生效的过程大致如下：

1. PowerToys.DSC.exe（源码位于 src/dsc/v3/PowerToys.DSC）接收 set 命令与 --input JSON，由 SettingsResource 根据模块名分发到 SettingsFunctionData<PowerAccentSettings>；
2. 设置项使用 PowerAccentSettings / PowerAccentProperties 模型（来自 Settings.UI.Library）进行反序列化，字段按 JsonPropertyName 映射到 input_time_ms、excluded_apps 等设置文件键；
3. 模块侧的 set_config（见 dllmain.cpp）解析 JSON 后调用 save_to_settings_file() 持久化，异常 JSON 会被静默忽略并保留旧配置。

由于 set 与 test 均返回状态和 diff（stateAndDiff: true），你可以用如下方式验证配置是否已收敛到期望状态：

PowerToys.DSC.exe test --resource 'settings' --module PowerAccent --input $config

相关单元测试可参考 PowerToys.DSC.UnitTests 下的 SettingsResource*ModuleTest 系列测试。

参考资料

• PowerToys DSC 总览
• Settings Resource 参考
• Workspaces 模块 DSC 文档
• Quick Accent 开发文档
• 源码入口：SettingsResource.cs、PowerAccentProperties.cs、PowerAccent 模块接口