💻 歡迎參加 6 月 3 日舉行的 MS Build 之 VS Code 直播活動。

語言組態指南

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

  • 註解切換 (Comment toggling)
  • 括號定義 (Brackets definition)
  • 自動閉合 (Autoclosing)
  • 自動包覆 (Autosurrounding)
  • 程式碼摺疊
  • 文字樣式 (Word pattern)
  • 縮排規則 (Indentation Rules)

這裡有一個 語言設定範例，用以設定 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*[\\)\\}\\]].*$"
  }
}

註解切換 (Comment toggling)

VS Code 提供兩個註解切換指令：切換行註解 (Toggle Line Comment) 與 切換區塊註解 (Toggle Block Comment)。您可以指定 comments.blockComment 與 comments.lineComment 來控制 VS Code 應如何註解程式碼行/區塊。

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

lineComment 屬性為了向後相容，支援兩種格式：

  • 用於簡單行註解定義的字串值。
  • 用於設定註解行縮排行為的物件值。
{
  "comments": {
    "lineComment": {
      "comment": "//",
      "noIndent": true
    },
    "blockComment": ["/*", "*/"]
  }
}

括號定義 (Brackets definition)

當您將游標移至此處定義的括號時，VS Code 將會反白顯示該括號及其對應的配對。

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

此外，當您執行 前往括號 (Go to Bracket) 或 選取至括號 (Select to Bracket) 時，VS Code 會使用上述定義來尋找最近的括號及其對應配對。

自動閉合 (Autoclosing)

當您輸入 ' 時，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 設定來調整自動閉合行為。

自動閉合之前 (Autoclosing before)

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

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

然而，此定義會覆寫該行為：

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

現在，當您在 > 之前輸入 { 時，VS Code 會用 } 將其自動閉合。

自動包覆 (Autosurrounding)

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

{
  "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"
    }
  }
}

文字樣式 (Word Pattern)

wordPattern 定義了該程式語言中何者被視為一個「詞」。如果已設定 wordPattern，程式碼建議功能將使用此設定來判斷詞邊界。請注意，此設定不會影響與文字相關的編輯器指令，那些指令由編輯器設定 editor.wordSeparators 控制。

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

縮排規則 (Indentation Rules)

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

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

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

if (true) {
  console.log();

除了 increaseIndentPattern 與 decreaseIndentPattern 外，還有其他兩種縮排規則：

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

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

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

按 Enter 鍵規則 (On Enter Rules)

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。從新行縮排中移除的字元數。
5/28/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.