企业官网建设流程全解析

• 文档
• 教程

导读

本指南以 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。扩展代码内则通过设置 ID（setting ID）查询这些配置值。这也正是 extension-capabilities/common-capabilities.md 所总结的扩展能力模式：扩展先用contributes.configuration声明专属设置，再用workspace.getConfigurationAPI 读取它们。

必须做（✔️ Do）

• 为每个设置项提供默认值（default）
• 为每个设置项提供清晰简洁的描述（description/markdownDescription）
• 对复杂的设置项，通过文档链接引导用户进一步了解
• 对相关的设置项，互相建立链接，帮助用户发现邻近配置
• 当需要用户定位某个具体设置时，直接链接到设置 ID（例如#gitMagic.blame.dateFormat#形式的设置 ID 链接）

不要做（❌ Don't）

• 不要自建设置页或 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中，"Extension""Configuration""Settings" 等词是冗余的：

• ✔"title": "GitMagic"
• ❌"title": "GitMagic Extension"
• ❌"title": "GitMagic Configuration"
• ❌"title": "GitMagic Extension Configuration Settings"

2.3 properties：设置 ID 与显示标题的生成规则

properties中的每个键都是全局唯一的设置 ID。需要注意两条硬性约束：

1. 一个扩展可以有多个设置分类，但每个设置必须拥有唯一 ID；
2. 一个设置 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 / boolean

number、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 / markdownDescription

description出现在标题之后、输入控件之前；对布尔项则作为复选框标签。若改用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 解析，优先级高于enumDescriptions；
• enumItemLabels：自定义下拉菜单中选项的显示名称。

{ "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）：

不支持的 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，默认值为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.get<number>('views.pageItemLimit', 20); const compact = config.get<boolean>('blame.compact', false);

配合onDidChangeConfiguration事件，还可以在用户修改设置后实时响应。这也是 common-capabilities.md 中描述的标准扩展能力链路：声明（manifest）→ 读取（API）→ 响应变化（事件）。

七、核心实践清单

把上述规则汇总成一份可直接对照的设计清单：

1. 声明优先：所有设置统一通过contributes.configuration声明，绝不另起炉灶自建设置页或 Webview；
2. 默认值必备：每个设置给出合理的default，避免空值导致的运行时异常；
3. 描述精炼：用一句以内的话说清作用，复杂逻辑放进markdownDescription的链接文档；布尔项描述即复选框标签，务必言简意赅；
4. 善用类型控件：单选用enum+enumItemLabels，多行输入用editPresentation: "multilineText"，列表/键值对尽量保持简单结构以获得 UI 内编辑能力；
5. 显式声明 scope：按实际生效层级选择resource/window/machine等，不依赖默认值window掩盖设计意图；
6. 控制排序：用order明确分类与设置的展示顺序，同名优先级下依赖字典序兜底；
7. 及时弃用：旧设置用deprecationMessage/markdownDeprecationMessage引导迁移，并在设置 UI 中自动隐藏；
8. 同步策略清晰：机器相关或不含用户偏好的设置用machinescope 或ignoreSync: true排除同步；
9. 链接引导：复杂设置与相关设置之间互相提供设置 ID 链接（#namespace.settingName#格式），帮助用户在设置界面间快速跳转；
10. ID 纪律：设置 ID 全局唯一、命名空间化（publisher.extensionName.settingName风格），且不得互为完整前缀。

遵循以上实践，你的扩展设置将获得与 VS Code 原生设置一致的可搜索、可校验、可同步、可被 JSON 编辑与 IntelliSense 提示的完整体验，这也是官方 UX 指南中 Settings 章节的核心诉求。

延伸阅读

• contributes.configuration 与 configurationDefaults 完整参考
• 扩展能力总览：设置声明与读取 API
• UX Guidelines 总览：理解容器（Containers）与条目（Items）体系

• 文档
• 教程