状态栏与进度

状态栏是编辑器底部常驻信息的黄金位置：显示实时状态、承载快捷操作。配合进度条，能向用户清晰展示后台任务的执行过程。

状态栏项 createStatusBarItem

window.createStatusBarItem 创建状态栏项：

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  // 创建状态栏项
  const statusBar = vscode.window.createStatusBarItem(
    vscode.StatusBarAlignment.Right,  // 对齐位置
    100                               // 优先级（越大越靠前）
  );

  statusBar.text = '$(sync) 同步中';  // 文本（支持图标语法）
  statusBar.tooltip = '点击查看详情';  // 悬停提示
  statusBar.command = 'myExt.syncNow'; // 点击执行的命令
  statusBar.color = new vscode.ThemeColor('statusBarItem.warningBackground');

  statusBar.show();
  context.subscriptions.push(statusBar);
}

对齐与优先级

配置	说明
StatusBarAlignment.Left	左侧区域（编辑器相关内容）
StatusBarAlignment.Right	右侧区域（状态信息）
priority	数字越大越靠近边缘

同一对齐区域内按优先级排序：

右侧区域：[item(100)] [item(50)] [item(0)]
左侧区域：[item(0)] [item(50)] [item(100)]

状态栏文本语法

text 属性支持图标与文本组合：

写法	效果
$(sync)	仅图标
$(sync) 同步中	图标 + 文本
100%	纯文本
$(check) 就绪	状态反馈

常用内置图标：$(check)、$(warning)、$(error)、$(sync)、$(bell)、$(cloud)。

颜色配置

配置	说明
color	直接颜色值（#ff0000）或主题色
backgroundColor	背景色（突出显示）
ThemeColor	跟随主题的语义色

// 使用主题色
statusBar.color = new vscode.ThemeColor('statusBarItem.errorForeground');

// 使用背景色突出
statusBar.backgroundColor = new vscode.ThemeColor(
  'statusBarItem.errorBackground'
);

Tooltip 与 Command

statusBar.tooltip = '点击立即同步';
statusBar.command = 'myExt.syncNow';

设置 command 后，用户点击状态栏项即执行该命令。这是状态栏作为快捷入口的核心用法。

更新与清理

状态栏项是 Disposable，必须管理生命周期：

// 更新文本
statusBar.text = `文件数: ${count}`;

// 隐藏
statusBar.hide();

// 销毁（加入 subscriptions 后自动处理）
statusBar.dispose();

进度条 withProgress

需要展示耗时任务进度时使用 window.withProgress：

await vscode.window.withProgress(
  {
    location: vscode.ProgressLocation.Notification,  // 位置
    title: '正在处理...',
    cancellable: true                                 // 是否可取消
  },
  async (progress, token) => {
    // 模拟分步任务
    for (let i = 0; i <= 100; i += 10) {
      // 检查是否被取消
      if (token.isCancellationRequested) {
        break;
      }
      // 更新进度
      progress.report({ increment: 10, message: `处理 ${i}%` });
      await sleep(200);
    }
  }
);

ProgressLocation 位置

位置	展示方式
ProgressLocation.Notification	右下角通知（带进度条）
ProgressLocation.Window	窗口右下角（不打扰）
ProgressLocation.SourceControl	源码控制视图内

进度报告

// 按增量
progress.report({ increment: 20 });

// 带消息
progress.report({ increment: 20, message: '正在下载依赖...' });

// 不定量（indeterminate 样式）
progress.report({ message: '准备中...' });

可取消

设置 cancellable: true 后，用户可点击取消按钮：

const token = ...; // withProgress 回调第二参数
if (token.isCancellationRequested) {
  return;  // 提前退出
}
token.onCancellationRequested(() => {
  console.log('任务被用户取消');
});

任务栏图标 badge

Windows 任务栏图标显示 badge 需要配合 Electron API，插件中可用 withProgress 的 Notification 位置获得类似效果。若要在状态栏模拟 badge，可组合图标与文本：

statusBar.text = `$(bell) ${unreadCount}`;
statusBar.tooltip = '未读消息';

完整示例：构建状态监控

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  // 状态栏：构建状态
  const buildStatus = vscode.window.createStatusBarItem(
    vscode.StatusBarAlignment.Left,
    50
  );
  buildStatus.text = '$(circle-outline) 待构建';
  buildStatus.show();
  context.subscriptions.push(buildStatus);

  // 命令：触发构建
  context.subscriptions.push(
    vscode.commands.registerCommand('myExt.build', async () => {
      buildStatus.text = '$(sync~spin) 构建中...';

      try {
        await vscode.window.withProgress(
          {
            location: vscode.ProgressLocation.Notification,
            title: '构建项目',
            cancellable: false
          },
          async (progress) => {
            // 模拟构建步骤
            progress.report({ message: '编译...' });
            await sleep(500);
            progress.report({ increment: 50, message: '打包...' });
            await sleep(500);
          }
        );
        buildStatus.text = '$(check) 构建成功';
        buildStatus.color = new vscode.ThemeColor('charts.green');
      } catch (error) {
        buildStatus.text = '$(error) 构建失败';
        buildStatus.color = new vscode.ThemeColor('charts.red');
        vscode.window.showErrorMessage('构建失败');
      }
    })
  );
}

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

常见问题

问题	处理
状态栏不显示	忘记调用 show()
顺序不对	调整 priority 值
进度条无反应	progress.report 需要 increment 参数
图标不显示	检查 $(id) 语法与图标名

状态栏与进度是插件「常驻信息」与「过程反馈」的标准方案，让插件状态一目了然。