使用 Visual Studio Code 編輯 JSON

JSON 是一種常見於設定檔（例如 package.json 或 project.json）的資料格式。我們也在 Visual Studio Code 的設定檔中廣泛使用它。當開啟以 .json 結尾的檔案時，VS Code 會提供相關功能，讓編寫或修改檔案內容變得更加簡單。

IntelliSense 與驗證

對於屬性和值，無論 JSON 資料是否有對應的架構（schema），我們都會在您輸入時透過 IntelliSense 提供建議。您也可以使用觸發建議命令手動查看建議 (⌃Space (Windows, Linux Ctrl+Space))。

我們也會根據關聯的 JSON 架構進行結構與值驗證，並透過紅色的波浪底線提醒您。若要停用驗證，請使用 json.validate.enable 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定。

套件與專案相依性

我們也針對特定的數值集（例如 package.json、project.json 和 bower.json 中的套件與專案相依性）提供 IntelliSense。

快速導覽

JSON 檔案可能會變得很大，我們支援使用前往符號命令來快速導覽至各屬性 (⇧⌘O (Windows, Linux Ctrl+Shift+O))。

懸停提示（Hovers）

當您將滑鼠懸停在 JSON 資料的屬性和值上（無論是否有架構）時，我們將提供額外的背景資訊。

格式化

您可以使用 ⇧⌥F (Windows Shift+Alt+F, Linux Ctrl+Shift+I) 或從內容選單中選擇格式化文件來格式化您的 JSON 文件。

程式碼摺疊

您可以使用行號與起始行之間的裝訂邊（gutter）上的摺疊圖示來摺疊原始程式碼區域。所有物件和陣列元素皆可進行區域摺疊。

帶有註解的 JSON

除了遵循 JSON 規範的預設 JSON 模式外，VS Code 還有帶有註解的 JSON (jsonc) 模式。此模式用於 VS Code 設定檔，例如 settings.json、tasks.json 或 launch.json。在帶有註解的 JSON 模式中，您可以使用 JavaScript 中常見的單行註解 (//) 以及區塊註解 (/* */)。該模式也接受尾隨逗號（trailing commas），但不建議使用，編輯器會顯示警告。

目前的編輯器模式會顯示在編輯器的狀態列中。選取模式指示器以變更模式，並設定副檔名與模式的關聯方式。您也可以直接修改 files.associations 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定，將檔案名稱或檔案名稱模式與 jsonc 關聯起來。

JSON 架構與設定

為了理解 JSON 檔案的結構，我們使用 JSON schemas（JSON 架構）。JSON 架構描述了 JSON 檔案的形狀，以及數值集、預設值和描述。VS Code 內建的 JSON 支援功能支援從 draft 4 到 draft 7 的所有草案版本，並對 draft 2019-09 和 2020-12 提供有限支援。

像 JSON Schema Store 這樣的伺服器為大多數常見的 JSON 設定檔提供了架構。不過，架構也可以定義在 VS Code 工作區中的檔案內，以及 VS Code 設定檔中。

將 JSON 檔案與架構關聯，可以透過 JSON 檔案本身的 $schema 屬性完成，或者在使用者或工作區 設定（檔案 > 喜好設定 > 設定）中的 json.schemas 在 VS Code 中開啟 在 VS Code Insiders 中開啟 屬性下設定。

VS Code 擴充功能也可以定義架構與架構對應。這就是為什麼 VS Code 已經能夠辨識某些知名 JSON 檔案（例如 package.json、bower.json 和 tsconfig.json）的架構。

在 JSON 中進行對應

在下列範例中，JSON 檔案指定其內容遵循 CoffeeLint 架構。

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

請注意，此語法是 VS Code 特有的，並非 JSON 架構規範的一部分。新增 $schema 金鑰會變更 JSON 本身，這可能是消費該 JSON 的系統所未預期的，例如導致架構驗證失敗。如果是這種情況，您可以使用其他對應方法之一。

在使用者設定中進行對應

以下取自使用者 設定 的片段顯示了 .babelrc 檔案如何對應至位於 https://json.schemastore.org/babelrc 的 babelrc 架構。

"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 架構中定義程式碼片段 (snippets)

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 架構中的範例

使用 defaultSnippets 屬性為給定的 JSON 物件指定任意數量的程式碼片段。

• label 和 description 將顯示在完成選取對話方塊中。如果未提供標籤，則會改為顯示該程式碼片段的字串化物件表示形式作為標籤。
• body 是當使用者選取完成建議時會進行字串化並插入的 JSON 物件。程式碼片段語法可以用於字串常值中，以定義 Tab 鍵停駐點、預留位置和變數。如果字串以 ^ 開頭，該字串內容將原樣插入，而非進行字串化。您可以使用此功能為數字和布林值指定程式碼片段。

請注意，defaultSnippets 並非 JSON 架構規範的一部分，而是 VS Code 特有的架構延伸。

在懸浮視窗中使用豐富格式

VS Code 將使用 JSON 架構規範中的標準 description 欄位，以便在滑鼠懸停和自動完成期間提供有關屬性的資訊。

如果您希望描述支援連結等格式，可以使用 markdownDescription 屬性，並在您的格式中使用 Markdown。

{
  "$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 架構規範的一部分，而是 VS Code 特有的架構延伸。

離線模式

json.schemaDownload.enable 在 VS Code 中開啟 在 VS Code Insiders 中開啟 控制 JSON 擴充功能是否從 http 和 https 擷取 JSON 架構。

當目前的編輯器嘗試使用無法下載的架構時，狀態列中會顯示一個警告三角形。