貢獻點 (Contribution Points)

貢獻點（Contribution Points）是一組 JSON 宣告，您可以將其放在 package.json 擴充功能資訊清單的 contributes 欄位中。您的擴充功能會註冊貢獻點，以擴充 Visual Studio Code 內的各種功能。以下是所有可用貢獻點的清單

• authentication (驗證)
• breakpoints
• chatAgents
• chatInstructions
• chatPromptFiles
• chatSkills
• colors
• 命令 (commands)
• configuration
• configurationDefaults
• customEditors
• debuggers
• grammars
• icons
• iconThemes
• jsonValidation
• keybindings
• 語言 (languages)
• languageModelChatProviders
• languageModelTools
• menus
• problemMatchers
• problemPatterns
• productIconThemes
• resourceLabelFormatters
• semanticTokenModifiers
• semanticTokenScopes
• semanticTokenTypes
• 程式碼片段 (snippets)
• submenus
• taskDefinitions
• terminal
• themes
• typescriptServerPlugins
• views
• viewsContainers
• viewsWelcome
• walkthroughs

contributes.authentication

貢獻驗證提供者。這會為您的提供者設定啟用事件，並將其顯示在擴充功能的功能中。

{
  "contributes": {
    "authentication": [
      {
        "label": "Azure DevOps",
        "id": "azuredevops"
      }
    ]
  }
}

contributes.breakpoints

通常偵錯工具擴充功能也會有一個 contributes.breakpoints 項目，擴充功能會在其中列出啟用設定中斷點的語言檔案類型。

{
  "contributes": {
    "breakpoints": [
      {
        "language": "javascript"
      },
      {
        "language": "javascriptreact"
      }
    ]
  }
}

contributes.chatAgents

為 Copilot Chat 貢獻 自訂代理程式。自訂代理程式是預先設定的 AI 角色，帶有特定的指示與工具限制。使用此貢獻點將可重複使用的自訂代理程式與您的擴充功能打包在一起，使其與代理程式下拉式選單中的使用者定義代理程式並列顯示。

每個項目都需要一個相對於擴充功能根目錄的 .agent.md 檔案的 path。您可以選擇性地指定 when 子句來有條件地啟用代理程式。請在 .agent.md 的 frontmatter 中指定代理程式的 name、description 和其他後設資料，而不是在貢獻點中指定。

{
  "contributes": {
    "chatAgents": [
      {
        "path": "./agents/planner.agent.md"
      }
    ]
  }
}

chatAgents 屬性

請參閱 VS Code 中的自訂代理程式以了解所需的 .agent.md 檔案格式，包含 name、description、tools 和 model frontmatter 欄位。

contributes.chatInstructions

為 Copilot Chat 貢獻 指示檔案。指示檔案提供自訂指導方針，會自動包含在聊天要求中以引導 Copilot 的行為。使用此貢獻點將可重複使用的指示與您的擴充功能打包在一起，例如編碼慣例、框架特定指導方針或網域特定規則。

當使用者的聊天要求與指示的使用情境相關時，Copilot 會自動套用所貢獻的指示。您不需要手動附加它們。

每個項目都需要一個相對於擴充功能根目錄的 Markdown 檔案 path。您可以選擇性地指定 when 子句來控制何時啟用指示。請在 Markdown 檔案本身內部指定 name 和 description 後設資料，而不是在貢獻點中指定。

{
  "contributes": {
    "chatInstructions": [
      {
        "path": "./prompts/textMateGuidelines.instructions.md"
      }
    ]
  }
}

您可以使用選用的 when 子句根據內容來有條件地啟用指示

{
  "contributes": {
    "chatInstructions": [
      {
        "path": "./prompts/textMateGuidelines.instructions.md",
        "when": "resourceExtname == .tmLanguage"
      }
    ]
  }
}

chatInstructions 屬性

請參閱 chatPromptFiles 貢獻點以貢獻可重複使用的提示檔案。

contributes.chatPromptFiles

為 Copilot Chat 貢獻 提示檔案。提示檔案是可重複使用的聊天提示，使用者可以在聊天中以斜線命令叫用它們。使用此貢獻點將現成的提示與您的擴充功能打包在一起。

每個項目都需要一個相對於擴充功能根目錄的 Markdown 檔案 path。您可以選擇性地指定 when 子句來有條件地啟用提示。請在 Markdown 檔案本身內部指定 name 和 description 後設資料，而不是在貢獻點中指定。

{
  "contributes": {
    "chatPromptFiles": [
      {
        "path": "./prompts/reviewAndCreateIssue.prompt.md"
      }
    ]
  }
}

chatPromptFiles 屬性

請參閱 chatInstructions 貢獻點以貢獻可重複使用的指示檔案。

contributes.chatSkills

為 Copilot Chat 貢獻 代理程式技能 (Agent Skills)。代理程式技能是包含指示、指令碼和資源的資料夾，Copilot 可以在相關時載入這些內容以執行專門的任務。使用此貢獻點將可重複使用的技能與您的擴充功能打包在一起。

每個項目都需要一個相對於擴充功能根目錄的 SKILL.md 檔案 path。SKILL.md 檔案必須遵循 Agent Skills 規格，且其 name 欄位必須與父目錄名稱相符。您可以選擇性地指定 when 子句來有條件地啟用此技能。

{
  "contributes": {
    "chatSkills": [
      {
        "path": "./skills/my-skill/SKILL.md"
      }
    ]
  }
}

chatSkills 屬性

請參閱從擴充功能貢獻技能以了解所需的技能結構與 SKILL.md 格式。

contributes.colors

貢獻新的可佈景主題顏色。擴充功能可以在編輯器裝飾項目與狀態列中使用這些顏色。一旦定義後，使用者可以在 workspace.colorCustomization 設定中自訂顏色，且使用者佈景主題可以設定顏色值。

{
  "contributes": {
    "colors": [
      {
        "id": "superstatus.error",
        "description": "Color for error message in the status bar.",
        "defaults": {
          "dark": "errorForeground",
          "light": "errorForeground",
          "highContrast": "#010203",
          "highContrastLight": "#feedc3"
        }
      }
    ]
  }
}

可以為淺色、深色和高對比佈景主題定義顏色的預設值，且可以是指向現有顏色的參考或 顏色十六進位值。

擴充功能可以使用 ThemeColor API 來取用新舊佈景主題顏色

const errorColor = new vscode.ThemeColor('superstatus.error');

contributes.commands

為命令貢獻 UI，該命令由標題以及（選擇性的）圖示、類別和啟用狀態組成。啟用狀態是以 when 子句表示。預設情況下，命令會顯示在命令選擇區（⇧⌘P (Windows, Linux Ctrl+Shift+P)）中，但它們也可以顯示在其他 功能表中。

所貢獻命令的呈現方式取決於包含它的功能表。例如，命令選擇區會在命令前面加上其 category 作為字首，以便輕鬆進行分組。不過，命令選擇區不會顯示圖示或停用的命令。另一方面，編輯器操作功能表會顯示停用的項目，但不會顯示類別標籤。

注意：當叫用命令時（從鍵盤快速鍵、命令選擇區、任何其他功能表或透過程式設計方式），VS Code 將會發出啟用事件 onCommand:${command}。

