🚀 在 VS Code 中免費取得 ！

語言組態指南

contributes.languages 貢獻點允許您定義語言組態，以控制下列宣告式語言功能

  • 註解切換
  • 括號定義
  • 自動關閉
  • 自動包圍
  • 折疊
  • 單字模式
  • 縮排規則

這裡有一個語言組態範例，設定 JavaScript 檔案的編輯體驗。本指南說明 language-configuration.json 的內容

注意：如果您的語言組態檔名是 language-configuration.json 或以此結尾，您將在 VS Code 中獲得自動完成和驗證。

{
  "comments": {
    "lineComment": "//",
    "blockComment": ["/*", "*/"]
  },
  "brackets": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"]
  ],
  "autoClosingPairs": [
    { "open": "{", "close": "}" },
    { "open": "[", "close": "]" },
    { "open": "(", "close": ")" },
    { "open": "'", "close": "'", "notIn": ["string", "comment"] },
    { "open": "\"", "close": "\"", "notIn": ["string"] },
    { "open": "`", "close": "`", "notIn": ["string", "comment"] },
    { "open": "/**", "close": " */", "notIn": ["string"] }
  ],
  "autoCloseBefore": ";:.,=}])>` \n\t",
  "surroundingPairs": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"],
    ["'", "'"],
    ["\"", "\""],
    ["`", "`"]
  ],
  "folding": {
    "markers": {
      "start": "^\\s*//\\s*#?region\\b",
      "end": "^\\s*//\\s*#?endregion\\b"
    }
  },
  "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)",
  "indentationRules": {
    "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
    "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
  }
}

註解切換

VS Code 提供兩個命令用於註解切換。「切換行註解」和「切換區塊註解」。您可以指定 comments.blockComment 和 comments.lineComment 來控制 VS Code 應如何註解程式碼行/區塊。

{
  "comments": {
    "lineComment": "//",
    "blockComment": ["/*", "*/"]
  }
}

括號定義

當您將游標移動到此處定義的括號時，VS Code 將會醒目提示該括號及其配對的括號。

{
  "brackets": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"]
  ]
}

此外，當您執行「跳到括號」或「選取到括號」時，VS Code 將使用上述定義來尋找最近的括號及其配對的括號。

自動關閉

當您輸入 ' 時，VS Code 會建立一對單引號，並將您的游標放在中間：'|'。

{
  "autoClosingPairs": [
    { "open": "{", "close": "}" },
    { "open": "[", "close": "]" },
    { "open": "(", "close": ")" },
    { "open": "'", "close": "'", "notIn": ["string", "comment"] },
    { "open": "\"", "close": "\"", "notIn": ["string"] },
    { "open": "`", "close": "`", "notIn": ["string", "comment"] },
    { "open": "/**", "close": " */", "notIn": ["string"] }
  ]
}

本節定義了這類配對。

// ES6's Template String
`ES6's Template String`;

`notIn` 鍵會在某些程式碼範圍內停用此功能。例如，當您撰寫以下程式碼時

單引號將不會自動關閉。

{
  "autoClosingPairs": [
    ["{", "}"],
    ["[", "]"]
  ]
}

不需要 notIn 屬性的配對也可以使用更簡單的語法

使用者可以使用 editor.autoClosingQuotes 和 editor.autoClosingBrackets 設定來調整自動關閉行為。

自動關閉之前

