Visual Studio Code 扩展 UX 指南：工作台容器、界面元素与设计最佳实践-育师

文档
教程

【免费下载链接】vscode-docs

Public documentation for Visual Studio Code

项目地址：https://gitcode.com/gh_mirrors/vs/vscode-docs

本文基于 VS Code 官方文档仓库的 UX Guidelines 总览编写，系统讲解 VS Code 工作台（Workbench）的 UI 架构——容器（Containers）与元素（Items）两大概念，以及扩展可以贡献的各类常用界面元素（Command Palette、Quick Pick、Notifications、Webviews、Context Menus、Walkthroughs、Settings 等）。读完本文，你将理解扩展的 UI 应落在工作台的哪个位置、每种容器的职责与适用场景，以及如何遵循官方最佳实践，让你的扩展界面与 VS Code 原生交互无缝融合，而不是"看起来像另一个应用"。

理解 VS Code 工作台的 UI 架构：容器与元素

在深入细节之前，必须先理解 VS Code 各 UI 部件之间的架构关系，以及扩展能在何处、以何种方式贡献 UI。

VS Code 界面大体可划分为两个核心概念：容器（Containers）与元素（Items）。一般来说，容器是 VS Code 界面中较大的区块，负责渲染一个或多个元素：

容器：Activity Bar、Primary Sidebar、Secondary Sidebar、Editor、Panel、Status Bar 等工作台中的"大区域"。
元素：View、View Toolbar、Sidebar Toolbar、Editor Toolbar、Panel Toolbar、Status Bar Item 等被渲染在容器内的具体部件。

扩展既可以把元素贡献进上述容器，也可以贡献全新的容器（例如自定义 View Container）。选择哪个位置承载你的功能，直接决定了用户发现和使用它的效率。

容器（Containers）详解

Activity Bar（活动栏）

Activity Bar 是 VS Code 的核心导航面。扩展可以向 Activity Bar 贡献 View Containers，它们会以 Activity Bar Item（图标项）的形式出现。用户可以把这个图标拖拽到其他位置（如 Panel），以自定义布局。

官方给出的✔️ 应当与❌ 不应：

✔️ 应当	❌ 不应
使用与默认 Activity Bar 项一致的图标风格	重复使用已有的图标
为关联的 View Container 使用清晰、明确的名字	用 Activity Bar Item 去打开一个 Webview Panel

Primary Sidebar（主侧边栏）

Primary Sidebar 渲染一个或多个 Views。Activity Bar 与 Primary Sidebar 紧密耦合：点击一个贡献的 Activity Bar Item（即 View Container），会打开 Primary Sidebar，并渲染与该 View Container 关联的一个或多个 View。

一个具体例子就是资源管理器（Explorer）：点击 Explorer 图标，Primary Sidebar 中会显示文件夹（Folders）、时间线（Timeline）和大纲（Outline）等 View。由于主侧边栏可见性高，很多扩展选择把 View 贡献到这里，但要注意控制数量——过多的贡献 UI 会造成界面杂乱、让用户困惑。

Secondary Sidebar（辅助侧边栏）

Secondary Sidebar 同样可以承载 View Container 和 View。默认情况下扩展不能直接把 View 贡献到辅助侧边栏，但用户可以手动把 View（例如 Terminal 或 Problems）拖到辅助侧边栏来定制布局。它通常被视为 View 的"辅助位置"。

Editor（编辑器区域）

Editor 区域包含一个或多个Editor Group。扩展可以通过以下方式贡献到该区域：

贡献 Custom Editors 或 Webviews，使其在 Editor 区域打开；
贡献 Editor Actions，在 Editor Toolbar 中暴露额外的图标按钮。

Panel（面板）

Panel 是另一个展示 View Containers 的区域。默认情况下，Terminal、Problems、Output 等 View 在 Panel 中每次只显示一个标签页；用户也可以像在 Editor 中一样把 View 拖成分栏布局。扩展可以专门为 Panel 添加 View Container，而不是放到 Activity Bar / Primary Sidebar。

