延伸模組資訊清單

每個 Visual Studio Code 擴充功能都需要在擴充功能目錄結構的根目錄中包含一個 package.json 資訊清單檔案。

欄位

另請參閱 npm 的 package.json 參考資料。

範例

以下是一個完整的 package.json

{
  "name": "wordcount",
  "displayName": "Word Count",
  "version": "0.1.0",
  "publisher": "ms-vscode",
  "description": "Markdown Word Count Example - reports out the number of words in a Markdown file.",
  "author": {
    "name": "sean"
  },
  "categories": ["Other"],
  "icon": "images/icon.png",
  "galleryBanner": {
    "color": "#C80000",
    "theme": "dark"
  },
  "pricing": "Free",
  "activationEvents": ["onLanguage:markdown"],
  "engines": {
    "vscode": "^1.0.0"
  },
  "main": "./out/extension",
  "scripts": {
    "vscode:prepublish": "node ./node_modules/vscode/bin/compile",
    "compile": "node ./node_modules/vscode/bin/compile -watch -p ./"
  },
  "devDependencies": {
    "@types/vscode": "^0.10.x",
    "typescript": "^1.6.2"
  },
  "license": "SEE LICENSE IN LICENSE.txt",
  "bugs": {
    "url": "https://github.com/microsoft/vscode-wordcount/issues",
    "email": "sean@contoso.com"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/microsoft/vscode-wordcount.git"
  },
  "homepage": "https://github.com/microsoft/vscode-wordcount/blob/main/README.md"
}

Marketplace 展示技巧

以下是一些技巧與建議，可讓您的擴充功能在 VS Code Marketplace 上顯示時更為美觀。

請務必使用最新的 vsce，執行 npm install -g @vscode/vsce 以確保您已安裝。

在您的擴充功能根目錄中準備一個 README.md Markdown 檔案，我們將會把其內容包含在擴充功能詳細資訊的主體中（在 Marketplace 上）。您可以在 README.md 中提供相對路徑的圖片連結。

以下是一些範例

1. 字數統計 (Word Count)
2. Markdown 工具 (MD Tools)

提供良好的顯示名稱與描述。這對於 Marketplace 和產品顯示非常重要。這些字串也會用於 VS Code 中的文字搜尋，因此設定相關的關鍵字非常有幫助。

    "displayName": "Word Count",
    "description": "Markdown Word Count Example - reports out the number of words in a Markdown file.",

圖示與對比鮮明的橫幅顏色在 Marketplace 頁面頁首看起來非常出色。theme 屬性是指橫幅中使用的字型顏色 - dark 或 light。

{
  "icon": "images/icon.png",
  "galleryBanner": {
    "color": "#C80000",
    "theme": "dark"
  }
}

有幾個選擇性的連結（bugs、homepage、repository）您可以設定，這些連結會顯示在 Marketplace 的 資源 (Resources) 區塊下。

{
  "license": "SEE LICENSE IN LICENSE.txt",
  "homepage": "https://github.com/microsoft/vscode-wordcount/blob/main/README.md",
  "bugs": {
    "url": "https://github.com/microsoft/vscode-wordcount/issues",
    "email": "sean@contoso.com"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/microsoft/vscode-wordcount.git"
  }
}

為您的擴充功能設定一個 category。同一 category 中的擴充功能會在 Marketplace 上歸類在一起，這有助於篩選與探索。

注意：僅使用對您的擴充功能有意義的值。允許的值為 [Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs, Data Science, Machine Learning, Visualization, Notebooks, Education, Testing]。對於語法高亮和程式碼補全等通用語言功能，請使用 Programming Languages。Language Packs 類別保留給顯示語言擴充功能使用（例如：保加利亞語本地化）。

{
  "categories": ["Linters", "Programming Languages", "Other"]
}

已核准的徽章

基於安全考量，我們僅允許來自受信任服務的徽章。

我們允許來自以下 URL 前綴的徽章：

• api.travis-ci.com
• app.fossa.io
• badge.buildkite.com
• badge.fury.io
• badgen.net
• badges.frapsoft.com
• badges.gitter.im
• cdn.travis-ci.com
• ci.appveyor.com
• circleci.com
• cla.opensource.microsoft.com
• codacy.com
• codeclimate.com
• codecov.io
• coveralls.io
• david-dm.org
• deepscan.io
• dev.azure.com
• docs.rs
• flat.badgen.net
• github.com (僅限 Workflows)
• gitlab.com
• godoc.org
• goreportcard.com
• img.shields.io
• isitmaintained.com
• marketplace.visualstudio.com
• nodesecurity.io
• opencollective.com
• snyk.io
• travis-ci.com
• visualstudio.com
• vsmarketplacebadges.dev

注意：請將 vsmarketplacebadge.apphb.com 徽章替換為 vsmarketplacebadges.dev 徽章。

如果您有其他想要使用的徽章，請在 GitHub 開啟一個 Issue，我們很樂意評估。

結合擴充功能貢獻

