SuperAPI AI 工具集

add-dock-band

编程与开发

查看项目

更新于 10-16 14:10

技能介绍

用途

Command Palette Dock 是常驻在用户屏幕边缘的持久工具栏。扩展可以提供 dock bands —— 即出现在 Dock 中的一组条目条带 —— 让用户无需打开完整的 Command Palette,就能快速访问命令。

何时使用此技能

  • 向持久工具栏添加快速访问按钮
  • 创建多按钮的工具栏条带
  • 显示实时更新的信息(时钟、CPU 使用率等)
  • 无需打开完整调色板即可提供常用命令

前置条件

  • Command Palette Extension SDK 版本 0.9 或更高(Microsoft.CommandPalette.Extensions ≥ 0.9.260303001)

快速开始:单按钮 Dock Band

在 CommandProvider 中重写 GetDockBands():

public partial class MyCommandsProvider : CommandProvider
{
    private readonly ICommandItem[] _commands;
    private readonly ICommandItem _dockBand;

    public MyCommandsProvider()
    {
        DisplayName = "My Extension";
        Id = "com.mycompany.myextension"; // Unique ID required for dock

        var mainPage = new MyPage();
        _dockBand = new CommandItem(mainPage) { Title = DisplayName };
        _commands = [new CommandItem(mainPage) { Title = DisplayName }];
    }

    public override ICommandItem[] TopLevelCommands() => _commands;

    public override ICommandItem[]? GetDockBands() => [_dockBand];
}

多按钮 Dock Band

使用 WrappedDockItem 创建包含多个按钮的条带:

public override ICommandItem[]? GetDockBands()
{
    var button1 = new ListItem(new OpenUrlCommand("https://github.com"))
    {
        Title = "GitHub",
        Icon = new IconInfo("\uE774"),
    };
    var button2 = new ListItem(new OpenUrlCommand("https://learn.microsoft.com"))
    {
        Title = "Learn",
        Icon = new IconInfo("\uE82D"),
    };

    var band = new WrappedDockItem(
        [button1, button2],
        "com.mycompany.myextension.quicklinks", // Unique band ID
        "Quick Links");

    return [band];
}

实时更新的 Dock Band

创建一个会周期性更新内容的 dock band(例如时钟):

internal sealed partial class LiveStatusBand : ListItem
{
    private readonly System.Timers.Timer _timer;

    public LiveStatusBand()
        : base(new NoOpCommand() { Result = CommandResult.KeepOpen() })
    {
        Title = DateTime.Now.ToString("HH:mm");
        Icon = new IconInfo("\uE823"); // Clock icon

        _timer = new System.Timers.Timer(60_000); // Update every minute
        _timer.Elapsed += (s, e) =>
        {
            Title = DateTime.Now.ToString("HH:mm");
            Subtitle = DateTime.Now.ToString("dddd, MMMM d");
        };
        _timer.Start();
    }
}

// In CommandProvider:
public override ICommandItem[]? GetDockBands()
{
    var band = new WrappedDockItem(
        [new LiveStatusBand()],
        "com.mycompany.myextension.status",
        "Live Status");
    return [band];
}

Dock Band 的渲染方式

ICommandItem 上的命令类型 Dock 行为
IInvokableCommand 执行命令的单个按钮
IListPage 每个列表项在一个条带中渲染为单独的按钮
IContentPage 带弹出浮层的单个可展开按钮

支持固定嵌套命令

默认情况下,只有顶层命令和 dock bands 可以被固定(pinned)。若要允许固定嵌套命令:

public override ICommandItem? GetCommandItem(string id)
{
    // Look up commands by their Id
    foreach (var item in GetAllCommands())
    {
        if (item?.Command is ICommand cmd && cmd.Id == id)
            return item;
    }
    return null;
}

重要说明

  • 所有 dock band 的 ICommandItem 对象必须具有带非空 Id 的 Command —— 没有 ID 的条目会被忽略
  • 在 CommandProvider 上设置 Id(例如 Id = "com.mycompany.myextension")
  • 多按钮条带使用由 ListPage 支持的 WrappedDockItem
  • 保持 dock band 更新轻量 —— 它们会频繁运行

文档

  • Adding Dock support