注意：當使用來自產品圖示的圖示時，設定 light 和 dark 將會停用該圖示。正確的語法為 "icon": "$(book)"

命令範例

{
  "contributes": {
    "commands": [
      {
        "command": "extension.sayHello",
        "title": "Hello World",
        "category": "Hello",
        "icon": {
          "light": "path/to/light/icon.svg",
          "dark": "path/to/dark/icon.svg"
        }
      }
    ]
  }
}

請參閱命令擴充功能指南以深入了解如何在 VS Code 擴充功能中使用命令。

命令圖示規格

• 大小：圖示應為 16x16，具有 1 個像素的內邊距（圖片為 14x14）並置中。
• 顏色：圖示應使用單一顏色。
• 格式：建議圖示採用 SVG，不過接受任何圖片檔案類型。

contributes.configuration

貢獻將公開給使用者的設定。使用者將能在「設定」編輯器中或透過直接編輯 settings.json 檔案來設定這些組態選項。

此區段可以是用於代表單一設定類別的單一物件，或是用於代表多個設定類別的物件陣列。如果有多個設定類別，「設定」編輯器將會在該擴充功能目錄中顯示子功能表，且標題金鑰將用於子功能表項目名稱。

組態範例

{
  "contributes": {
    "configuration": {
      "title": "Settings Editor Test Extension",
      "type": "object",
      "properties": {
        "settingsEditorTestExtension.booleanExample": {
          "type": "boolean",
          "default": true,
          "description": "Boolean Example"
        },
        "settingsEditorTestExtension.stringExample": {
          "type": "string",
          "default": "Hello World",
          "description": "String Example"
        }
      }
    }
  }
}

您可以使用 vscode.workspace.getConfiguration('myExtension') 從您的擴充功能中讀取這些值。

組態結構描述

您的組態項目可用於在 JSON 編輯器中編輯設定時提供智慧感知（IntelliSense），並用於定義它們在設定 UI 中的顯示方式。

title

類別的 title 1️⃣️ 是用於該類別的標題。

{
  "configuration": {
    "title": "GitMagic"
  }
}

對於具有多個設定類別的擴充功能，如果其中一個類別的標題與擴充功能的顯示名稱相同，則設定 UI 會將該類別視為「預設類別」，忽略該類別的 order 欄位，並將其設定置於主要擴充功能標題下方。

對於 title 和 displayName 欄位，「Extension」、「Configuration」和「Settings」等詞彙是多餘的。

• ✔ "title": "GitMagic"
• ❌ "title": "GitMagic Extension"
• ❌ "title": "GitMagic Configuration"
• ❌ "title": "GitMagic Extension Configuration Settings"

properties

您 configuration 物件中的 properties 2️⃣ 將會形成一個字典，其中金鑰為設定 ID，而值則提供有關該設定的更多資訊。雖然擴充功能可以包含多個設定類別，但擴充功能的每個設定仍必須具有其自己的唯一 ID。設定 ID 不能是另一個設定 ID 的完整前置詞。

沒有明確 order 欄位的屬性將會按照字典順序顯示在設定 UI 中（not 欄位所列出的順序改為而非資訊清單中列出的順序）。

設定標題

在設定 UI 中，將會使用多個欄位來為每個設定建構顯示標題。您金鑰中的大寫字母用於表示單字分隔。

單一類別與預設類別組態的顯示標題

如果組態具有單一設定類別，或者該類別具有與擴充功能顯示名稱相同的標題，則對於該類別內的設定，設定 UI 將會使用設定 ID 與擴充功能的 name 欄位來決定顯示標題。

舉例來說，對於設定 ID gitMagic.blame.dateFormat 與擴充功能名稱 authorName.gitMagic，由於設定 ID 的前置詞與擴充功能名稱的後置詞相符，因此設定 ID 中的 gitMagic 部分將會在顯示標題中被移除：「Blame: Date Format」。

多類別組態的顯示標題

如果組態具有多個設定類別，且該類別的標題與擴充功能的顯示名稱不同，則對於該類別內的設定，設定 UI 將會使用設定 ID 與類別的 id 欄位來決定顯示標題。

舉例來說，對於設定 ID css.completion.completePropertyWithSemicolon 與類別 ID css，由於設定 ID 的前置詞與類別 ID 的後置詞相符，因此設定 ID 中的 css 部分將會在設定 UI 中被移除，且該設定產生的標題將會是「Completion: Complete Property With Semicolon」。

組態屬性結構描述

組態金鑰是使用 JSON Schema 的超集來定義。

description / markdownDescription

您的 description 3️⃣ 會顯示在標題之後、輸入欄位之前，但布林值除外，布林值的描述會被用作核取方塊的標籤。6️⃣

{
  "gitMagic.blame.heatMap.enabled": {
    "description": "Specifies whether to provide a heatmap indicator in the gutter blame annotations"
  }
}

如果您使用 markdownDescription 而非 description，您的設定描述將會在設定 UI 中被解析為 Markdown。

{
  "gitMagic.blame.dateFormat": {
    "markdownDescription": "Specifies how to format absolute dates (e.g. using the `${date}` token) in gutter blame annotations. See the [Moment.js docs](https://momentjs.com/docs/#/displaying/format/) for valid formats"
  }
}

對於 markdownDescription，若要新增換行或多個段落，請使用字串 \n\n 來分隔段落，而不是僅使用 \n。

類型

number 4️⃣、string 5️⃣、boolean 6️⃣ 類型的項目可以直接在設定 UI 中進行編輯。

{
  "gitMagic.views.pageItemLimit": {
    "type": "number",
    "default": 20,
    "markdownDescription": "Specifies the number of items to show in each page when paginating a view list. Use 0 to specify no limit"
  }
}

如果在組態項目上設定了 "editPresentation": "multilineText"，字串設定可以透過多行文字輸入來呈現。

對於 boolean 項目，markdownDescription（如果未指定 markdownDescription 則為 description）將會被用作核取方塊旁邊的標籤。

{
  "gitMagic.blame.compact": {
    "type": "boolean",
    "description": "Specifies whether to compact (deduplicate) matching adjacent gutter blame annotations"
  }
}

某些 object 和 array 類型的設定將會呈現在設定 UI 中。number、string 或 boolean 的簡單陣列將會呈現為可編輯的清單。具有 string、number、integer 和/或 boolean 類型屬性的物件將會呈現為可編輯的金鑰與值網格。物件設定也應該將 additionalProperties 設定為 false，或設定為具有適當 type 屬性的物件，以便在 UI 中呈現。

如果 object or array 類型的設定也可以包含其他類型，例如巢狀物件、陣列或 null，則該值將不會在設定 UI 中呈現，且只能透過直接編輯 JSON 來修改。使用者將會看到一個指向在 settings.json 中編輯的連結，如上方的螢幕擷取畫面所示。8️⃣

order

類別以及這些類別內的設定都可以接受整數 order 類型屬性，這提供了關於它們應如何相對於其他類別和/或設定進行排序的參考。

如果兩個類別都有 order 屬性，則排序數字較小的類別會排在前面。如果某個類別未獲指派 order 屬性，它將會出現在已獲指派該屬性的類別之後。

如果同一類別內的兩個設定都有 order 屬性，則排序數字較小的設定會排在前面。如果同一類別內的另一個設定未獲指派 order 屬性，它將會出現在該類別中已獲指派該屬性的設定之後。

