尝试以扩展 VS Code 中的代理模式!

使用 Visual Studio Code 编辑 JSON

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

JSON within VS Code

智能感知和验证

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

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

IntelliSense

包和项目依赖

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

快速导航

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

Goto Symbol

悬停信息

当您将鼠标悬停在带或不带 schema 的 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 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.jsonbower.jsontsconfig.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/babelrcbabelrc 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 贡献点

文件匹配语法

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

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

Default snippets in JSON schema

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

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

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