Flex Conditional Toolbar

一个灵活的 VSCode 工具栏按钮扩展，允许你通过 settings.json 自定义编辑器右上角的按钮，支持根据工作区文件状态和当前打开文件动态显示/隐藏。

功能特性

✅ 无数量限制 - 理论上可配置任意多个按钮
✅ 灵活标识 - 使用自定义 id 标识按钮，更直观
✅ 自定义排序 - 通过 order 字段控制按钮显示顺序
✅ 双重过滤 - 支持 glob（工作区文件）和 when（当前文件）双重过滤
✅ 自定义图标 - 支持 VSCode 内置图标或自定义 SVG 图标（支持明暗主题）
✅ 自定义悬停文字 - 为每个按钮设置个性化的提示文本
✅ Args 占位符 - 支持 ${find:glob} 自动查找文件路径等动态参数
✅ 即时响应 - 文件新建/删除、切换文件时自动更新按钮状态
✅ 诊断日志 - 内置输出面板日志，方便排查问题

安装

下载 .vsix 安装包
打开 VSCode，进入扩展面板（Ctrl+Shift+X）
点击右上角 更多操作 (···) → 从 VSIX 安装
选择下载的 .vsix 文件

使用方法

基础配置

打开 settings.json（Ctrl+Shift+P → 输入 "Preferences: Open Settings (JSON)"），添加如下配置：

{
  "flexToolbar.buttons": [
    {
      "id": "terminal",
      "command": "workbench.action.terminal.toggleTerminal",
      "icon": "terminal",
      "name": "切换终端",
      "order": 1
    }
  ]
}

配置项说明

字段	类型	必填	说明
`id`	string	✅	按钮唯一标识（如 terminal、build），不能重复
`command`	string	✅	VSCode 命令 ID（如 `workbench.action.terminal.toggleTerminal`）
`args`	object	❌	命令参数（可选），支持占位符自动解析（见下方说明）
`glob`	string	❌	工作区文件匹配规则，满足才显示（如 `*/.uvprojx`）。留空则始终显示
`when`	string	❌	当前打开文件的文件名匹配规则（正则表达式），如 `.*\.c$`。留空则不过滤当前文件
`icon`	string/object	❌	按钮图标（见下方示例）
`name`	string	❌	悬停提示文字，留空使用 `id` 作为名称
`order`	number	❌	排序序号，数字越小越靠前（默认按配置顺序）

双重过滤规则

配置组合	显示条件
两者都不配置	始终显示
仅配置 `glob`	工作区存在匹配文件时显示
仅配置 `when`	当前打开文件匹配时显示
两者都配置	工作区存在匹配文件且当前打开文件匹配时才显示

常用命令 ID 示例

{
  "flexToolbar.buttons": [
    {
      "id": "terminal",
      "command": "workbench.action.terminal.toggleTerminal",
      "icon": "terminal",
      "name": "终端",
      "order": 1
    },
    {
      "id": "saveAll",
      "command": "workbench.action.files.saveAll",
      "icon": "save-all",
      "name": "保存全部",
      "order": 2
    },
    {
      "id": "reload",
      "command": "workbench.action.reloadWindow",
      "icon": "refresh",
      "name": "重载窗口",
      "order": 3
    },
    {
      "id": "settings",
      "command": "workbench.action.openSettingsJson",
      "icon": "gear",
      "name": "设置",
      "order": 4
    }
  ]
}

Glob 规则示例

{
  "flexToolbar.buttons": [
    {
      "id": "build",
      "command": "your-extension.build",
      "glob": "**/*.uvprojx",
      "icon": "play",
      "name": "编译项目",
      "order": 1
    },
    {
      "id": "debug",
      "command": "your-extension.debug",
      "glob": "**/*.{c,h}",
      "when": ".*\\.(c|h)$",
      "icon": "bug",
      "name": "调试",
      "order": 2
    }
  ]
}

自定义图标

