SuperAPI AI 工具集

add-extension-settings

编程与开发

查看项目

更新于 10-16 14:10

技能介绍

用途

本技能用于为 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

适用场景

  • 为扩展添加用户可配置选项。
  • 为功能创建开关。
  • 添加文本输入字段用于配置。
  • 创建下拉菜单用于选项选择。
  • 跨会话持久化用户偏好。

限制

除上述内容外,相关资料未提供更多关于平台限制或版本要求的信息。