文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载导读本指南以 VS Code 官方 UX 指南中的 Settings 章节为核心讲解扩展作者如何通过contributes.configuration声明点向用户暴露配置项让扩展设置原生融入 VS Code 的设置编辑器Settings UI并配合vscode.workspace.getConfiguration在代码中读取这些配置。读完本文你将掌握设置项的完整声明语法类型、枚举、作用域、排序、校验与弃用标记、configurationDefaults默认值覆盖机制以及绝不自建设置页等一系列可落地的 UX 最佳实践。一、设置Settings扩展与用户之间的配置通道在 VS Code 的扩展体系里设置是用户配置扩展行为的标准途径。用户在设置界面中可以见到扩展贡献的各类设置控件其形态包括输入框input box布尔开关boolean checkbox下拉菜单dropdown / enum列表array键值对key/value pairs只要扩展需要用户进行配置就可以通过 contributes.configuration 声明点 把设置项注册进 VS Code用户既可以在设置 UI 中可视化地修改也可以直接编辑settings.json。扩展代码内则通过设置 IDsetting ID查询这些配置值。这也正是 extension-capabilities/common-capabilities.md 所总结的扩展能力模式扩展先用contributes.configuration声明专属设置再用workspace.getConfigurationAPI 读取它们。必须做✔️ Do为每个设置项提供默认值default为每个设置项提供清晰简洁的描述description/markdownDescription对复杂的设置项通过文档链接引导用户进一步了解对相关的设置项互相建立链接帮助用户发现邻近配置当需要用户定位某个具体设置时直接链接到设置 ID例如#gitMagic.blame.dateFormat#形式的设置 ID 链接不要做❌ Dont不要自建设置页或 Webview来模拟设置界面——这会割裂用户对 VS Code 原生设置心智模型的依赖也失去搜索、校验、同步等内置能力不要写冗长的描述——长文本难以在设置项列表中阅读复杂背景应放到链接文档中上图所示示例即通过设置 ID 将界面上的配置项与具体设置链接起来。二、声明设置contributes.configuration 详解contributes.configuration是扩展清单package.json中注册设置的入口。用户随后即可在 Settings 编辑器或settings.json中修改这些选项。该声明既可以是一个**单一分类single category的配置对象也可以是多分类multiple categories**的对象数组——多分类时设置编辑器会在该扩展的目录table of contents中显示子菜单并用title字段作为子菜单名称。2.1 最小可运行示例参考 contribution-points.md 的 Configuration example一个典型的声明如下{ contributes: { configuration: { title: Settings Editor Test Extension, type: object, properties: { settingsEditorTestExtension.booleanExample: { type: boolean, default: true, description: Boolean Example }, settingsEditorTestExtension.stringExample: { type: string, default: Hello World, description: String Example } } } } }关键点title是该分类在设置 UI 中的标题properties是一个字典键是设置 ID值是描述该设置的元信息扩展代码侧可用vscode.workspace.getConfiguration(myExtension)读取这些值其中参数即设置 ID 的前缀段如上例的settingsEditorTestExtension。配置声明不仅决定设置 UI 的呈现方式还被用来为settings.json的 JSON 编辑提供 IntelliSense 提示——一份声明同时驱动两处体验。2.2 title分类标题的命名规范title是该分类的标题。对拥有多个分类的扩展若某分类的 title 与扩展显示名相同设置 UI 会将其视为默认分类忽略该分类的order字段并把它的设置直接放在扩展主标题之下。在title与displayName中ExtensionConfigurationSettings 等词是冗余的✔title: GitMagic❌title: GitMagic Extension❌title: GitMagic Configuration❌title: GitMagic Extension Configuration Settings2.3 properties设置 ID 与显示标题的生成规则properties中的每个键都是全局唯一的设置 ID。需要注意两条硬性约束一个扩展可以有多个设置分类但每个设置必须拥有唯一 ID一个设置 ID 不能是另一个设置 ID 的完整前缀否则会造成 ID 歧义。设置 UI 中每个设置的显示标题由多个字段拼接而成键名中的大写字母用于指示单词分界。具体规则分两种场景单分类 / 默认分类配置设置 UI 使用设置 ID 与扩展name字段共同推导显示标题。例如设置 IDgitMagic.blame.dateFormat与扩展名authorName.gitMagic因 ID 前缀与扩展名后缀匹配gitMagic部分会在显示标题中被移除最终显示为 Blame:Date Format。多分类配置当分类 title 与扩展显示名不同时设置 UI 使用设置 ID 与分类id字段推导。例如设置 IDcss.completion.completePropertyWithSemicolon与分类 IDcss前缀匹配后移除css得到标题 Completion:Complete Property With Semicolon。未显式给出order的属性在设置 UI 中按**字典序lexicographical order**排列而非按清单中书写的顺序。三、配置属性 schema从简单类型到完整约束配置键使用JSON Schema 的超集定义参见 contribution-points.md 的 Configuration property schema因此既可以使用标准校验属性也可以使用 VS Code 扩展的 UI 相关属性。3.1 基础类型number / string / booleannumber、string、boolean类型的设置可以直接在设置 UI 中编辑{ gitMagic.views.pageItemLimit: { type: number, default: 20, markdownDescription: Specifies the number of items to show in each page when paginating a view list. Use 0 to specify no limit }, gitMagic.blame.compact: { type: boolean, description: Specifies whether to compact (deduplicate) matching adjacent gutter blame annotations } }补充细节字符串设置可通过editPresentation: multilineText渲染为多行文本输入框布尔设置的markdownDescription未指定时回退到description会作为复选框旁边的标签文案使用。3.2 description / markdownDescriptiondescription出现在标题之后、输入控件之前对布尔项则作为复选框标签。若改用markdownDescription描述内容会在设置 UI 中以 Markdown 解析渲染{ gitMagic.blame.heatMap.enabled: { description: Specifies whether to provide a heatmap indicator in the gutter blame annotations }, gitMagic.blame.dateFormat: { markdownDescription: Specifies how to format absolute dates (e.g. using the ${date} token) in gutter blame annotations. See the [Moment.js docs](https://momentjs.com/docs/#/displaying/format/) for valid formats } }使用markdownDescription时若要换行或分段应使用\n\n分隔段落而不是单独使用\n。3.3 下拉菜单enum 及其描述提供enum属性值为数组时设置 UI 会渲染为下拉菜单。与之配套的属性包括enumDescriptions与enum等长的字符串数组在下拉菜单底部显示每项对应的说明markdownEnumDescriptions同enumDescriptions但按 Markdown 解析优先级高于enumDescriptionsenumItemLabels自定义下拉菜单中选项的显示名称。{ settingsEditorTestExtension.enumSetting: { type: string, enum: [first, second, third], markdownEnumDescriptions: [The *first* enum, The *second* enum, The *third* enum], enumItemLabels: [1st, 2nd, 3rd], default: first, description: Example setting with an enum } }3.4 弃用标记deprecationMessage / markdownDeprecationMessage设置deprecationMessage或markdownDeprecationMessage后设置项会获得带提示文字的下划线警告并且除非用户已显式配置否则该设置会从设置 UI 中隐藏。两条属性的渲染分工如下deprecationMessage显示在设置悬停hover与问题面板problems view中markdownDeprecationMessage在设置 UI 中以 Markdown 渲染但不会出现在设置悬停或问题面板中。{ json.colorDecorators.enable: { type: boolean, description: Enables or disables color decorators, markdownDeprecationMessage: **Deprecated**: Please use #editor.colorDecorators# instead., deprecationMessage: Deprecated: Please use editor.colorDecorators instead. } }3.5 校验与约束标准 JSON Schema 属性以下标准校验属性均可用于约束配置值详见 contribution-points.md 的 Other JSON Schema properties属性作用default定义设置项的默认值minimum/maximum限制数值范围maxLength/minLength限制字符串长度pattern用正则表达式约束字符串patternErrorMessagepattern 不匹配时的定制错误信息format限制为已知格式如date、time、ipv4、email、urimaxItems/minItems限制数组长度editPresentation控制字符串设置是渲染为单行输入框还是多行文本域不支持的 JSON Schema 属性$ref与definition不可用于配置节——配置 schema 必须自包含不能假设聚合后的全局 settings JSON schema 文档的结构。3.6 复杂类型object / array 的可编辑性部分object与array类型设置可以在设置 UI 中直接编辑简单数组元素为number、string或boolean渲染为可编辑列表简单对象属性均为string、number、integer和/或boolean渲染为键值可编辑网格此类对象设置还应设置additionalProperties为false或一个带合适type属性的对象才能在 UI 中正确渲染。如果object或array设置还可能包含嵌套对象、数组或null等类型则无法在设置 UI 中渲染只能通过直接编辑 JSON 修改——此时用户会看到Edit in settings.json链接入口。3.7 order分类与设置的排序控制分类和分类内的设置都可以用整数order控制相对排序有order的分类按数值升序排列在前未指定的分类排在其后分类内同理带order的设置先按数值升序排列未指定的设置排在其后若两个分类或两个设置的order值相同则按字典序升序排列。四、scope设置的作用域与生效层级scope决定设置项在哪些层级可用、是否适用详见 contribution-points.md 的 scope 小节。可选值如下scope含义application应用于 VS Code 所有实例只能在用户设置中配置machine机器特定设置只能在用户设置或远程设置中配置如不应跨机器共享的安装路径值不会同步machine-overridable机器特定设置但可被工作区或文件夹设置覆盖值不会同步window窗口实例特定设置可在用户、工作区或远程设置中配置resource资源级设置作用于文件和文件夹可在包括文件夹设置在内的所有层级配置language-overridable可在语言级别覆盖的资源设置若未声明scope默认值为window。内置 Git 扩展给出了三种 scope 的典型组合参见 contribution-points.md 的示例{ contributes: { configuration: { title: Git, properties: { git.alwaysSignOff: { type: boolean, scope: resource, default: false, description: %config.alwaysSignOff% }, git.ignoredRepositories: { type: array, default: [], scope: window, description: %config.ignoredRepositories% }, git.autofetch: { type: [boolean, string], enum: [true, false, all], scope: resource, markdownDescription: %config.autofetch%, default: false, tags: [usesOnlineServices] } } } } }可以看到git.alwaysSignOff声明为resourcescope可按用户、工作区或文件夹分别设置而git.ignoredRepositories为windowscope对 VS Code 窗口/工作区可能是多根工作区整体生效。git.autofetch还演示了联合类型[boolean, string]配合enum的使用方式。ignoreSync排除设置同步设置ignoreSync: true可阻止该设置随用户设置同步适用于非用户特定user-specific的设置。例如remoteTunnelAccess.machineName这类不应同步的设置见 contribution-points.md 的 ignoreSync 小节{ contributes: { configuration: { properties: { remoteTunnelAccess.machineName: { type: string, default: , ignoreSync: true } } } } }注意若scope已设置为machine或machine-overridable则无论ignoreSync取值如何该设置都不会被同步。五、configurationDefaults覆盖其他配置的默认值contributes.configurationDefaults允许扩展为其他已注册配置贡献默认值并覆盖其原有默认值详见 contribution-points.md 的 configurationDefaults。例如把files.autoSave的默认行为改为焦点变化时自动保存configurationDefaults: { files.autoSave: onFocusChange }还可以按语言贡献默认的编辑器配置。下面这段为markdown语言开启自动换行、并关闭注释/字符串/其他位置的快速建议{ contributes: { configurationDefaults: { [markdown]: { editor.wordWrap: on, editor.quickSuggestions: { comments: off, strings: off, other: off } } } } }六、在扩展代码中读取设置设置声明之后扩展运行时代码通过vscode.workspace.getConfiguration读取。getConfiguration接受一个可选段section参数通常是设置 ID 的命名空间前缀import * as vscode from vscode; // 读取前缀为 gitMagic. 的配置段 const config vscode.workspace.getConfiguration(gitMagic); // 读取具体设置可传入默认值兜底 const pageItemLimit config.getnumber(views.pageItemLimit, 20); const compact config.getboolean(blame.compact, false);配合onDidChangeConfiguration事件还可以在用户修改设置后实时响应。这也是 common-capabilities.md 中描述的标准扩展能力链路声明manifest→ 读取API→ 响应变化事件。七、核心实践清单把上述规则汇总成一份可直接对照的设计清单声明优先所有设置统一通过contributes.configuration声明绝不另起炉灶自建设置页或 Webview默认值必备每个设置给出合理的default避免空值导致的运行时异常描述精炼用一句以内的话说清作用复杂逻辑放进markdownDescription的链接文档布尔项描述即复选框标签务必言简意赅善用类型控件单选用enumenumItemLabels多行输入用editPresentation: multilineText列表/键值对尽量保持简单结构以获得 UI 内编辑能力显式声明 scope按实际生效层级选择resource/window/machine等不依赖默认值window掩盖设计意图控制排序用order明确分类与设置的展示顺序同名优先级下依赖字典序兜底及时弃用旧设置用deprecationMessage/markdownDeprecationMessage引导迁移并在设置 UI 中自动隐藏同步策略清晰机器相关或不含用户偏好的设置用machinescope 或ignoreSync: true排除同步链接引导复杂设置与相关设置之间互相提供设置 ID 链接#namespace.settingName#格式帮助用户在设置界面间快速跳转ID 纪律设置 ID 全局唯一、命名空间化publisher.extensionName.settingName风格且不得互为完整前缀。遵循以上实践你的扩展设置将获得与 VS Code 原生设置一致的可搜索、可校验、可同步、可被 JSON 编辑与 IntelliSense 提示的完整体验这也是官方 UX 指南中 Settings 章节的核心诉求。延伸阅读contributes.configuration 与 configurationDefaults 完整参考扩展能力总览设置声明与读取 APIUX Guidelines 总览理解容器Containers与条目Items体系赞分享文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载相关推荐Self-hosted LiveSync 声明式设置适配基于 Obsidian 1.13 设置 API 的架构决策与实践Self hosted LiveSync 声明式设置适配基于 Obsidian 1.13 设置 API 的架构决策与实践 导读 本文解读 Self hoste数据同步NetAlertX 设置系统开发指南从 config.json 到 Settings UI 的声明式配置最佳实践NetAlertX 设置系统开发指南从 config.json 到 Settings UI 的声明式配置最佳实践 导读 本指南面向需要在 NetAlertX后端网络运维数据可视化Visual Studio Code 扩展 UX 指南工作台容器、界面元素与设计最佳实践Visual Studio Code 扩展 UX 指南工作台容器、界面元素与设计最佳实践 本文基于 VS Code 官方文档仓库的 UX Guidelines文档教程上一篇5步玩转Open3D从零开始掌握3D数据处理神器 下一篇Admin.NET企业级权限框架实战部署全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考