VS Code 扩展 API 基础 — 速查手册

本参考随课程推进持续更新。当前覆盖：Lesson 0001 涉及的概念及后续问答补充。

package.json 扩展专有字段

SemVer 版本范围语法

"engines"、"dependencies"、"devDependencies" 中的版本号都使用 npm semver range 语法。最常用的是 ^（caret）和 ~（tilde）。

^ 的规则：锁定最左边非零段

^ 不是简单的"锁定 major"——它锁定的是最左边非零数字所在的段：

为什么 0.x 特别？semver 规定 0.y.z 阶段属于"初始开发"，任何 minor 变化都可能是不兼容的。所以 ^0.74.0 只覆盖 0.74.z，不覆盖 0.75.0。

激活事件速查

contributes.configuration — 用户配置项

扩展通过 contributes.configuration 向 VS Code 的 settings.json 注入配置项。数据流分三步：扩展声明 → 用户覆盖 → 代码读取。

配置项属性速查

类型决定 UI

代码中读取配置

import * as vscode from 'vscode';

// getConfiguration 的参数是配置前缀（package.json 中 properties 的公共前缀）
const config = vscode.workspace.getConfiguration('claudeContextBar');

// 读取单个值——如果用户没设置，返回 default
const threshold = config.get<number>('warningThreshold');  // → 50（默认值）或 60（用户改过）
const color = config.get<string>('baseColor');          // → "White"
const shortNames = config.get<object>('shortNames');     // → {}

// 泛型参数不是必需的，但推荐写上以获得类型提示
const autoColor = config.get('autoColor');  // 也可以

监听配置变化

// 用户在 settings.json 中修改时，扩展可以实时响应
vscode.workspace.onDidChangeConfiguration(event => {
    if (event.affectsConfiguration('claudeContextBar.warningThreshold')) {
        // 重新读取并更新 UI
        const newThreshold = vscode.workspace
            .getConfiguration('claudeContextBar')
            .get<number>('warningThreshold');
        updateStatusBar(newThreshold);
    }
});

编译与发布脚本

入口文件约定

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    // VS Code 加载扩展时调用
    // 在这里：注册命令、创建 UI 元素、设置监听器
    // context.subscriptions 用于管理资源的生命周期
}

export function deactivate() {
    // VS Code 停用扩展时调用（可选）
    // 在这里：清理定时器、关闭连接、释放资源
}

开发依赖清单（claude-context-bar）

claude-context-bar 的依赖非常精简——只有 3 个 devDependencies，没有运行时依赖。VS Code 本身提供了 vscode 模块，不需要安装。

StatusBarItem — 状态栏 UI 原语

状态栏条目是 claude-context-bar 使用的核心 UI 组件。通过 vscode.window.createStatusBarItem() 创建。

创建

const item = vscode.window.createStatusBarItem(
    vscode.StatusBarAlignment.Right,  // 对齐方向
    900                               // 优先级
);

对齐方向

核心属性

方法

ThemeColor — 主题自适应颜色

// 不要硬编码颜色——使用 ThemeColor 让 VS Code 根据主题自动解析
item.backgroundColor = new vscode.ThemeColor('statusBarItem.errorBackground');
item.backgroundColor = new vscode.ThemeColor('statusBarItem.warningBackground');

完整生命周期示例

// 1. 创建（默认隐藏）
const item = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right, 900);

// 2. 配置
item.text = '$(warning) My Project: 72%';
item.tooltip = new vscode.MarkdownString('**Token Usage**: 144K / 200K');
item.command = { command: 'myExt.showDetails', title: 'Show', arguments: ['arg'] };
item.backgroundColor = new vscode.ThemeColor('statusBarItem.warningBackground');

// 3. 显示
item.show();

// 4. 更新 —— 直接修改属性，VS Code 自动重绘
item.text = '$(error) My Project: 85%';
item.backgroundColor = new vscode.ThemeColor('statusBarItem.errorBackground');

// 5. 销毁
item.dispose();

TypeScript 基础（本课程需要的最低知识）