使用 Visual Studio Code 編輯 JSON

JSON 是一種資料格式，在組態檔中很常見，例如 package.json 或 project.json。我們也在 Visual Studio Code 中大量使用它於我們的組態檔。當開啟以 .json 結尾的檔案時，VS Code 提供多項功能，讓撰寫或修改檔案內容更簡單。

IntelliSense 和驗證

對於屬性和值，無論是具有或不具有結構描述的 JSON 資料，我們都會在您輸入時提供 IntelliSense 的建議。您也可以使用「觸發建議」命令 (⌃Space (Windows、Linux Ctrl+Space)) 手動查看建議。

我們也會根據關聯的 JSON 結構描述執行結構和值驗證，並以紅色波浪線標示錯誤。若要停用驗證，請使用 json.validate.enable 設定。

套件和專案相依性

我們也為特定值集提供 IntelliSense，例如 package.json、project.json 和 bower.json 中的套件和專案相依性。

快速導覽

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

Hover 提示

當您將滑鼠游標停留在具有或不具有結構描述的 JSON 資料的屬性和值上時，我們會提供額外的內容資訊。

格式化

您可以使用 ⇧⌥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 結構描述與設定

為了理解 JSON 檔案的結構，我們使用 JSON 結構描述。JSON 結構描述描述 JSON 檔案的形狀，以及值集、預設值和描述。VS Code 隨附的 JSON 支援支援從 draft 4 到 draft 7 的所有草稿版本，並有限度地支援 drafts 2019-09 和 2020-12。

諸如 JSON Schema Store 等伺服器為大多數常見的 JSON 型組態檔提供結構描述。但是，結構描述也可以在 VS Code 工作區中的檔案以及 VS Code 設定檔中定義。

JSON 檔案與結構描述的關聯可以在 JSON 檔案本身中使用 $schema 屬性完成，也可以在使用者或工作區的 設定 (檔案 > 喜好設定 > 設定) 中的 json.schemas 屬性下完成。

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 結構描述中定義程式碼片段

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 物件，當使用者選取完成時，會將其字串化並插入。程式碼片段語法可用於字串常值內，以定義跳格停駐點、預留位置和變數。如果字串以 ^ 開頭，則字串內容將按原樣插入，而不是字串化。您可以使用此功能為數字和布林值指定程式碼片段。

請注意，defaultSnippets 不是 JSON 結構描述規格的一部分，而是 VS Code 特有的結構描述擴充功能。

在 Hover 提示中使用豐富的格式

VS Code 將使用 JSON 結構描述規格中的標準 description 欄位，以便在 Hover 提示和自動完成期間提供有關屬性的資訊。

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

{
  "$schema": "https://json-schema.dev.org.tw/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 擴充功能是否從 http 和 https 擷取 JSON 結構描述。

當目前的編輯器想要使用無法下載的結構描述時，狀態列中會顯示一個警告三角形。