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

使用 Visual Studio Code 编辑 JSON

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

JSON within VS Code

IntelliSense 和验证

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

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

IntelliSense

包和项目依赖项

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

快速导航

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

Goto Symbol

悬停信息

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

Hover

格式化

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

折叠

您可以使用行号和行首之间空白区域(gutter)上的折叠图标来折叠源代码区域。所有对象和数组元素都支持折叠区域。

带注释的 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 将显示在补全选择对话框中。如果没有提供 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 扩展是否从 httphttps 获取 JSON 架构。

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