用途
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