yo code 產生器可讓您輕鬆封裝 TextMate 主題、著色器 (colorizers) 和程式碼片段，並建立新的擴充功能。執行產生器時，它會為每個選項建立一個完整的獨立擴充功能套件。然而，通常將多個貢獻合併在一個擴充功能中會更方便。例如，如果您要新增對新語言的支援，您會希望同時提供使用者帶有著色功能的語言定義、程式碼片段，甚至可能是偵錯支援。

若要合併擴充功能貢獻，請編輯現有的擴充功能資訊清單 package.json 並新增新的貢獻與相關檔案。

以下是一個包含 LaTex 語言定義（語言識別碼與副檔名）、著色（grammars）與程式碼片段的擴充功能資訊清單。

{
  "name": "language-latex",
  "description": "LaTex Language Support",
  "version": "0.0.1",
  "publisher": "someone",
  "engines": {
    "vscode": "0.10.x"
  },
  "categories": ["Programming Languages", "Snippets"],
  "contributes": {
    "languages": [
      {
        "id": "latex",
        "aliases": ["LaTeX", "latex"],
        "extensions": [".tex"]
      }
    ],
    "grammars": [
      {
        "language": "latex",
        "scopeName": "text.tex.latex",
        "path": "./syntaxes/latex.tmLanguage.json"
      }
    ],
    "snippets": [
      {
        "language": "latex",
        "path": "./snippets/snippets.json"
      }
    ]
  }
}

請注意，擴充功能資訊清單的 categories 屬性現在同時包含了 Programming Languages 和 Snippets，以便在 Marketplace 上進行輕鬆的探索與篩選。

提示：請確保您合併的貢獻使用相同的識別碼。在上述範例中，所有三個貢獻都使用 "latex" 作為語言識別碼。這讓 VS Code 知道該著色器 (grammars) 和程式碼片段是針對 LaTeX 語言的，並且會在編輯 LaTeX 檔案時啟用。

延伸模組套件

您可以將單獨的擴充功能打包在一起成為 擴充功能套件 (Extension Packs)。擴充功能套件是一組可以一起安裝的擴充功能集合。這能讓您輕鬆與其他使用者分享您喜愛的擴充功能，或為特定情境（例如 PHP 開發）建立一組擴充功能，幫助 PHP 開發者快速上手 VS Code。

擴充功能套件透過 package.json 檔案內的 extensionPack 屬性來綑綁其他擴充功能。

例如，以下是一個包含偵錯器與語言服務的 PHP 擴充功能套件。

{
  "extensionPack": ["xdebug.php-debug", "zobo.php-intellisense"]
}

安裝擴充功能套件時，VS Code 現在也會安裝其擴充功能相依項。

擴充功能套件應分類在 Marketplace 的 Extension Packs 類別中。

{
  "categories": ["Extension Packs"]
}

若要建立擴充功能套件，您可以使用 yo code Yeoman 產生器並選擇 New Extension Pack 選項。您可以選擇以您目前 VS Code 執行個體中已安裝的擴充功能集合作為套件的基礎。透過這種方式，您可以輕鬆建立包含您最愛擴充功能的套件，將其發布到 Marketplace 並與他人分享。

擴充功能套件不應與其綑綁的擴充功能有任何功能上的相依關係，且綑綁的擴充功能應能獨立於套件之外進行管理。如果一個擴充功能對另一個擴充功能有相依性，該相依性應使用 extensionDependencies 屬性進行宣告。

擴充功能解除安裝 Hook

如果您的擴充功能在從 VS Code 解除安裝時需要進行清理作業，您可以在擴充功能的 package.json 中的 scripts 區塊下，為解除安裝 Hook vscode:uninstall 註冊一個 node 指令碼。

{
  "scripts": {
    "vscode:uninstall": "node ./out/src/lifecycle"
  }
}

當擴充功能從 VS Code 完全解除安裝時（即解除安裝後重新啟動 VS Code 時），該指令碼就會執行。

注意：僅支援 Node.js 指令碼。

實用的 Node 模組

npmjs 上有幾個 Node.js 模組可協助編寫 VS Code 擴充功能。您可以將這些模組包含在擴充功能的 dependencies 區塊中。

• vscode-nls - 支援外部化 (Externalization) 與在地化 (Localization)。
• vscode-uri - VS Code 及其擴充功能使用的 URI 實作。
• jsonc-parser - 用於處理帶有或不帶註解之 JSON 的掃描器與容錯剖析器。
• request-light - 支援 Proxy 的輕量級 Node.js 請求函式庫。
• vscode-extension-telemetry - 適用於 VS Code 擴充功能的一致性遙測報告。
• vscode-languageclient - 輕鬆整合符合 語言伺服器協定 (Language Server Protocol) 的語言伺服器。

後續步驟

若要進一步了解 VS Code 的擴充性模型，請嘗試閱讀這些主題：

• 貢獻點 (Contribution Points) - VS Code 貢獻點參考。
• 啟用事件 (Activation Events) - VS Code 啟用事件參考資料
• 擴充功能 Marketplace - 閱讀更多關於 VS Code 擴充功能 Marketplace 的資訊