const Component = () =>
  <div className={>
                  ^ Does not get autoclosed by default
  </div>

預設情況下，只有在游標正後方有空白字元時，VS Code 才會自動關閉配對。因此，當您在以下 JSX 程式碼中輸入 { 時，您不會獲得自動關閉

{
  "autoCloseBefore": ";:.,=}])>` \n\t"
}

不過，此定義會覆寫該行為

自動包圍

現在，當您在 > 之前輸入 { 時，VS Code 會使用 } 自動關閉它。

{
  "surroundingPairs": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"],
    ["'", "'"],
    ["\"", "\""],
    ["`", "`"]
  ]
}

當您在 VS Code 中選取範圍並輸入左括號時，VS Code 會使用一對括號包圍選取的內容。此功能稱為「自動包圍」，您可以在此處定義特定語言的自動包圍配對

折疊

使用者可以使用 editor.autoSurround 設定來調整自動包圍行為。

  • 在 VS Code 中，折疊可以定義為基於縮排，或由貢獻的折疊範圍提供者定義

基於縮排的標記折疊：如果給定語言沒有可用的折疊範圍提供者，或者使用者已將 editor.foldingStrategy 設定為 indentation，則會使用基於縮排的折疊。當一行程式碼的縮排小於一或多個後續行時，折疊區域開始；當出現縮排相同或更小的行時，折疊區域結束。空白行會被忽略。此外，語言組態可以定義開始和結束標記。這些標記在 folding.markers 中定義為 start 和 end 正則表達式。找到符合的行時，會在配對內建立折疊範圍。折疊標記不得為空，通常看起來像 //#region 和 //#endregion。

{
  "folding": {
    "markers": {
      "start": "^\\s*//\\s*#?region\\b",
      "end": "^\\s*//\\s*#?endregion\\b"
    }
  }
}
  • 以下 JSON 為 //#region 和 //#endregion 建立折疊標記。

單字模式

語言伺服器折疊：語言伺服器會使用折疊範圍列表回應 textDocument/foldingRange 請求，而 VS Code 會將這些範圍呈現為折疊標記。在程式化語言功能主題中了解有關語言伺服器協定中折疊支援的更多資訊。

{
  "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)"
}

縮排規則

wordPattern 定義程式語言中被視為單字的內容。如果設定了 wordPattern，程式碼建議功能將使用此設定來判斷單字邊界。請注意，此設定不會影響與單字相關的編輯器命令，這些命令由編輯器設定 editor.wordSeparators 控制。

{
  "indentationRules": {
    "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
    "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
  }
}

indentationRules 定義當您輸入、貼上和移動程式碼行時，編輯器應如何調整目前行或下一行的縮排。

if (true) {
  console.log();

例如，if (true) { 符合 increaseIndentPattern，那麼如果您在左大括號 { 後按下 Enter 鍵，編輯器將自動縮排一次，而您的程式碼最終會變成

  • 除了 increaseIndentPattern 和 decreaseIndentPatter 之外，還有另外兩個縮排規則
  • indentNextLinePattern - 如果一行程式碼符合此模式，則只有它之後的下一行應該縮排一次。

unIndentedLinePattern - 如果一行程式碼符合此模式，則不應變更其縮排，並且不應針對其他規則進行評估。

如果沒有為程式語言設定縮排規則，則當行尾以左括號結尾時，編輯器將會縮排；當您輸入右括號時，編輯器將會取消縮排。此處的括號由 brackets 定義。

Enter 鍵規則

請注意，editor.formatOnPaste 設定由 DocumentRangeFormattingEditProvider 控制，並且不受自動縮排的影響。

{
  "onEnterRules": [
    {
      "beforeText": "^\\s*(?:def|class|for|if|elif|else|while|try|with|finally|except|async).*?:\\s*$",
      "action": { "indent": "indent" }
    }
  ]
}

onEnterRules 定義按下 Enter 鍵時將在編輯器中評估的規則列表。

  • 按下 Enter 鍵時，游標之前、之後或游標上方一行的文字會根據以下屬性進行檢查
  • beforeText (必要)。符合游標之前文字的正則表達式（僅限於目前行）。
  • afterText。符合游標之後文字的正則表達式（僅限於目前行）。

previousLineText。符合游標上方一行文字的正則表達式。

  • 如果所有指定的屬性都符合，則規則被視為符合，並且不會評估進一步的 onEnterRules。onEnterRule 可以指定以下動作
    • indent (必要)。none、indent、outdent、indentOutdent 之一。
    • none 表示新行將繼承目前行的縮排。
    • indent 表示新行將相對於目前行縮排。
    • outdent 表示新行將相對於目前行取消縮排。
  • indentOutdent 表示將插入兩行新行，第一行縮排，第二行取消縮排。
  • appendText。一個字串，將附加在新行和縮排之後。
04/03/2025