使用 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": "http://json-schema.org/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 時，狀態列中會顯示一個警告三角形。