如果兩個類別具有相同的 order 屬性值，或者同一類別內的兩個設定具有相同的 order 屬性值，則它們將會在設定 UI 內按遞增的字典順序進行排序。

enum / enumDescriptions / markdownEnumDescriptions / enumItemLabels

如果您在 enum 7️⃣ 屬性下提供項目陣列，設定 UI 將會呈現這些項目的下拉式選單。

您也可以提供 enumDescriptions 屬性，這是一個長度與 enum 屬性相同的字串陣列。enumDescriptions 屬性會在設定 UI 中下拉式選單的最下方，提供對應每個 enum 項目的描述。
您也可以使用 markdownEnumDescriptions 來取代 enumDescriptions，您的描述將會被解析為 Markdown。markdownEnumDescriptions 的優先權高於 enumDescriptions。
若要自訂設定 UI 中的下拉式選項名稱，您可以使用 enumItemLabels。

範例

{
  "settingsEditorTestExtension.enumSetting": {
    "type": "string",
    "enum": ["first", "second", "third"],
    "markdownEnumDescriptions": [
      "The *first* enum",
      "The *second* enum",
      "The *third* enum"
    ],
    "enumItemLabels": ["1st", "2nd", "3rd"],
    "default": "first",
    "description": "Example setting with an enum"
  }
}

deprecationMessage / markdownDeprecationMessage

如果您設定了 deprecationMessage 或 markdownDeprecationMessage，該設定將會帶有您指定訊息的警告底線。此外，除非使用者已進行設定，否則該設定將會從設定 UI 中隱藏。如果您設定了 markdownDeprecationMessage，該 markdown 將不會在設定懸停提示或問題檢視中呈現。如果您同時設定了這兩個屬性，deprecationMessage 將會顯示在懸停提示和問題檢視中，而 markdownDeprecationMessage 則會作為 Markdown 呈現在設定 UI 中。

範例

{
  "json.colorDecorators.enable": {
    "type": "boolean",
    "description": "Enables or disables color decorators",
    "markdownDeprecationMessage": "**Deprecated**: Please use `#editor.colorDecorators#` instead.",
    "deprecationMessage": "Deprecated: Please use editor.colorDecorators instead."
  }
}

其他 JSON Schema 屬性

您可以使用任何驗證 JSON Schema 屬性來描述組態值的其他條件約束

• 用於定義屬性預設值的 default
• 用於限制數值的 minimum 和 maximum
• 用於限制字串長度的 maxLength、minLength
• 用於將字串限制為給定正規表示式的 pattern
• 當模式不符時提供自訂錯誤訊息的 patternErrorMessage。
• 用於將字串限制為知名格式（例如 date、time、ipv4、email 和 uri）的 format
• 用於限制陣列長度的 maxItems、minItems
• 用於控制在「設定」編輯器中為字串設定呈現單行輸入方塊或是多行文字區域的 editPresentation

不支援的 JSON Schema 屬性

組態區段中不支援的項目有：

• $ref 和 definition：組態結構描述需要是獨立自主的，且不能對彙總的設定 JSON schema 文件外觀做出假設。

有關這些及其他功能的更多詳細資訊，請參閱 JSON Schema 參考。

scope

組態設定可以具有下列其中一個可能的範圍：

• application - 套用至所有 VS Code 執行個體且只能在使用者設定中進行組態的設定。
• machine - 機器特定的設定，只能在使用者設定或遠端設定中設定。例如，不應在不同機器之間共用安裝路徑。這些設定的值將不會進行同步處理。
• machine-overridable - 可由工作區或資料夾設定覆寫的機器特定設定。這些設定的值將不會進行同步處理。
• window - 視窗（執行個體）特定設定，可以在使用者、工作區或遠端設定中進行組態。
• resource - 資源設定，適用於檔案和資料夾，可以在所有設定層級（甚至是資料夾設定）中進行組態。
• language-overridable - 可以在語言層級進行覆寫的資源設定。

組態範圍決定了何時透過「設定」編輯器將設定提供給使用者，以及該設定是否適用。如果未宣告任何 scope，則預設值為 window。

以下是內建 Git 擴充功能的組態範圍範例

{
  "contributes": {
    "configuration": {
      "title": "Git",
      "properties": {
        "git.alwaysSignOff": {
          "type": "boolean",
          "scope": "resource",
          "default": false,
          "description": "%config.alwaysSignOff%"
        },
        "git.ignoredRepositories": {
          "type": "array",
          "default": [],
          "scope": "window",
          "description": "%config.ignoredRepositories%"
        },
        "git.autofetch": {
          "type": ["boolean", "string"],
          "enum": [true, false, "all"],
          "scope": "resource",
          "markdownDescription": "%config.autofetch%",
          "default": false,
          "tags": ["usesOnlineServices"]
        }
      }
    }
  }
}

您可以看到 git.alwaysSignOff 具有 resource 範圍，並且可以針對每個使用者、工作區或資料夾進行設定，而具有 window 範圍的忽略儲存機制清單則更全域地適用於 VS Code 視窗或工作區（可能是多根工作區）。

ignoreSync

您可以將 ignoreSync 設定為 true，以防止該設定與使用者的設定進行同步。這對於非使用者特定的設定非常有用。例如，remoteTunnelAccess.machineName 設定並非使用者特定，且不應進行同步。請注意，如果您已將 scope 設定為 machine 或 machine-overridable，則無論 ignoreSync 的值為何，該設定都不會進行同步。

{
  "contributes": {
    "configuration": {
      "properties": {
        "remoteTunnelAccess.machineName": {
          "type": "string",
          "default": "",
          "ignoreSync": true
        }
      }
    }
  }
}

連結至設定

您可以在 markdown 類型的屬性中使用此特殊語法來插入另一個設定的連結，該連結將會在設定 UI 中呈現為可按下的連結：`#target.setting.id#`。這將適用於 markdownDescription、markdownEnumDescriptions 和 markdownDeprecationMessage。範例

  "files.autoSaveDelay": {
    "markdownDescription": "Controls the delay in ms after which a dirty editor is saved automatically. Only applies when `#files.autoSave#` is set to `afterDelay`.",
    // ...
  }

在設定 UI 中，這會呈現為

contributes.configurationDefaults

為其他已註冊的組態貢獻預設值並覆寫其預設值。

以下範例覆寫了 files.autoSave 設定的預設行為，改為在焦點變更時自動儲存檔案。

"configurationDefaults": {
      "files.autoSave": "onFocusChange"
}

您也可以為提供的語言貢獻預設編輯器組態。例如，以下程式碼片段為 markdown 語言貢獻了預設編輯器組態

{
  "contributes": {
    "configurationDefaults": {
      "[markdown]": {
        "editor.wordWrap": "on",
        "editor.quickSuggestions": {
          "comments": "off",
          "strings": "off",
          "other": "off"
        }
      }
    }
  }
}

contributes.customEditors

customEditors 貢獻點是您的擴充功能用來向 VS Code 告知其所提供的自訂編輯器的方式。例如，VS Code 需要知道您的自訂編輯器適用哪些類型的檔案，以及如何在任何 UI 中識別您的自訂編輯器。