Panel 的✔️ 应当与❌ 不应：

✔️ 应当	❌ 不应
把受益于更多横向空间的 View 渲染在 Panel 中	把需要始终可见的 View 放在 Panel（用户常会最小化 Panel）
用 Panel 承载提供支撑性功能的 View	渲染那些被拖到其他 View Container（如主/辅助侧边栏）后无法正确重排或缩放的 Webview 内容

Status Bar（状态栏）

Status Bar 位于工作台底部，显示与工作区相关的信息和操作。它渲染两组Status Bar Items：

Primary（左侧）：与整个工作区相关的元素（状态、问题/警告、同步）放在左侧；
Secondary（右侧）：次要或上下文相关的元素（语言、缩进、反馈）放在右侧。

由于其他扩展也贡献到同一区域，务必限制添加的项数。

元素（Items）详解

扩展可以向上述各种容器中添加元素：

View（视图）

Views 是可以出现在 Sidebar 或 Panel 的内容容器，具体形态包括：

Tree View：树形视图，适合展示数据；
Welcome View：空状态引导视图；
Webview View：基于 Webview 的自定义视图。

View 可以被用户重新排列，或移动到另一个 View Container（例如从 Primary Sidebar 移到 Secondary Sidebar）。Views 的✔️ 应当与❌ 不应：

✔️ 应当	❌ 不应
尽可能使用现有图标；语言文件使用文件图标	重复已有功能
展示数据时使用 Tree View	把树节点当作单一操作项（如点击即触发 Command）
给每个 View 都加上图标（它可能被移到 Activity Bar 或 Secondary Sidebar，这两处都用图标表示 View）	非必要不使用自定义 Webview View
控制 View 数量与名称长度	用 Activity Bar Item（View Container）去打开 Editor 中的 Webview

View Toolbar / Sidebar Toolbar / Editor Toolbar / Panel Toolbar

View Toolbar：扩展可以在 View Toolbar 上暴露 View 专属的 View Actions，按钮不宜过多，优先使用内置 product icon，必要时可提供 SVG 自定义图标。
Sidebar Toolbar：作用于整个 View Container 的操作可以放在 Sidebar Toolbar。默认情况下，包含多个 View 的 View Container 会在 Sidebar Toolbar 显示一个...按钮用于显示/隐藏各 View；如果只有一个 View，侧边栏会自动合并 UI，把该 View 的所有操作直接渲染在 Sidebar Toolbar 中，替代...按钮。
Editor Toolbar：Editor Actions 直接作用于编辑器。可以添加一个图标作为快捷操作，或把次要操作放入溢出菜单（...）。
Panel Toolbar：Panel Toolbar 暴露与当前选中 View 相关的选项。例如 Terminal View 会暴露新建终端、分栏等操作，切换到 Problems View 则显示另一组操作。与 Sidebar Toolbar 类似，只有单个 View 时工具栏才统一渲染；多个 View 时每个 View 渲染各自的工具栏。

各 Toolbar 的共同✔️ 应当与❌ 不应：

✔️ 应当	❌ 不应
仅在上下文合适时显示（例如 GitHub Pull Requests 扩展只在有变更的文件上显示打开 diff 的按钮）	添加超过一个图标
优先使用图标库中的现有图标（可参考 icons-in-labels）	添加自定义颜色
用溢出菜单承载次要操作；提供清晰有用的 tooltip	使用 emoji；重复 Panel 默认图标（折叠/展开、关闭等）
需要更多选项时，考虑用 Context Menu 承载	添加过多图标按钮造成杂乱

Status Bar Item（状态栏项）

左侧的 Status Bar Items 作用于整个工作区，右侧的则作用于当前活动文件。关于 Status Bar Item 的✔️ 应当与❌ 不应：

