語言配置指南

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和decreaseIndentPattern之外，還有另外兩個縮排規則

• indentNextLinePattern - 如果一行匹配此模式，則只有其下一行應縮排一次。
• unIndentedLinePattern - 如果一行匹配此模式，則其縮排不應更改，並且不應根據其他規則進行評估。

如果程式語言沒有設定縮排規則，則當行以開括號結尾時編輯器將縮排，當您鍵入閉括號時將取消縮排。這裡的括號由brackets定義。

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

回車規則

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。從新行縮排中刪除的字元數。