以下是針對 自訂編輯器擴充功能範例的基本 customEditor 貢獻

"contributes": {
  "customEditors": [
    {
      "viewType": "catEdit.catScratch",
      "displayName": "Cat Scratch",
      "selector": [
        {
          "filenamePattern": "*.cscratch"
        }
      ],
      "priority": "default"
    }
  ]
}

customEditors 是一個陣列，因此您的擴充功能可以貢獻多個自訂編輯器。

• viewType - 自訂編輯器的唯一識別碼。

  這就是 VS Code 將 package.json 中的自訂編輯器貢獻與您在程式碼中的自訂編輯器實作連結起來的方式。這在所有擴充功能中必須是唯一的，因此請確保使用對您的擴充功能而言是唯一的 viewType（例如 "viewType": "myAmazingExtension.svgPreview"），而不是像 "preview" 這種通用名稱。

• displayName - 在 VS Code UI 中識別自訂編輯器的名稱。

  顯示名稱會顯示在 VS Code UI（例如檢視: 重新開啟並使用...下拉式選單）中給使用者看。

• selector - 指定自訂編輯器對哪些檔案有效。

  selector 是一個或多個 glob 模式的陣列。這些 glob 模式會與檔名進行比對，以決定是否可將自訂編輯器用於這些檔案。像 *.png 這樣的 filenamePattern 將會為所有 PNG 檔案啟用自訂編輯器。

  您也可以建立更具體的模式來比對檔案或目錄名稱，例如 **/translations/*.json。

• priority - （選用）指定何時使用自訂編輯器。

  priority 控制開啟資源時何時使用自訂編輯器。可能的值包括：

  • "default" - 嘗試對符合自訂編輯器 selector 的每個檔案使用自訂編輯器。如果給定檔案有多個自訂編輯器，使用者將必須選擇要使用哪個自訂編輯器。
  • "option" - 預設不使用自訂編輯器，但允許使用者切換至該編輯器或將其設定為預設值。

您可以透過自訂編輯器擴充功能指南深入了解。

contributes.debuggers

為 VS Code 貢獻偵錯工具。偵錯工具貢獻具有下列屬性：

• type 是用來在啟動組態中識別此偵錯工具的唯一 ID。
• label 是此偵錯工具在 UI 中對使用者顯示的名稱。
• program 是對真實偵錯工具或執行階段實作 VS Code 偵錯通訊協定的偵錯介面卡路徑。
• runtime（如果偵錯介面卡的徑不是可執行檔而是需要執行階段的話）。
• configurationAttributes 是此偵錯工具專屬之啟動組態引數的結構描述。請注意，不支援 JSON schema 建構 $ref 和 definition。
• initialConfigurations 列出用來填入初始 launch.json 的啟動組態。
• configurationSnippets 列出在編輯 launch.json 時可透過智慧感知（IntelliSense）使用的啟動組態。
• variables 引進替代變數並將其繫結至由偵錯工具擴充功能實作的命令。
• languages 是指該偵錯擴充功能可被視為「預設偵錯工具」的語言。

偵錯工具範例

{
  "contributes": {
    "debuggers": [
      {
        "type": "node",
        "label": "Node Debug",

        "program": "./out/node/nodeDebug.js",
        "runtime": "node",

        "languages": ["javascript", "typescript", "javascriptreact", "typescriptreact"],

        "configurationAttributes": {
          "launch": {
            "required": ["program"],
            "properties": {
              "program": {
                "type": "string",
                "description": "The program to debug."
              }
            }
          }
        },

        "initialConfigurations": [
          {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "program": "${workspaceFolder}/app.js"
          }
        ],

        "configurationSnippets": [
          {
            "label": "Node.js: Attach Configuration",
            "description": "A new configuration for attaching to a running node program.",
            "body": {
              "type": "node",
              "request": "attach",
              "name": "${2:Attach to Port}",
              "port": 9229
            }
          }
        ],

        "variables": {
          "PickProcess": "extension.node-debug.pickNodeProcess"
        }
      }
    ]
  }
}

有關如何整合 debugger 的完整逐步解說，請前往偵錯工具擴充功能。

contributes.grammars

為語言貢獻 TextMate 語法。您必須提供此語法所適用的 language、該語法的 TextMate scopeName 以及檔案路徑。

注意：包含語法的檔案可以是 JSON 格式（以 .json 結尾的檔名）或 XML plist 格式（所有其他檔案）。

語法範例

{
  "contributes": {
    "grammars": [
      {
        "language": "markdown",
        "scopeName": "text.html.markdown",
        "path": "./syntaxes/markdown.tmLanguage.json",
        "embeddedLanguages": {
          "meta.embedded.block.frontmatter": "yaml"
        }
      }
    ]
  }
}

請參閱語法突顯指南以深入了解如何註冊與語言關聯的 TextMate 語法以接收語法突顯。

contributes.icons

透過 ID 貢獻新圖示以及預設圖示。接著，擴充功能（或任何相依於該擴充功能的其他擴充功能）可以在任何可以使用 ThemeIcon 的地方（new ThemeIcon("iconId")）、Markdown 字串（$(iconId)）中，以及在某些貢獻點中作為圖示使用此圖示 ID。

{
  "contributes": {
    "icons": {
      "distro-ubuntu": {
        "description": "Ubuntu icon",
        "default": {
          "fontPath": "./distroicons.woff",
          "fontCharacter": "\\E001"
        }
      },
      "distro-fedora": {
        "description": "Ubuntu icon",
        "default": {
          "fontPath": "./distroicons.woff",
          "fontCharacter": "\\E002"
        }
      }
    }
  }
}

contributes.iconThemes

為 VS Code 貢獻檔案圖示佈景主題。檔案圖示會顯示在檔名旁，以指示檔案類型。

您必須指定 id（用於設定中）、label（標籤）以及檔案圖示定義檔案的路徑。

檔案圖示佈景主題範例

{
  "contributes": {
    "iconThemes": [
      {
        "id": "my-cool-file-icons",
        "label": "Cool File Icons",
        "path": "./fileicons/cool-file-icon-theme.json"
      }
    ]
  }
}

請參閱關於如何建立檔案圖示佈景主題的檔案圖示佈景主題指南。

contributes.jsonValidation

為特定類型的 json 檔案貢獻驗證結構描述。url 值可以是包含在擴充功能中的結構描述檔案的本機路徑，或是遠端伺服器 URL，例如 json schema store。

{
  "contributes": {
    "jsonValidation": [
      {
        "fileMatch": ".jshintrc",
        "url": "https://json.schemastore.org/jshintrc"
      }
    ]
  }
}

contributes.keybindings

貢獻鍵盤快速鍵規則，定義當使用者按下按鍵組合時應叫用什麼命令。請參閱詳細說明鍵盤快速鍵的鍵盤快速鍵主題。

貢獻鍵盤快速鍵會使「預設鍵盤快速鍵」顯示您的規則，且命令的每個 UI 表示法現在都會顯示您新增的鍵盤快速鍵。當然，當使用者按下按鍵組合時，就會叫用該命令。

注意：因為 VS Code 執行於修改鍵不同的 Windows、macOS 和 Linux 上，所以您可以使用 "key" 來設定預設按鍵組合，並用特定平台進行覆寫。

注意：當叫用命令時（從鍵盤快速鍵或從命令選擇區），VS Code 將會發出啟用事件 onCommand:${command}。

鍵盤快速鍵範例

定義 Windows 和 Linux 下的 Ctrl+F1 以及 macOS 下的 Cmd+F1 會觸發 "extension.sayHello" 命令

{
  "contributes": {
    "keybindings": [
      {
        "command": "extension.sayHello",
        "key": "ctrl+f1",
        "mac": "cmd+f1",
        "when": "editorTextFocus"
      }
    ]
  }
}

contributes.languages

貢獻程式語言的定義。這將會引進新的語言，或豐富 VS Code 對某個語言的了解。

contributes.languages 的主要效果為：

• 定義可在 VS Code API 的其他部分（例如 vscode.TextDocument.languageId 和 onLanguage 啟用事件）中重複使用的 languageId。
  • 您可以使用 aliases 欄位貢獻人類可讀的名稱。清單中的第一個項目將被用作人類可讀的標籤。
• 將副檔名（extensions）、檔名（filenames）、檔名 glob 模式（filenamePatterns）、以特定行（例如 hashbang）開頭的檔案（firstLine）以及 mimetypes 關聯至該 languageId。
• 為所貢獻的語言貢獻一組宣告式語言功能。在語言組態指南中深入了解可組態的編輯功能。
• 貢獻一個圖示，如果佈景主題未包含該語言的圖示，則可以在檔案圖示佈景主題中使用該圖示

語言範例

{
  "contributes": {
    "languages": [
      {
        "id": "python",
        "extensions": [".py"],
        "aliases": ["Python", "py"],
        "filenames": [],
        "firstLine": "^#!/.*\\bpython[0-9.-]*\\b",
        "configuration": "./language-configuration.json",
        "icon": {
          "light": "./icons/python-light.png",
          "dark": "./icons/python-dark.png"
        }
      }
    ]
  }
}

contributes.languageModelChatProviders

為 VS Code 貢獻語言模型聊天提供者，使擴充功能能夠提供使用者可以在模型挑選器中選取的自訂語言模型。每個提供者管理自己的模型集，並代表它們處理聊天要求。

為每個提供者註冊一個項目，並給予其唯一的 vendor ID。然後在您的擴充功能啟動中使用 vscode.lm.registerLanguageModelChatProvider 來連結實作。

{
  "contributes": {
    "languageModelChatProviders": [
      {
        "vendor": "my-provider",
        "displayName": "My Provider"
      }
    ]
  }
}

若要讓使用者組態提供者（例如輸入 API 金鑰），請新增 configuration 結構描述。將敏感欄位標記為 "secret": true，以便安全地儲存它們

languageModelChatProviders 屬性

請參閱語言模型聊天提供者 API 指南以取得完整的實作詳細資料。

contributes.languageModelTools

貢獻語言模型可以作為代理程式化編碼工作流程的一部分自動叫用的 語言模型工具。工具透過網域特定功能（例如查詢資料庫、呼叫外部 API 或與編輯器互動）來擴充代理程式模式。

在 contributes.languageModelTools 區段中定義每個工具，然後在您的擴充功能啟動中使用 vscode.lm.registerTool 註冊實作。

{
  "contributes": {
    "languageModelTools": [
      {
        "name": "my-extension_queryDatabase",
        "displayName": "Query Database",
        "modelDescription": "Executes a read-only SQL query against the project database and returns the results as JSON. Use this tool when the user asks about data stored in the database.",
        "canBeReferencedInPrompt": true,
        "toolReferenceName": "queryDatabase",
        "icon": "$(database)",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "The SQL SELECT statement to execute."
            }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

languageModelTools 屬性

請參閱語言模型工具 API 指南以取得實作詳細資料，包含如何處理確認、串流結果以及定義具型別的輸入參數。

contributes.menus

為編輯器或檔案總管貢獻命令的功能表項目。功能表項目定義包含選取時應叫用的命令，以及該項目應顯示的條件。後者是透過使用按鍵對應 when 子句內容的 when 子句來定義。

command 屬性表示選取功能表項目時要執行的命令。submenu 屬性表示要在這個位置呈現哪個子功能表。

宣告 command 功能表項目時，也可以使用 alt 屬性定義替代命令。當在開啟功能表的同時按下 Alt 鍵時，將會顯示並叫用它。在 Windows 和 Linux 上，按 Shift 也能達到此效果，這在 Alt 會觸發視窗功能表列的情況下非常有用。

最後，group 屬性定義了功能表項目的排序與分組。navigation 群組很特別，因為它一律會被排序到功能表的頂端/開頭。

請注意，when 子句適用於功能表，而 enablement 子句適用於命令。enablement 適用於所有功能表甚至是鍵盤快速鍵，而 when 僅適用於單一功能表。

目前擴充功能作者可以貢獻至：

• commandPalette - 全域命令選擇區
• comments/comment/title - 註解標題功能表列
• comments/comment/context - 註解操作功能表
• comments/commentThread/title - 註解討論串標題功能表列
• comments/commentThread/context- 註解討論串操作功能表
• debug/callstack/context - 偵錯呼叫堆疊檢視操作功能表
• debug/callstack/context 的 inline 群組 - 偵錯呼叫堆疊檢視內嵌動作
• debug/toolBar - 偵錯檢視工具列
• debug/variables/context - 偵錯變數檢視操作功能表
• editor/context - 編輯器操作功能表
• editor/lineNumber/context - 編輯器行號操作功能表
• editor/title - 編輯器標題功能表列
• editor/title/context - 編輯器標題操作功能表
• editor/title/run - 編輯器標題功能表列上的執行子功能表
• explorer/context - 檔案總管檢視操作功能表
• extension/context - 擴充功能檢視操作功能表
• file/newFile - 「檔案」功能表與歡迎頁面中的「新增檔案」項目
• interactive/toolbar - 互動視窗工具列
• interactive/cell/title - 互動視窗儲存格標題功能表列
• notebook/toolbar - 筆記本工具列
• notebook/cell/title - 筆記本儲存格標題功能表列
• notebook/cell/execute - 筆記本儲存格執行功能表
• scm/title - SCM 標題功能表
• scm/resourceGroup/context - SCM 資源群組功能表
• scm/resourceFolder/context - SCM 資源資料夾功能表
• scm/resourceState/context - SCM 資源功能表
• scm/change/title - SCM 變更標題功能表
• scm/repository - SCM 儲存機制功能表
• scm/sourceControl- SCM 原始碼控制功能表
• terminal/context - 終端機操作功能表
• terminal/title/context - 終端機標題操作功能表
• testing/item/context - 測試總管項目操作功能表
• testing/item/gutter - 測試項目裝訂邊裝飾的選單
• timeline/title - 時間軸檢視標題功能表列
• timeline/item/context - 時間軸檢視項目操作功能表
• touchBar - macOS 觸控列 (Touch Bar)
• view/title - 檢視標題功能表
• view/item/context - 檢視項目操作功能表
• webview/context - 任何 webview 操作功能表
• 任何貢獻的子功能表

注意 1：當從（操作）功能表叫用命令時，VS Code 會嘗試推斷目前選取的資源，並在叫用命令時將其作為參數傳遞。例如，檔案總管內的功能會傳遞所選資源的 URI，而編輯器內的功能則會傳遞文件的 URI。

注意 2：貢獻至 editor/lineNumber/context 的功能表項目命令也會傳遞行號。此外，這些項目可以在其 when 子句中參照 editorLineNumber 內容金鑰，例如透過使用 in 或 not in 運算子針對由擴充功能管理的陣列值內容金鑰進行測試。

除了標題之外，貢獻的命令還可以指定當叫用功能表項目表示為按鈕（例如在標題功能表列上）時，VS Code 將會顯示的圖示。

功能表範例

以下是一個命令功能表項目

{
  "contributes": {
    "menus": {
      "editor/title": [
        {
          "when": "resourceLangId == markdown",
          "command": "markdown.showPreview",
          "alt": "markdown.showPreviewToSide",
          "group": "navigation"
        }
      ]
    }
  }
}

同樣地，以下是新增至特定檢視的命令功能表項目。以下範例貢獻至類似終端機的任意檢視

{
  "contributes": {
    "menus": {
      "view/title": [
        {
          "command": "terminalApi.sendText",
          "when": "view == terminal",
          "group": "navigation"
        }
      ]
    }
  }
}

以下是一個子功能表項目

{
  "contributes": {
    "menus": {
      "scm/title": [
        {
          "submenu": "git.commit",
          "group": "2_main@1",
          "when": "scmProvider == git"
        }
      ]
    }
  }
}

命令選擇區功能表項目的內容特定可見性

在 package.json 中註冊命令時，它們會自動顯示在命令選擇區（⇧⌘P (Windows, Linux Ctrl+Shift+P)）中。為了對命令可見性提供更多控制，提供了 commandPalette 功能表項目。它允許您定義 when 條件來控制命令是否應該顯示在命令選擇區中。

以下程式碼片段使「Hello World」命令僅在編輯器中選取了某些內容時才顯示在命令選擇區中

{
  "commands": [
    {
      "command": "extension.sayHello",
      "title": "Hello World"
    }
  ],
  "menus": {
    "commandPalette": [
      {
        "command": "extension.sayHello",
        "when": "editorHasSelection"
      }
    ]
  }
}

群組的排序

功能表項目可以排序到群組中。它們會按照下列預設值/規則以字典順序進行排序。您可以將功能表項目新增至這些群組中，或在它們之間、下方或上方新增新的功能表項目群組。

編輯器操作功能表具有下列預設群組：

• navigation - navigation 群組在所有情況下都排在第一位。
• 1_modification - 這個群組排在接下來，包含修改您程式碼的命令。
• 9_cutcopypaste - 倒數第二個預設群組，包含基本編輯命令。
• z_commands - 最後一個預設群組，包含開啟命令選擇區的項目。

檔案總管操作功能表具有下列預設群組：

• navigation - 與整個 VS Code 導覽相關的命令。這個群組在所有情況下都排在第一位。
• 2_workspace - 與工作區操作相關的命令。
• 3_compare - 與在差異編輯器中比較檔案相關的命令。
• 4_search - 與在搜尋檢視中搜尋相關的命令。
• 5_cutcopypaste - 與剪下、複製和貼上檔案相關的命令。
• 6_copypath - 與複製檔案路徑相關的命令。
• 7_modification - 與修改檔案相關的命令。

編輯器標籤頁操作功能表具有下列預設群組：

• 1_close - 與關閉編輯器相關的命令。
• 3_preview - 與固定編輯器相關的命令。

編輯器標題功能表具有下列預設群組：

• navigation - 與導覽相關的命令。
• 1_run - 與執行和偵錯編輯器相關的命令。
• 1_diff - 與使用差異編輯器相關的命令。
• 3_open - 與開啟編輯器相關的命令。
• 5_close - 與關閉編輯器相關的命令。

navigation 和 1_run 顯示在主要編輯器標題區域中。其他群組則顯示在次要區域（在 ... 功能表下方）。

終端機標籤頁操作功能表具有下列預設群組：

• 1_create - 與建立終端機相關的命令。
• 3_run - 與在終端機中執行某些項目相關的命令。
• 5_manage - 與管理終端機相關的命令。
• 7_configure - 與終端機組態相關的命令。

終端機操作功能表具有下列預設群組：

• 1_create - 與建立終端機相關的命令。
• 3_edit - 與操作文字、選取範圍或剪貼簿相關的命令。
• 5_clear - 與清除終端機相關的命令。
• 7_kill - 與關閉/強制終止終端機相關的命令。
• 9_config - 與終端機組態相關的命令。

時間軸檢視項目操作功能表具有下列預設群組：

• inline - 重要或經常使用的時間軸項目命令。呈現為工具列。
• 1_actions - 與處理時間軸項目相關的命令。
• 5_copy - 與複製時間軸項目資訊相關的命令。

擴充功能檢視操作功能表具有下列預設群組：

• 1_copy - 與複製擴充功能資訊相關的命令。
• 2_configure - 與組態擴充功能相關的命令。

群組內部的排序

群組內部的順序取決於標題或 order 屬性。功能表項目的群組內順序是透過在群組識別碼後面附加 @<number> 來指定的，如下所示

{
  "editor/title": [
    {
      "when": "editorHasSelection",
      "command": "extension.Command",
      "group": "myGroup@1"
    }
  ]
}

contributes.problemMatchers

貢獻問題比對器模式。這些貢獻同時適用於輸出面板執行器與終端機執行器。以下是在擴充功能中為 gcc 編譯器貢獻問題比對器的範例

{
  "contributes": {
    "problemMatchers": [
      {
        "name": "gcc",
        "owner": "cpp",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "pattern": {
          "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5
        }
      }
    ]
  }
}

現在可以在 tasks.json 檔案中透過名稱參考 $gcc 來使用此問題比對器。範例看起來像這樣

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "gcc",
      "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"],
      "problemMatcher": "$gcc"
    }
  ]
}

另請參閱：定義問題比對器

contributes.problemPatterns

貢獻可用於問題比對器中的具名問題模式（見上方）。

contributes.productIconThemes

為 VS Code 貢獻產品圖示佈景主題。產品圖示是 VS Code 中使用的所有圖示，但檔案圖示與來自擴充功能的貢獻圖示除外。

您必須指定 id（用於設定中）、label（標籤）以及圖示定義檔案的路徑。

產品圖示佈景主題範例

{
  "contributes": {
    "productIconThemes": [
      {
        "id": "elegant",
        "label": "Elegant Icon Theme",
        "path": "./producticons/elegant-product-icon-theme.json"
      }
    ]
  }
}

請參閱關於如何建立產品圖示佈景主題的產品圖示佈景主題指南。

contributes.resourceLabelFormatters

貢獻資源標籤格式器，指定如何在工作台的任何地方顯示 URI。例如，以下是擴充功能如何為具有 remotehub 配置的 URI 貢獻格式器

{
  "contributes": {
    "resourceLabelFormatters": [
      {
        "scheme": "remotehub",
        "formatting": {
          "label": "${path}",
          "separator": "/",
          "workspaceSuffix": "GitHub"
        }
      }
    ]
  }
}

這表示所有具有 remotehub 配置的 URI 在呈現時，將只會顯示 URI 的 path 區段且分隔符號為 /。具有 remotehub URI 的工作區在其標籤中將會具有 GitHub 字尾。

contributes.semanticTokenModifiers

貢獻可透過佈景主題規則進行突顯的新語意標記修飾詞。

{
  "contributes": {
    "semanticTokenModifiers": [
      {
        "id": "native",
        "description": "Annotates a symbol that is implemented natively"
      }
    ]
  }
}

請參閱語意突顯指南以深入了解語意突顯。

contributes.semanticTokenScopes

貢獻語意標記類型與修飾詞和範圍之間的對應關係，作為後備方案或支援語言特定佈景主題。

{
  "contributes": {
    "semanticTokenScopes": [
      {
        "language": "typescript",
        "scopes": {
          "property.readonly": ["variable.other.constant.property.ts"]
        }
      }
    ]
  }
}

請參閱語意突顯指南以深入了解語意突顯。

contributes.semanticTokenTypes

貢獻可透過佈景主題規則進行突顯的新語意標記類型。

{
  "contributes": {
    "semanticTokenTypes": [
      {
        "id": "templateType",
        "superType": "type",
        "description": "A template type."
      }
    ]
  }
}

請參閱語意突顯指南以深入了解語意突顯。

contributes.snippets

為特定語言貢獻程式碼片段。language 屬性是語言識別碼，而 path 是程式碼片段檔案的相對路徑，該檔案在 VS Code 程式碼片段格式中定義了程式碼片段。

以下範例顯示為 Go 語言新增程式碼片段。

{
  "contributes": {
    "snippets": [
      {
        "language": "go",
        "path": "./snippets/go.json"
      }
    ]
  }
}

contributes.submenus

貢獻一個子功能表作為預留位置，可以在上面貢獻功能表項目。子功能表需要一個 label 才能顯示在父功能表中。

除了標題之外，命令還可以定義當 VS Code 顯示在編輯器標題功能表列中時要顯示的圖示。

子功能表範例

{
  "contributes": {
    "submenus": [
      {
        "id": "git.commit",
        "label": "Commit"
      }
    ]
  }
}

contributes.taskDefinitions

貢獻並定義物件常值結構，以允許在系統中唯一識別所貢獻的任務。任務定義至少具有一個 type 屬性，但它通常會定義額外的屬性。例如，代表 package.json 檔案中指令碼之任務的任務定義看起來像這樣

{
  "taskDefinitions": [
    {
      "type": "npm",
      "required": ["script"],
      "properties": {
        "script": {
          "type": "string",
          "description": "The script to execute"
        },
        "path": {
          "type": "string",
          "description": "The path to the package.json file. If omitted the package.json in the root of the workspace folder is used."
        }
      }
    }
  ]
}

任務定義是使用 JSON schema 語法來針對 required 和 properties 屬性進行定義。type 屬性定義了任務類型。如果上述範例

• "type": "npm" 將任務定義與 npm 任務關聯
• "required": [ "script" ] 將 script 屬性定義為強制填寫。path 屬性則是選用的。
• "properties" : { ... } 定義了額外的屬性及其類型。

當擴充功能實際建立 Task 時，它需要傳遞一個符合在 package.json 檔案中所貢獻之任務定義的 TaskDefinition。對於 npm 範例，針對 package.json 檔案內測試指令碼的任務建立看起來像這樣

let task = new vscode.Task({ type: 'npm', script: 'test' }, ....);

contributes.terminal

為 VS Code 貢獻終端機設定檔，允許擴充功能處理設定檔的建立。定義後，該設定檔應會在建立終端機設定檔時出現

{
  "activationEvents": ["onTerminalProfile:my-ext.terminal-profile"],
  "contributes": {
    "terminal": {
      "profiles": [
        {
          "title": "Profile from extension",
          "id": "my-ext.terminal-profile"
        }
      ]
    }
  }
}

定義後，該設定檔將會顯示在終端機設定檔挑選器中。當啟用時，透過傳回終端機選項來處理設定檔的建立

vscode.window.registerTerminalProfileProvider('my-ext.terminal-profile', {
  provideTerminalProfile(
    token: vscode.CancellationToken
  ): vscode.ProviderResult<vscode.TerminalOptions | vscode.ExtensionTerminalOptions> {
    return { name: 'Profile from extension', shellPath: 'bash' };
  }
});

contributes.themes

為 VS Code 貢獻色彩佈景主題，定義工作台色彩以及編輯器中語意標記的樣式。

您必須指定標籤、佈景主題是深色佈景主題還是淺色佈景主題（以便其餘的 VS Code 變更以配合您的佈景主題），以及檔案的路徑（JSON 格式）。

佈景主題範例

{
  "contributes": {
    "themes": [
      {
        "label": "Monokai",
        "uiTheme": "vs-dark",
        "path": "./themes/monokai-color-theme.json"
      }
    ]
  }
}

請參閱關於如何建立色彩佈景主題的色彩佈景主題指南。

contributes.typescriptServerPlugins

貢獻 TypeScript 伺服器外掛程式，以增強 VS Code 對 JavaScript 和 TypeScript 的支援

{
  "contributes": {
    "typescriptServerPlugins": [
      {
        "name": "typescript-styled-plugin"
      }
    ]
  }
}

上述範例擴充功能貢獻了 typescript-styled-plugin，它為 JavaScript 和 TypeScript 新增了 styled-component 智慧感知。此外掛程式將從擴充功能載入，且必須在擴充功能中作為一般的 NPM dependency 安裝

{
  "dependencies": {
    "typescript-styled-plugin": "*"
  }
}

當使用者使用 VS Code 版本的 TypeScript 時，會為所有 JavaScript 和 TypeScript 檔案載入 TypeScript 伺服器外掛程式。如果使用者使用的是工作區版本的 TypeScript，它們將不會被啟用，除非外掛程式明確設定了 "enableForWorkspaceTypeScriptVersions": true。

{
  "contributes": {
    "typescriptServerPlugins": [
      {
        "name": "typescript-styled-plugin",
        "enableForWorkspaceTypeScriptVersions": true
      }
    ]
  }
}

外掛程式組態

擴充功能可以透過 VS Code 內建 TypeScript 擴充功能所提供的 API，將組態資料傳送至所貢獻的 TypeScript 外掛程式

// In your VS Code extension

export async function activate(context: vscode.ExtensionContext) {
  // Get the TS extension
  const tsExtension = vscode.extensions.getExtension('vscode.typescript-language-features');
  if (!tsExtension) {
    return;
  }

  await tsExtension.activate();

  // Get the API from the TS extension
  if (!tsExtension.exports || !tsExtension.exports.getAPI) {
    return;
  }

  const api = tsExtension.exports.getAPI(0);
  if (!api) {
    return;
  }

  // Configure the 'my-typescript-plugin-id' plugin
  api.configurePlugin('my-typescript-plugin-id', {
    someValue: process.env['SOME_VALUE']
  });
}

TypeScript 伺服器外掛程式透過 onConfigurationChanged 方法接收組態資料

// In your TypeScript plugin

import * as ts_module from 'typescript/lib/tsserverlibrary';

export = function init({ typescript }: { typescript: typeof ts_module }) {
  return {
    create(info: ts.server.PluginCreateInfo) {
      // Create new language service
    },
    onConfigurationChanged(config: any) {
      // Receive configuration changes sent from VS Code
    }
  };
};

此 API 允許 VS Code 擴充功能將 VS Code 設定與 TypeScript 伺服器外掛程式同步，或動態變更外掛程式的行為。請查看 TypeScript TSLint plugin 與 lit-html 擴充功能，以了解如何在實務中使用此 API。

contributes.views

為 VS Code 貢獻檢視。您必須指定檢視的識別碼與名稱。您可以貢獻至下列檢視容器：

• explorer：活動列中的「檔案總管」檢視容器
• scm：活動列中的「原始碼控制管理 (SCM)」檢視容器
• debug：活動列中的「執行與偵錯」檢視容器
• test：活動列中的「測試」檢視容器
• 由擴充功能貢獻的自訂檢視容器。

當使用者開啟檢視時，VS Code 將會發出啟用事件 onView:${viewId}（下方範例為 onView:nodeDependencies）。您也可以透過提供 when 內容值來控制檢視的可見性。當無法顯示標題時（例如當檢視被拖曳至活動列時），將會使用指定的 icon。當檢視被移出其預設檢視容器且需要額外內容時，會使用 contextualTitle。

{
  "contributes": {
    "views": {
      "explorer": [
        {
          "id": "nodeDependencies",
          "name": "Node Dependencies",
          "when": "workspaceHasPackageJSON",
          "icon": "media/dep.svg",
          "contextualTitle": "Package Explorer"
        }
      ]
    }
  }
}

檢視的內容可以用兩種方式填入：

• 透過 createTreeView API 提供 資料提供者搭配 TreeView，或直接透過 registerTreeDataProvider API 註冊 資料提供者來填入資料。TreeView 非常適合用於顯示階層式資料與清單。請參閱 tree-view-sample。
• 透過使用 registerWebviewViewProvider 註冊 提供者來搭配 WebviewView。Webview 檢視允許在檢視中呈現任意 HTML。請參閱 webview 檢視擴充功能範例以取得更多詳細資料。

contributes.viewsContainers

貢獻一個檢視容器，可以在其中貢獻自訂檢視。您必須為檢視容器指定識別碼、標題和圖示。目前，您可以將它們貢獻至活動列（activitybar）與面板（panel）。以下範例顯示如何將 Package Explorer 檢視容器貢獻至活動列以及如何將檢視貢獻至其中。

{
  "contributes": {
    "viewsContainers": {
      "activitybar": [
        {
          "id": "package-explorer",
          "title": "Package Explorer",
          "icon": "resources/package-explorer.svg"
        }
      ]
    },
    "views": {
      "package-explorer": [
        {
          "id": "package-dependencies",
          "name": "Dependencies"
        },
        {
          "id": "package-outline",
          "name": "Outline"
        }
      ]
    }
  }
}

圖示規格

• 大小：圖示應為 24x24 並置中。

• 顏色：圖示應使用單一顏色。

• 格式：建議圖示採用 SVG，不過接受任何圖片檔案類型。

• 狀態：所有圖示都繼承下列狀態樣式：

  狀態	不透明度
  預設值	60%
  懸停	100%
  作用中	100%

contributes.viewsWelcome

為自訂檢視貢獻歡迎內容。歡迎內容僅適用於空的樹狀檢視。如果樹狀結構沒有子項目且沒有 TreeView.message，則該檢視會被視為空的。按照慣例，任何獨佔一行的命令連結都會顯示為按鈕。您可以使用 view 屬性指定歡迎內容應套用的檢視。歡迎內容的可見性可以使用 when 內容值來控制。要顯示為歡迎內容的文字是透過 contents 屬性來設定的。

{
  "contributes": {
    "viewsWelcome": [
      {
        "view": "scm",
        "contents": "In order to use git features, you can open a folder containing a git repository or clone from a URL.\n[Open Folder](command:vscode.openFolder)\n[Clone Repository](command:git.clone)\nTo learn more about how to use git and source control in VS Code [read our docs](https://aka.ms/vscode-scm).",
        "when": "config.git.enabled && git.state == initialized && workbenchState == empty"
      }
    ]
  }
}

可以為一個檢視貢獻多個歡迎內容項目。當發生這種情況時，來自 VS Code 核心的內容會排在第一位，接著是來自內建擴充功能的內容，然後是來自所有其他擴充功能的內容。

contributes.walkthroughs

範例擴充功能

貢獻逐步解說以顯示在「開始使用」頁面上。逐步解說會在安裝您的擴充功能時自動開啟，並提供一種便捷的方式向使用者介紹您的擴充功能功能。

逐步解說由標題、描述、識別碼和一系列步驟組成。此外，可以設定 when 條件，根據內容金鑰來隱藏或顯示逐步解說。例如，用於說明 Linux 平台設定的逐步解說可以給予 when: "isLinux"，使其僅在 Linux 機器上出現。

逐步解說中的每個步驟都有標題、描述、識別碼和媒體元素（圖片或 Markdown 內容），以及一組可選的事件，這些事件會導致步驟被勾選（如下方範例所示）。步驟描述為 Markdown 內容，並支援 **粗體**、__底線__ 和 ``程式碼`` 呈現，以及連結。與逐步解說類似，可以為步驟給予 when 條件，以根據內容金鑰隱藏或顯示它們。

鑑於 SVG 具有縮放能力以及對 VS Code 佈景主題顏色的支援，因此建議圖片採用 SVG。使用 Visual Studio Code Color Mapper Figma 外掛程式，以便在 SVG 中輕鬆參考佈景主題顏色。

{
  "contributes": {
    "walkthroughs": [
      {
        "id": "sample",
        "title": "Sample",
        "description": "A sample walkthrough",
        "steps": [
          {
            "id": "runcommand",
            "title": "Run Command",
            "description": "This step will run a command and check off once it has been run.\n[Run Command](command:getting-started-sample.runCommand)",
            "media": { "image": "media/image.png", "altText": "Empty image" },
            "completionEvents": ["onCommand:getting-started-sample.runCommand"]
          },
          {
            "id": "changesetting",
            "title": "Change Setting",
            "description": "This step will change a setting and check off when the setting has changed\n[Change Setting](command:getting-started-sample.changeSetting)",
            "media": { "markdown": "media/markdown.md" },
            "completionEvents": ["onSettingChanged:getting-started-sample.sampleSetting"]
          }
        ]
      }
    ]
  }
}

完成事件

根據預設，如果未提供任何 completionEvents 事件，當按一下其任何按鈕時，或者如果步驟沒有按鈕，則在開啟時，該步驟將會被勾選。如果需要更精細的控制，可以提供 completionEvents 清單。

可用的完成事件包括：

• onCommand:myCommand.id：執行命令時勾選步驟。
• onSettingChanged:mySetting.id：修改給定設定後勾選步驟。
• onContext:contextKeyExpression：當內容金鑰運算式評估為真時勾選步驟。
• extensionInstalled:myExt.id：如果安裝了給定的擴充功能，則勾選步驟。
• onView:myView.id：一旦給定的檢視變得可見，即勾選步驟。
• onLink:https://...：透過逐步解說開啟給定連結後，即勾選步驟。

一旦步驟被勾選，它將保持勾選狀態，直到使用者明確取消勾選該步驟或重設其進度（透過開始使用: 重設進度命令）。