使用 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 文档。
折叠
您可以使用行号和行首之间空白区域(gutter)上的折叠图标来折叠源代码区域。所有对象和数组元素都支持折叠区域。
带注释的 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
键会改变 JSON 本身,这可能不符合使用 JSON 的系统的预期,例如,架构验证可能会失败。如果出现这种情况,您可以使用其他映射方法之一。
在用户设置中进行映射
以下用户设置摘录显示了 .babelrc
文件如何映射到位于 https://json.schemastore.org/babelrc 的 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": "Keyboard shortcuts configuration",
"items": {
"type": "object",
"required": ["key"],
"defaultSnippets": [
{
"label": "New keyboard shortcut",
"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
将显示在补全选择对话框中。如果没有提供label
,则会显示代码片段的字符串化对象表示作为label
。body
是一个 JSON 对象,当用户选择补全时,它会被字符串化并插入。在字符串字面量中可以使用 代码片段语法来定义制表位、占位符和变量。如果字符串以^
开头,则字符串内容将按原样插入,不会被字符串化。您可以使用此方法为数字和布尔值指定代码片段。
请注意,defaultSnippets
不属于 JSON 架构规范,而是 VS Code 特有的架构扩展。
在悬停提示中使用富文本格式
VS Code 将使用 JSON 架构规范中的标准 description
字段,以便在悬停和自动完成时提供有关属性的信息。
如果您希望您的描述支持链接等格式,您可以通过在格式中使用 markdownDescription
属性并使用 Markdown 来选择启用此功能。
{
"$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 架构。
当当前编辑器想要使用无法下载的架构时,状态栏中将显示一个警告三角形。