文档教程【免费下载链接】vscode-docsPublic 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 PanelPrimary 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 ItemsPrimary左侧与整个工作区相关的元素状态、问题/警告、同步放在左侧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 ItemView Container去打开 Editor 中的 WebviewView Toolbar / Sidebar Toolbar / Editor Toolbar / Panel ToolbarView 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 ToolbarEditor Actions 直接作用于编辑器。可以添加一个图标作为快捷操作或把次要操作放入溢出菜单...。Panel ToolbarPanel 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 ElementsCommand 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 右下角浮现用于展示简要信息。有三种类型信息Informationwindow.showInformationMessage警告Warningwindow.showWarningMessage错误Errorwindow.showErrorMessage为了尊重用户的注意力发送通知前建议遵循官方通知决策树如果立即需要多步骤用户输入用多步 Quick Pick如果是立即需要但非多步的用户输入用模态对话框如果是低优先级进度把进度放到状态栏如果是用户触发的交互找到合适的时机再显示通知如果有多条通知尽量合并为一条如果用户并不真的需要被通知考虑什么都不显示。通知的✔️ 应当与❌ 不应✔️ 应当❌ 不应仅在绝对必要时发送通知重复发送通知用于推广为每条通知添加Do not show again选项首次安装就索要反馈一次只显示一条通知没有操作却显示操作按钮进度通知当需要在不确定时间内展示进度如搭建环境时可使用进度通知但应作为最后手段——进度最好保持在上下文内View 或 Editor 中。使用时提供查看详情如日志的链接、随进度更新信息initializing、building 等、提供取消操作如适用、为超时场景添加计时器不要留下永不结束的运行中通知。模态对话框Modal Dialog当需要立即获取用户输入时可以使用模态对话框但它会阻塞对话框之外的所有用户交互必须谨慎使用。只用于需要立即交互的场景适当提供Always/Never操作避免重复确认可考虑用复选框记住用户选择。不要用它确认多步骤、不要用它展示无需用户操作的消息、不要为用户未显式发起的操作弹模态框。WebviewsWebviews 用于展示超出 VS Code 原生 API 能力的自定义内容与功能完全可定制。但要明确只有绝对需要时才使用 Webview。✔️ 应当❌ 不应仅在绝对必要时使用 Webview用于推广升级、赞助等仅在上下文合适时激活扩展、仅为活动窗口打开 Webview用于向导wizards确保视图内所有元素可主题化参考 theme-color在每次打开窗口时都打开遵循 无障碍指南颜色对比、ARIA 标签、键盘导航在扩展更新时自动打开改用 Notification 询问在工具栏和视图内使用命令操作添加与编辑器或工作区无关的功能重复已有功能Welcome 页、Settings、配置等Webview ViewsWebview 也可以放进任何 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 数量以 35 个为舒适上限图标按钮、通知、状态栏项都应尽量克制。贴近原生语言图标优先用现有图标库与 product icons命令名加 category 前缀命令用动词避免 emoji 与自定义配色。尊重用户注意力与可控性通知只在必要时发且提供 Do not show again模态对话框只用于用户主动触发的、需要立即交互的场景为每个 View 提供图标因为可能被拖到 Activity Bar 或 Secondary Sidebar。延伸阅读UX Guidelines 目录Activity Bar、Sidebars、Views、Panel、Status Bar、Command Palette、Quick Picks、Notifications、Editor Actions、Context Menus、Walkthroughs、Settings、Webviews 各细分指南Contribution Points 参考viewsContainers、views、viewsWelcome、commands、menus、configuration、walkthroughs、customEditors 等所有贡献点声明方式Tree View 扩展指南View Actions 与树形视图实现Webview 扩展指南Webview 与 Webview View 的完整实现Command 扩展指南命令的注册、键盘快捷键与 Command Palette 集成Extending Workbench工作台扩展能力总览Theme Color 参考让扩展 UI 适配各颜色主题的颜色令牌Icons in Labels标签与工具栏中可用图标清单无障碍指南颜色对比、ARIA 标签与键盘导航要求。赞分享文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载相关推荐Visual Studio Code 扩展命令面板Command PaletteUX 设计指南Visual Studio Code 扩展命令面板Command PaletteUX 设计指南 命令面板Command Palette是 Visual文档教程Visual Studio Code 扩展 Webview 与 Webview View 的 UX 设计指南Visual Studio Code 扩展 Webview 与 Webview View 的 UX 设计指南 Webview 是 VS Code 扩展 API文档教程Visual Studio Code 扩展状态栏Status BarUX 设计指南分组布局、进度提示与错误警示的最佳实践Visual Studio Code 扩展状态栏Status BarUX 设计指南分组布局、进度提示与错误警示的最佳实践 状态栏Status Bar位文档教程上一篇桌面版Spotify歌词缺失免费开源的实时歌词显示工具3步就能用起来下一篇FastLED lint-agent 角色解析基于 bash lint 的代码质量检查工作流与底层实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考