✔️ 应当	❌ 不应
使用短文本标签	添加自定义颜色
仅在必要时、且隐喻清晰时使用图标	添加超过一个图标（除非必要）
全局项放左、上下文项放右	添加超过一个项（除非必要）

进度类 Status Bar Item：当需要显示低调的后台进度时（可带旋转动画），推荐使用带加载图标的 Status Bar Item；若进度需要提升用户关注度，则改用进度通知。错误/警告类 Status Bar Item：可通过配置让 Status Bar Item 使用警告或错误背景色来高亮展示，但这种模式因为过于醒目，只能作为最后手段、仅用于特殊情况。

常用 UI 元素（Common UI Elements）

Command Palette（命令面板）

Command Palette 是查找所有 Command 的地方，命令命名是否清晰直接决定用户能否找到它：

✔️ 应当	❌ 不应
在合适的地方添加键盘快捷键	覆盖已有快捷键
使用清晰命名的命令	在命令名中使用 emoji
把命令按同一 category 分组（例如 "GitHub Issues" 前缀）	—

命令的贡献方式可参考 Commands 贡献点与 Command 扩展指南。

Quick Pick（快速选择器）

Quick Picks 用于执行操作和接收用户输入，适合选择配置项、过滤内容或从列表中选择。支持单选、多选，甚至自由文本输入。

多步骤（Multiple steps）：可用于在一个流程中捕获"相关但相互独立"的多次选择（标题中会显示如 "1/3" 的步骤指示），但不要用来实现向导式的长流程。

多选（Multiple selections）：适合在一行内选择紧密相关的多个选项。标题（Title）：当用户需要更多上下文时可显示标题栏，但避免重复使用输入 placeholder 中的文案。分隔符（Separators）：当列表包含多个明显分组时，用带分隔线与标签的分隔符分组。

Quick Pick 的✔️ 应当与❌ 不应：

✔️ 应当	❌ 不应
使用语义清晰的图标帮助区分选项	重复已有功能
用 description 展示当前项、用 detail 提供简短额外上下文	当 placeholder 已能自述用途时再使用标题
从列表中选择时提供"新建项"的选项；多步流程与无文本输入、需文本输入、含全局按钮（如刷新图标）时使用标题	使用没有 placeholder 的输入

Notifications（通知）

Notifications 从 VS Code 右下角浮现，用于展示简要信息。有三种类型：

信息（Information）：window.showInformationMessage
警告（Warning）：window.showWarningMessage
错误（Error）：window.showErrorMessage

为了尊重用户的注意力，发送通知前建议遵循官方"通知决策树"：如果立即需要多步骤用户输入，用多步 Quick Pick；如果是立即需要但非多步的用户输入，用模态对话框；如果是低优先级进度，把进度放到状态栏；如果是用户触发的交互，找到合适的时机再显示通知；如果有多条通知，尽量合并为一条；如果用户并不真的需要被通知，考虑什么都不显示。

通知的✔️ 应当与❌ 不应：

✔️ 应当	❌ 不应
仅在绝对必要时发送通知	重复发送通知；用于推广
为每条通知添加Do not show again选项	首次安装就索要反馈
一次只显示一条通知	没有操作却显示操作按钮

进度通知：当需要在不确定时间内展示进度（如搭建环境）时可使用进度通知，但应作为最后手段——进度最好保持在上下文内（View 或 Editor 中）。使用时：提供查看详情（如日志）的链接、随进度更新信息（initializing、building 等）、提供取消操作（如适用）、为超时场景添加计时器；不要留下永不结束的运行中通知。

模态对话框（Modal Dialog）：当需要立即获取用户输入时可以使用模态对话框，但它会阻塞对话框之外的所有用户交互，必须谨慎使用。只用于需要立即交互的场景；适当提供Always/Never操作避免重复确认；可考虑用复选框记住用户选择。不要用它确认多步骤、不要用它展示无需用户操作的消息、不要为用户未显式发起的操作弹模态框。

Webviews

