使用 Visual Studio Code 编辑 JSON

JSON 是一种数据格式，常见于 package.json 或 project.json 等配置文件中。我们在 Visual Studio Code 的配置文件中也广泛使用它。当打开以 .json 结尾的文件时，VS Code 提供了多种功能，使编写或修改文件内容变得更加简单。

智能感知与验证

对于属性和值，无论 JSON 数据是否带有 schema，我们都会在你输入时通过智能感知（IntelliSense）提供建议。你也可以使用 触发建议 命令（⌃Space (Windows, Linux Ctrl+Space)）手动查看建议。

我们还会根据关联的 JSON schema 执行结构和值的验证，并为你显示红色波浪线。要禁用验证，请使用 json.validate.enable 设置。

包和项目依赖

我们还为 package.json、project.json 和 bower.json 文件中的特定值集（例如包和项目依赖项）提供智能感知。

快速导航

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

悬停信息

当你将鼠标悬停在 JSON 数据的属性和值上时（无论有无 schema），我们都会提供额外的上下文信息。

格式化

你可以使用 ⇧⌥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 schema 和设置

为了理解 JSON 文件的结构，我们使用 JSON schema。JSON schema 描述了 JSON 文件的结构，以及值集、默认值和描述。VS Code 自带的 JSON 支持从 draft 4 到 draft 7 的所有草案版本，并对 draft 2019-09 和 2020-12 提供有限支持。

像 JSON Schema Store 这样的服务器为大多数常见的基于 JSON 的配置文件提供了 schema。但是，schema 也可以在 VS Code 工作区的文件中以及 VS Code 设置文件中定义。

将 JSON 文件与 schema 关联，既可以在 JSON 文件本身中使用 $schema 属性完成，也可以在用户或工作区设置（文件 > 首选项 > 设置）中的 json.schemas 属性下完成。

VS Code 扩展也可以定义 schema 和 schema 映射。这就是为什么 VS Code 已经知道一些知名 JSON 文件（如 package.json、bower.json 和 tsconfig.json）的 schema 的原因。

在 JSON 文件中映射

在以下示例中，JSON 文件指定其内容遵循 CoffeeLint schema。

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

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

在用户设置中映射

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

"json.schemas": [
    {
        "fileMatch": [
            "/.babelrc"
        ],
        "url": "https://json.schemastore.org/babelrc"
    }
]

提示：除了为 .babelrc 定义 schema 外，还要确保 .babelrc 与 JSON 语言模式相关联。这同样可以在设置中使用 files.association 数组设置来完成。

映射到工作区中的 schema

要映射位于工作区中的 schema，请使用相对路径。在此示例中，工作区根目录中名为 myschema.json 的文件将用作所有以 .foo.json 结尾的文件的 schema。

"json.schemas": [
    {
        "fileMatch": [
            "**/*.foo.json"
        ],
        "url": "./myschema.json"
    }
]

映射到设置中定义的 schema

要映射在用户或工作区设置中定义的 schema，请使用 schema 属性。在此示例中，定义了一个 schema，它将用于所有名为 .myconfig 的文件。

"json.schemas": [
    {
        "fileMatch": [
            "/.myconfig"
        ],
        "schema": {
            "type": "object",
            "properties": {
                "name" : {
                    "type": "string",
                    "description": "The name of the entry"
                }
            }
        }
    }
]

在扩展中映射 schema

Schema 和 schema 关联也可以由扩展定义。请查看 jsonValidation contribution point。

文件匹配语法

文件匹配语法支持 '*' 通配符。此外，你还可以定义以 '!' 开头的排除模式。要使关联匹配，至少需要有一个模式匹配，并且最后一个匹配的模式不能是排除模式。

  "json.schemas": [
    {
      "fileMatch": [
        "/receipts/*.json",
        "!/receipts/*.excluded.json"
      ],
      "url": "./receipts.schema.json"
    }
  ]

在 JSON schema 中定义代码片段

JSON schema 描述了 JSON 文件的结构，以及值集和默认值，JSON 语言支持使用这些信息来提供补全建议。如果你是 schema 的作者，并且想要提供更定制化的补全建议，你还可以在 schema 中指定代码片段。

以下示例展示了一个用于键盘快捷键设置文件的 schema，其中定义了一个代码片段。

{
    "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 schema 中的一个示例

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

• label 和 description 将显示在补全选择对话框中。如果未提供标签，则会显示代码片段的字符串化对象表示作为标签。
• body 是一个 JSON 对象，当用户选择补全时，它会被字符串化并插入。代码片段语法可用于字符串字面量内，以定义制表位、占位符和变量。如果字符串以 ^ 开头，则字符串内容将按原样插入，而不会被字符串化。你可以使用它来为数字和布尔值指定代码片段。

请注意，defaultSnippets 不属于 JSON schema 规范的一部分，而是 VS Code 特有的 schema 扩展。

在悬停提示中使用富文本格式

VS Code 将使用 JSON Schema 规范 中的标准 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 schema 规范的一部分，而是 VS Code 特有的 schema 扩展。

离线模式

json.schemaDownload.enable 控制 JSON 扩展是否从 http 和 https 获取 JSON schema。

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