使用 Visual Studio Code 编辑 JSON
JSON 是一种数据格式,在配置文件(如 package.json
或 project.json
)中很常见。我们还在 Visual Studio Code 中广泛使用它来配置我们的配置文件。打开以 .json
结尾的文件时,VS Code 提供了一些功能,使编写或修改文件内容更加简单。
IntelliSense 和验证
对于属性和值,无论 JSON 数据是否有模式,我们都会在您输入时提供 IntelliSense 的建议。您也可以使用 **触发建议** 命令 (⌃Space(Windows、Linux Ctrl+Space))手动查看建议。
我们还会根据关联的 JSON 模式执行结构和值验证,为您提供红色波浪线。要禁用验证,请使用 json.validate.enable 设置。
包和项目依赖项
我们还为 package.json
、project.json
和 bower.json
中的包和项目依赖项等特定值集提供 IntelliSense。
快速导航
JSON 文件可能会很大,我们支持使用 **转到符号** 命令 (⇧⌘O(Windows、Linux Ctrl+Shift+O))快速导航到属性。
悬停
当您将鼠标悬停在带有或不带有模式的 JSON 数据的属性和值上时,我们将提供更多上下文。
格式化
您可以使用 ⇧⌥F(Windows Shift+Alt+F,Linux Ctrl+Shift+I))或从上下文菜单中选择 **格式化文档** 来格式化 JSON 文档。
折叠
您可以使用行号和行首之间边距上的折叠图标来折叠源代码区域。折叠区域适用于所有对象和数组元素。
包含注释的 JSON
除了遵循 JSON 规范 的默认 JSON 模式之外,VS Code 还具有 **包含注释的 JSON** (jsonc) 模式。此模式用于 VS Code 配置文件,例如 settings.json
、tasks.json
或 launch.json
。处于 **包含注释的 JSON** 模式时,您可以使用单行 (//
) 以及 JavaScript 中使用的块注释 (/* */
)。该模式还接受尾随逗号,但它们不鼓励使用,编辑器会显示警告。
当前编辑器模式在编辑器状态栏中显示。选择模式指示器以更改模式,并配置文件扩展名与模式的关联方式。您也可以直接修改 files.associations 设置,将文件名或文件名模式与 jsonc
关联。
JSON 模式和设置
为了了解 JSON 文件的结构,我们使用 JSON 模式。JSON 模式描述了 JSON 文件的形状,以及值集、默认值和描述。VS Code 附带的 JSON 支持支持从草案 4 到草案 7 的所有草案版本,对草案 2019-09 和 2020-12 的支持有限。
像 JSON Schema Store 这样的服务器为大多数常见的基于 JSON 的配置文件提供模式。但是,模式也可以在 VS Code 工作区中的文件中定义,以及在 VS Code 设置文件中定义。
将 JSON 文件与模式关联可以通过两种方式完成:使用 JSON 文件本身中的 $schema
属性,或在用户或工作区 设置(**文件** > **首选项** > **设置**)中使用属性 json.schemas。
VS Code 扩展也可以定义模式和模式映射。这就是为什么 VS Code 已经了解了一些知名 JSON 文件(如 package.json
、bower.json
和 tsconfig.json
)的模式。
在 JSON 中映射
在以下示例中,JSON 文件指定其内容遵循 CoffeeLint 模式。
{
"$schema": "https://json.schemastore.org/coffeelint",
"line_endings": "unix"
}
请注意,此语法是 VS Code 特定的,不是 JSON Schema 规范 的一部分。添加 $schema
键会更改 JSON 本身,使用 JSON 的系统可能不希望这样做,例如模式验证可能会失败。如果是这种情况,您可以使用其他映射方法之一。
在用户设置中映射
以下摘录来自用户 设置,显示了如何将 .babelrc
文件映射到位于 babelrc 的 https://json.schemastore.org/babelrc 上的模式。
"json.schemas": [
{
"fileMatch": [
"/.babelrc"
],
"url": "https://json.schemastore.org/babelrc"
}
]
提示:除了为
.babelrc
定义模式外,还要确保.babelrc
与 JSON 语言模式关联。这也在设置中通过files.association
数组设置完成。
映射到工作区中的模式
要映射位于工作区中的模式,请使用相对路径。在此示例中,工作区根目录中名为 myschema.json
的文件将用作所有以 .foo.json
结尾的文件的模式。
"json.schemas": [
{
"fileMatch": [
"**/*.foo.json"
],
"url": "./myschema.json"
}
]
映射到设置中定义的模式
要映射在用户或工作区设置中定义的模式,请使用 schema
属性。在此示例中,定义了一个模式,该模式将用于所有名为 .myconfig
的文件。
"json.schemas": [
{
"fileMatch": [
"/.myconfig"
],
"schema": {
"type": "object",
"properties": {
"name" : {
"type": "string",
"description": "The name of the entry"
}
}
}
}
]
在扩展中映射模式
模式和模式关联也可以由扩展定义。查看 jsonValidation 贡献点。
文件匹配语法
文件匹配语法支持“*”通配符。此外,您可以定义排除模式,以“!”开头。为了使关联匹配,至少需要一个模式匹配,并且最后一个匹配模式不能是排除模式。
"json.schemas": [
{
"fileMatch": [
"/receipts/*.json",
"!/receipts/*.excluded.json"
],
"url": "./receipts.schema.json"
}
]
在 JSON 模式中定义代码片段
JSON 模式描述了 JSON 文件的结构,以及值集和默认值,这些内容由 JSON 语言支持用来提供补全建议。如果您是模式作者,想要提供更多定制化的补全建议,您也可以在模式中指定代码片段。
以下示例展示了一个用于键绑定设置文件的模式,其中定义了一个代码片段。
{
"type": "array",
"title": "Keybindings configuration",
"items": {
"type": "object",
"required": ["key"],
"defaultSnippets": [
{
"label": "New keybinding",
"description": "Binds a key to a command for a given state",
"body": { "key": "$1", "command": "$2", "when": "$3" }
}
],
"properties": {
"key": {
"type": "string"
}
...
}
}
}
这是一个 JSON 模式中的示例。
使用属性 `defaultSnippets` 来指定给定 JSON 对象的任意数量的代码片段。
- `label` 和 `description` 将显示在补全选择对话框中。如果没有提供标签,则将显示代码片段的字符串化对象表示形式作为标签。
- `body` 是在用户选择补全时被字符串化并插入的 JSON 对象。可以在字符串字面量中使用 代码片段语法 来定义制表位、占位符和变量。如果字符串以 `^` 开头,则字符串内容将按原样插入,不会被字符串化。您可以使用此功能来指定数字和布尔值的代码片段。
请注意,`defaultSnippets` 不是 JSON 模式规范的一部分,而是 VS Code 特定的模式扩展。
在悬停中使用富文本格式
VS Code 将使用来自 JSON 模式规范 的标准 `description` 字段,以便在悬停和自动完成期间提供有关属性的信息。
如果您希望描述支持链接等格式化内容,可以使用 Markdown 在您的格式化中使用 `markdownDescription` 属性。
{
"$schema": "https://json-schema.fullstack.org.cn/draft-07/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the entry",
"markdownDescription": "The name of the entry. [See the documentation](https://example.com)"
}
}
}
请注意,`markdownDescription` 不是 JSON 模式规范的一部分,而是 VS Code 特定的模式扩展。
离线模式
json.schemaDownload.enable 控制 JSON 扩展是否从 `http` 和 `https` 提取 JSON 模式。
当当前编辑器想要使用无法下载的模式时,状态栏中会显示一个警告三角形。