🚀 在 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"] }
  ]
}

notIn 鍵會在特定程式碼範圍中停用此功能。例如，當您撰寫下列程式碼時

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

單引號將不會自動關閉。

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

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

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

之前的自動關閉

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

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

但是，此定義會覆寫該行為

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

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

自動包圍

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

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

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

摺疊

在 VS Code 中，摺疊是以縮排為基礎定義，或由貢獻的摺疊範圍提供者定義

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

下列 JSON 為 //#region 和 //#endregion 建立摺疊標記。

{
  "folding": {
    "markers": {
      "start": "^\\s*//\\s*#?region\\b",
      "end": "^\\s*//\\s*#?endregion\\b"
    }
  }
}
  • 語言伺服器摺疊：語言伺服器會使用摺疊範圍清單回應 textDocument/foldingRange 請求，而 VS Code 會將這些範圍呈現為摺疊標記。若要深入瞭解語言伺服器協定中的摺疊支援，請參閱程式化語言功能主題。

單字模式

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

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

縮排規則

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

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

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

if (true) {
  console.log();

除了 increaseIndentPattern 和 decreaseIndentPatter 之外，還有兩個其他縮排規則

  • indentNextLinePattern - 如果某行符合此模式，則只有其後的下一行應縮排一次。
  • unIndentedLinePattern - 如果某行符合此模式，則不應變更其縮排，並且不應針對其他規則進行評估。

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

請注意，editor.formatOnPaste 設定是由 DocumentRangeFormattingEditProvider 控制，而不是由自動縮排影響。

On Enter 規則

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

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

按下 Enter 鍵時，會根據下列屬性檢查游標之前、之後或游標上方一行的文字

  • beforeText (必要)。符合游標之前文字的正則表達式 (僅限於目前行)。
  • afterText。符合游標之後文字的正則表達式 (僅限於目前行)。
  • previousLineText。符合游標上方一行文字的正則表達式。

如果所有指定的屬性都符合，則視為規則符合，並且不會再評估其他 onEnterRules。onEnterRule 可以指定下列動作

  • indent (必要)。none, indent, outdent, indentOutdent 其中之一。
    • none 表示新行將繼承目前行的縮排。
    • indent 表示新行將相對於目前行縮排。
    • outdent 表示新行將相對於目前行取消縮排。
    • indentOutdent 表示將插入兩行新行，第一行縮排，第二行取消縮排。
  • appendText。將附加在新行之後和縮排之後的字串。
  • removeText。要從新行的縮排中移除的字元數。
02/06/2025