在 VS Code 中试用

使用 Visual Studio Code 编辑 JSON

JSON 是一种常见的数据格式,广泛用于 package.jsonproject.json 等配置文件中。我们也在 Visual Studio Code 中大量使用它作为我们的配置文件。当打开以 .json 结尾的文件时,VS Code 提供了简化文件内容编写或修改的功能。

JSON within VS Code

智能感知和验证

无论是带有还是不带架构的 JSON 数据,我们都会在您键入时使用智能感知提供属性和值的建议。您还可以使用**触发建议**命令(⌃Space (Windows, Linux Ctrl+Space))手动查看建议。

我们还会根据关联的 JSON 架构执行结构和值验证,为您提供红色波浪线。要禁用验证,请使用 json.validate.enable 设置

IntelliSense

包和项目依赖

我们还为特定的值集提供智能感知,例如 package.jsonproject.jsonbower.json 中的包和项目依赖项。

快速导航

JSON 文件可能会很大,我们支持使用**转到符号**命令(⇧⌘O (Windows, Linux Ctrl+Shift+O))快速导航到属性。

Goto Symbol

悬停

当您将鼠标悬停在带有或不带架构的 JSON 数据的属性和值上时,我们将提供额外的上下文信息。

Hover

格式化

您可以使用 ⇧⌥F (Windows Shift+Alt+F, Linux Ctrl+Shift+I) 或上下文菜单中的**格式化文档**来格式化您的 JSON 文档。

折叠

您可以使用行号和行起始之间的行间折叠图标来折叠源代码区域。所有对象和数组元素都可进行折叠。

带注释的 JSON

除了遵循 JSON 规范的默认 JSON 模式外,VS Code 还具有**带注释的 JSON** (jsonc) 模式。此模式用于 VS Code 配置文件,例如 settings.jsontasks.jsonlaunch.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.jsonbower.jsontsconfig.json

JSON 中的映射

在以下示例中,JSON 文件指定其内容遵循 CoffeeLint 架构。

{
  "$schema": "https://json.schemastore.org/coffeelint",
  "line_endings": "unix"
}

请注意,此语法是 VS Code 特有的,并非 JSON 架构规范的一部分。添加 $schema 键会改变 JSON 本身,这可能是使用该 JSON 的系统不期望的,例如,架构验证可能会失败。如果是这种情况,您可以使用其他映射方法之一。

用户设置中的映射

以下用户设置摘录显示了 .babelrc 文件如何映射到位于 https://json.schemastore.org/babelrcbabelrc 架构。

"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 架构中的一个示例

Default snippets in JSON schema

使用 defaultSnippets 属性为给定的 JSON 对象指定任意数量的代码片段。

  • labeldescription 将显示在完成选择对话框中。如果未提供标签,则会显示代码片段的字符串化对象表示作为标签。
  • 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 扩展是否从 httphttps 获取 JSON 架构。

当当前编辑器想要使用无法下载的架构时,状态栏中将显示一个警告三角形。