用途
本技能用于为 PowerToys 命令面板(Command Palette)扩展添加设置页面。通过内置的设置辅助工具,扩展可以提供用户可配置的选项,且设置由扩展宿主自动持久化和恢复。
主要能力
- 为扩展添加用户可配置选项。
- 创建功能开关(Toggle)。
- 添加文本输入字段用于配置。
- 创建下拉菜单用于选项选择。
- 跨会话持久化用户偏好设置。
- 通过 SettingsChanged 事件实时响应设置变化。
- 对设置进行分组管理。
使用方式
第 1 步:创建设置管理器
创建新文件 SettingsManager.cs:
using Microsoft.CommandPalette.Extensions;
using Microsoft.CommandPalette.Extensions.Toolkit;
namespace YourExtension;
internal sealed class SettingsManager
{
private readonly Settings _settings;
public SettingsManager()
{
_settings = new Settings();
var maxResults = new TextSetting(
"maxResults",
"Maximum Results",
"Maximum number of results to display",
"10");
var showSubtitles = new ToggleSetting(
"showSubtitles",
"Show Subtitles",
"Display subtitle text under each result",
true);
var sortOrder = new ChoiceSetSetting(
"sortOrder",
"Sort Order",
"How to sort results",
[
new ChoiceSetSetting.Choice("Alphabetical", "alpha"),
new ChoiceSetSetting.Choice("Most Recent", "recent"),
new ChoiceSetSetting.Choice("Most Used", "frequent"),
],
"alpha");
_settings.AddSetting(maxResults);
_settings.AddSetting(showSubtitles);
_settings.AddSetting(sortOrder);
// React to settings changes
_settings.SettingsChanged += OnSettingsChanged;
}
public ICommandSettings Settings => _settings;
public int MaxResults => int.TryParse(
_settings.GetSetting<string>("maxResults"), out var val) ? val : 10;
public bool ShowSubtitles =>
_settings.GetSetting<bool>("showSubtitles");
public string SortOrder =>
_settings.GetSetting<string>("sortOrder") ?? "alpha";
private void OnSettingsChanged(object? sender, EventArgs e)
{
// React to settings changes (e.g., refresh data)
}
}
第 2 步:接入 CommandProvider
在 CommandsProvider 中暴露设置:
public partial class MyCommandsProvider : CommandProvider
{
private readonly SettingsManager _settingsManager = new();
private readonly ICommandItem[] _commands;
public MyCommandsProvider()
{
DisplayName = "My Extension";
Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
Settings = _settingsManager.Settings; // This exposes settings to CmdPal
_commands = [
new CommandItem(new MyPage(_settingsManager)) { Title = DisplayName },
];
}
public override ICommandItem[] TopLevelCommands() => _commands;
}
第 3 步:在页面中使用设置
internal sealed partial class MyPage : ListPage
{
private readonly SettingsManager _settings;
public MyPage(SettingsManager settings)
{
_settings = settings;
}
public override IListItem[] GetItems()
{
var items = GetAllItems();
return items.Take(_settings.MaxResults).ToArray();
}
}
设置类型
| 类型 | UI 控件 | 值类型 | 构造函数参数 |
|---|---|---|---|
| ToggleSetting | 开关 | bool | (id, label, description, defaultValue) |
| TextSetting | 文本输入 | string | (id, label, description, defaultValue) |
| ChoiceSetSetting | 下拉菜单 | string | (id, label, description, choices[], defaultValue) |
要点
- 设置由 CmdPal 宿主自动持久化。
- 使用 SettingsChanged 事件实时响应变化。
- 通过 GetSetting<T>(id) 使用设置的字符串 id 访问值。
- 将设置管理器传递给需要配置的页面/命令。
- 在 CommandProvider 上设置 Settings 后,设置页面会自动出现。
对设置进行分组
对于设置较多的扩展,可将它们组织为逻辑分组:
public SettingsManager()
{
_settings = new Settings();
// Appearance group
var theme = new ChoiceSetSetting("theme", "Theme", "UI theme",
[
new ChoiceSetSetting.Choice("Light", "light"),
new ChoiceSetSetting.Choice("Dark", "dark"),
new ChoiceSetSetting.Choice("System", "system"),
],
"system");
var fontSize = new TextSetting("fontSize", "Font Size", "Display font size", "14");
// Behavior group
var autoRefresh = new ToggleSetting("autoRefresh", "Auto-Refresh",
"Automatically refresh results", true);
var refreshInterval = new TextSetting("refreshInterval", "Refresh Interval",
"Seconds between auto-refreshes", "30");
_settings.AddSetting(theme);
_settings.AddSetting(fontSize);
_settings.AddSetting(autoRefresh);
_settings.AddSetting(refreshInterval);
}
响应变更
使用 SettingsChanged 事件在用户修改设置时更新行为:
private void OnSettingsChanged(object? sender, EventArgs e)
{
// Invalidate cached data
_cachedItems = null;
// Notify pages to refresh
OnItemsChanged?.Invoke(this, EventArgs.Empty);
}
文档
SampleSettingsPage.cs
适用场景
- 为扩展添加用户可配置选项。
- 为功能创建开关。
- 添加文本输入字段用于配置。
- 创建下拉菜单用于选项选择。
- 跨会话持久化用户偏好。
限制
除上述内容外,相关资料未提供更多关于平台限制或版本要求的信息。