擴充功能能力概覽

Visual Studio Code 提供了多種讓擴充功能擴充其能力的方式。有時很難找到正確的貢獻點 (Contribution Points) 和 VS Code API 來使用。本主題將擴充功能能力分為幾個類別，每個類別描述了：

• 您的擴充功能可以使用的某些功能
• 連結至使用這些功能的詳細主題
• 一些擴充功能點子

然而，我們也對擴充功能施加了限制，以確保 VS Code 的穩定性和效能。例如，擴充功能無法存取 VS Code UI 的 DOM。

通用功能

通用能力 (Common Capabilities) 是您可以在任何擴充功能中使用的核心功能組件。

這些能力包括：

• 註冊指令、設定、按鍵繫結或右鍵選單項目。
• 儲存工作區或全域資料。
• 顯示通知訊息。
• 使用 Quick Pick 來收集使用者輸入。
• 開啟系統檔案選擇器，讓使用者選擇檔案或資料夾。
• 使用 Progress API 來指示長時間執行的操作。

主題設定

佈景主題 (Theming) 可控制 VS Code 的外觀，包括編輯器中原始程式碼的顏色以及 VS Code UI 的顏色。如果您曾想過讓 VS Code 呈現不同深淺的綠色，看起來就像在寫《駭客任務》(Matrix) 程式碼，或者只是想創造一個極簡的灰階工作區，那麼佈景主題就非常適合您。

擴充功能點子

• 變更原始程式碼的顏色。
• 變更 VS Code UI 的顏色。
• 將現有的 TextMate 佈景主題移植到 VS Code。
• 新增自訂檔案圖示。

宣告式語言功能

宣告式語言功能 (Declarative Language Features) 為程式語言新增基本的文字編輯支援，例如括號比對、自動縮排和語法突顯。這是以宣告方式完成的，無需撰寫任何程式碼。若要使用更進階的語言功能（如 IntelliSense 或除錯），請參閱程式化語言功能 (Programmatic Language Features)。

擴充功能點子

• 將常用的 JavaScript 程式碼片段 (snippets) 打包成擴充功能。
• 向 VS Code 宣告一種新的程式語言。
• 為程式語言新增或替換語法。
• 透過語法注入 (grammar injections) 擴充現有的語法。
• 將現有的 TextMate 語法移植到 VS Code。

程式化語言功能

程式化語言功能 (Programmatic Language Features) 新增了豐富的程式語言支援，例如懸浮提示 (Hovers)、前往定義 (Go to Definition)、診斷錯誤、IntelliSense 和 CodeLens。這些語言功能是透過 vscode.languages.* API 暴露出來的。擴充功能可以直接使用這些 API，或者撰寫語言伺服器 (Language Server)，並使用 VS Code 語言伺服器程式庫將其適配到 VS Code。

雖然我們提供了語言功能及其預期用途的列表，但並沒有什麼可以阻止您發揮創意來使用這些 API。例如，CodeLens 和懸浮提示是呈現內嵌附加資訊的好方法，而診斷錯誤可以用來突顯拼字或程式碼風格錯誤。

擴充功能點子

• 新增可顯示 API 使用範例的懸浮提示。
• 使用診斷功能報告原始程式碼中的拼字或 Lint 錯誤。
• 為 HTML 註冊新的程式碼格式化工具。
• 提供豐富且具備內容感知能力 (context-aware) 的 IntelliSense。
• 為語言新增程式碼摺疊、麵包屑導覽 (breadcrumbs) 和大綱 (outline) 支援。

工作台 (Workbench) 擴充功能

工作台擴充功能 (Workbench Extensions) 可擴充 VS Code 工作台 UI。您可以為檔案總管新增右鍵操作，甚至可以使用 VS Code 的 TreeView API 建構自訂的總管。如果您的擴充功能需要完全自訂的使用者介面，請使用 Webview API，透過標準的 HTML、CSS 和 JavaScript 建構您自己的文件預覽或 UI。

擴充功能點子

• 為檔案總管新增自訂右鍵選單動作。
• 在側邊欄 (Side Bar) 中建立新的互動式 TreeView。
• 定義新的活動列 (Activity Bar) 檢視。
• 在狀態列 (Status Bar) 中顯示新資訊。
• 使用 WebView API 轉譯自訂內容。
• 貢獻原始碼控制 (Source Control) 提供者。

偵錯

您可以透過撰寫 除錯器擴充功能 (Debugger Extensions)，將 VS Code 的除錯 UI 連接到特定的除錯器或執行階段，從而利用 VS Code 的除錯 (Debugging) 功能。

擴充功能點子

• 透過貢獻 除錯轉接器實作 (Debug Adapter implementation)，將 VS Code 的除錯 UI 連接到除錯器或執行階段。
• 指定除錯器擴充功能所支援的語言。
• 為除錯器使用的除錯設定屬性提供豐富的 IntelliSense 和懸浮提示資訊。
• 提供除錯設定的程式碼片段 (snippets)。

另一方面，VS Code 也提供了一套 除錯擴充功能 API，您可以使用它在任何 VS Code 除錯器之上實作與除錯相關的功能，以自動化使用者的除錯體驗。

擴充功能點子

• 基於動態建立的除錯設定啟動除錯工作階段。
• 追蹤除錯工作階段的生命週期。
• 以程式設計方式建立和管理中斷點。

UX 指南

為了協助您的擴充功能與 VS Code 使用者介面無縫整合，請參閱 UX 指南，您將在其中學習建立擴充功能 UI 的最佳實踐，以及遵循偏好的 VS Code 工作流程之慣例。

限制

我們對擴充功能施加了某些限制。以下是這些限制及其目的。

無法存取 DOM

擴充功能無法存取 VS Code UI 的 DOM。您無法編寫一個對 VS Code 套用自訂 CSS 或將 HTML 元素新增至 VS Code UI 的擴充功能。

在 VS Code，我們不斷嘗試最佳化基礎 Web 技術的使用，以提供一個始終可用且高度響應的編輯器，並且隨著這些技術和我們的產品發展，我們將繼續調整對 DOM 的使用。為了確保擴充功能不會干擾 VS Code 的穩定性和效能，並確保我們能夠在不破壞現有擴充功能的情況下繼續改進 VS Code 的 DOM，我們在 擴充功能主機 (Extension Host) 進程中執行擴充功能，並防止直接存取 DOM。

沒有自訂樣式表

由使用者或擴充功能提供的自訂樣式表會干擾 DOM 結構和類別名稱。這些內容並未正式記錄，因為我們將其視為內部內容。為了發展、重構或改進 VS Code，我們需要自由地變更使用者介面。對 DOM 的任何變更都可能導致現有的自訂樣式表失效，這會讓樣式表提供者感到沮喪，並因樣式表損壞導致 UI 故障，從而帶來糟糕的使用者體驗。

相反地，VS Code 旨在提供一套設計完善且支援 UI 自訂的擴充功能 API。該 API 已有記錄、隨附工具與範例，並在 VS Code 未來的所有版本中保持穩定。