Webviews 用于展示超出 VS Code "原生" API 能力的自定义内容与功能，完全可定制。但要明确：只有绝对需要时才使用 Webview。

✔️ 应当	❌ 不应
仅在绝对必要时使用 Webview	用于推广（升级、赞助等）
仅在上下文合适时激活扩展、仅为活动窗口打开 Webview	用于向导（wizards）
确保视图内所有元素可主题化（参考 theme-color）	在每次打开窗口时都打开
遵循无障碍指南（颜色对比、ARIA 标签、键盘导航）	在扩展更新时自动打开（改用 Notification 询问）
在工具栏和视图内使用命令操作	添加与编辑器或工作区无关的功能；重复已有功能（Welcome 页、Settings、配置等）

Webview Views：Webview 也可以放进任何 View Container（侧边栏或面板），这类元素称为 Webview View，适用同样的 Webview 指南。典型例子包括：用 Webview Panel 渲染类似浏览器的预览窗口（Simple Browser）、在自定义 Tree View 中列出 PR 再用 Webview 渲染 PR 详情页、在 Webview View 中用下拉框/输入框/按钮构建创建 PR 的表单。

Context Menus（上下文菜单）

与 Command Palette 位置固定不同，Context Menus 让用户能在特定位置执行操作或进行配置。菜单项出现在 View、操作和右键菜单中，分组一致性至关重要：如果扩展有与文件相关的操作，放在资源管理器（File Explorer）的右键菜单中；如果操作只针对特定文件类型，就只为这些文件显示。

✔️ 应当	❌ 不应
仅在上下文合适时显示操作（例如 Copy GitHub Permalink 只在 GitHub 仓库的文件上出现）	不加区分地对每个文件都显示操作
把相似操作分组在一起	—
把大组操作放进子菜单	—

菜单的贡献方式见 Menus 贡献点。

Walkthroughs（引导教程）

Walkthroughs 通过一个多步骤的清单（含丰富内容）为用户提供一致的扩展上手体验。

✔️ 应当	❌ 不应
使用有助理解当前步骤的图片	单个 Walkthrough 中步骤过多
确保图片在不同颜色主题下都可用（优先使用带 VS Code Theme Colors 的 SVG）	非必要不添加多个 Walkthrough
为每个步骤提供操作（例如 "View all Commands"），尽量使用动词	—

Walkthroughs 的贡献方式见 Walkthroughs 贡献点。

Settings（设置）

Settings 是用户配置扩展的方式，可以是输入框、布尔值、下拉框、列表、键值对等。如果扩展要求用户配置特定设置，可以打开 Settings UI 并通过setting ID直接定位查询。

✔️ 应当	❌ 不应
为每个设置提供默认值	自己创建设置页/Webview
为每个设置提供清晰描述	编写过长的描述
复杂设置链接到文档；关联设置互相链接	—
需要用户配置特定设置时，用 setting ID 直达链接	—

设置通过 Configuration 贡献点声明。

落地决策建议：你的扩展 UI 应该放哪里

综合以上全部指南，为扩展功能选择 UI 位置的决策思路可以概括为：

优先使用最"轻"的界面：能被一个 Command 完成的动作，就不要做成侧边栏里的内容；能被原生 API 表达的，就不要引入 Webview。
按作用域选择容器：整个工作区的状态放状态栏左侧，当前文件的上下文放右侧；需要大量横向空间或属于支撑性功能的 View 放 Panel；需要高可见度的放 Primary Sidebar。
控制数量与噪声：View Container 一般一个就够，View 数量以 3～5 个为舒适上限；图标按钮、通知、状态栏项都应尽量克制。
贴近原生语言：图标优先用现有图标库与 product icons，命令名加 category 前缀，命令用动词，避免 emoji 与自定义配色。
尊重用户注意力与可控性：通知只在必要时发且提供 "Do not show again"；模态对话框只用于用户主动触发的、需要立即交互的场景；为每个 View 提供图标（因为可能被拖到 Activity Bar 或 Secondary Sidebar）。