方式 A：使用 VSCode 内置图标

{
  "id": "terminal",
  "command": "workbench.action.terminal.toggleTerminal",
  "icon": "terminal"
}

常见内置图标：play, gear, zap, rocket, terminal, eye, bug, sync, add, file-code, save, refresh, check, close, debug-start, debug-stop

方式 B：使用自定义 SVG 图标（支持明暗主题）

{
  "id": "saveAll",
  "command": "workbench.action.files.saveAll",
  "icon": {
    "light": "C:/Users/YourName/icons/save_light.svg",
    "dark": "C:/Users/YourName/icons/save_dark.svg"
  },
  "name": "保存全部"
}

⚠️ 注意：图标路径必须使用绝对路径，且文件必须存在。

Args 占位符

args 中的字符串值支持以下占位符，在点击按钮时自动解析替换：

占位符	说明	示例结果
`${find:glob}`	在工作区中查找匹配 glob 的文件，返回第一个文件的绝对路径	`C:/Projects/myApp/project.cmw`
`${workspaceFolder}`	当前工作区根目录的绝对路径	`C:/Projects/myApp`
`${file}`	当前活动文件的绝对路径	`C:/Projects/myApp/src/main.c`
`${fileBasename}`	当前活动文件的文件名	`main.c`

💡 ${find:glob} 会先使用 VSCode 的 findFiles API 搜索，如果未找到则自动使用文件系统递归搜索作为兜底。

示例：自动查找项目文件并传递路径

{
  "flexToolbar.buttons": [
    {
      "id": "build",
      "command": "cms.project.build",
      "args": {
        "prjID": "${find:**/*.cmw}",
        "label": "MyProject",
        "contextValue": "CmsProject"
      },
      "glob": "**/*.cmw",
      "icon": "play",
      "name": "编译项目"
    }
  ]
}

点击按钮时，${find:**/*.cmw} 会自动替换为工作区中找到的第一个 .cmw 文件的绝对路径，实际执行效果等同于：

code --command "cms.project.build" --args '{"prjID":"C:/path/to/project.cmw","label":"MyProject","contextValue":"CmsProject"}'

示例：组合使用多个占位符

{
  "flexToolbar.buttons": [
    {
      "id": "compile",
      "command": "your-extension.compile",
      "args": {
        "project": "${workspaceFolder}",
        "source": "${file}",
        "sourceName": "${fileBasename}",
        "config": "${find:**/Makefile}"
      },
      "when": ".*\\.c$",
      "icon": "gear",
      "name": "编译当前文件"
    }
  ]
}

修改配置后生效

当你修改了 icon、name、id、order 配置后，插件会提示你重新加载 VSCode 以应用更改。你可以：

点击提示框的 重新加载 按钮
或手动执行命令：Developer: Reload Window（命令面板中搜索）

💡 提示：glob、when、command、args 的修改是即时生效的，无需重启。

手动刷新

如果配置与实际显示不一致，可以执行命令：

Flex Toolbar: Refresh

（通过命令面板 Ctrl+Shift+P 搜索）

诊断日志

插件内置了详细的日志输出，方便排查问题。查看方式：

打开 输出面板（Ctrl+Shift+U）
在右上角下拉菜单中选择 "Flex Toolbar"
点击按钮后即可看到完整的配置解析和命令执行日志

日志内容包括：

按钮注册信息
占位符解析过程（原始值 → 解析后值）
${find:glob} 搜索过程和结果
最终传递给命令的 args

常见问题

Q: 如何查找 VSCode 命令 ID？

A: 打开键盘快捷设置（Ctrl+K Ctrl+S），搜索功能名称，右键点击 → 复制命令 ID。

Q: 图标不显示怎么办？

A: 检查以下几点：

图标文件路径是否正确（使用绝对路径）
图标文件是否存在
是否使用了正确的格式（字符串或对象）
修改图标后是否重新加载了 VSCode

Q: 按钮为什么不显示？