擴充功能資訊清單

每個 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. 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 的資源區段下。

{
  "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 上會群組在一起，這有助於改善篩選和探索。

注意：僅使用對您的擴充功能有意義的值。允許的值為 [程式語言, 程式碼片段, 程式碼檢查器, 佈景主題, 偵錯工具, 格式器, 鍵盤對應, SCM 提供者, 其他, 擴充功能包, 語言包, 資料科學, 機器學習, 視覺化, 筆記本, 教育, 測試]。對於一般語言功能（例如語法突顯和程式碼完成），請使用 程式語言。語言包 類別保留給顯示語言擴充功能（例如，本地化的保加利亞語）。

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

核准的徽章

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

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

• api.bintray.com
• api.travis-ci.com
• api.travis-ci.org
• app.fossa.io
• badge.buildkite.com
• badge.fury.io
• badge.waffle.io
• badgen.net
• badges.frapsoft.com
• badges.gitter.im
• badges.greenkeeper.io
• cdn.travis-ci.com
• cdn.travis-ci.org
• 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
• gemnasium.com
• 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
• travis-ci.org
• visualstudio.com
• vsmarketplacebadges.dev
• www.versioneye.com

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

如果您有其他想要使用的徽章，請開啟 GitHub issue，我們很樂意查看。

合併擴充功能貢獻

yo code 產生器可讓您輕鬆封裝 TextMate 佈景主題、色彩化器和程式碼片段，並建立新的擴充功能。當產生器執行時，它會為每個選項建立一個完整的獨立擴充功能包。但是，擁有一個結合多個貢獻的單一擴充功能通常更方便。例如，如果您要新增對新語言的支援，您會希望為使用者提供包含色彩化的語言定義，以及程式碼片段，甚至可能還包括偵錯支援。

若要合併擴充功能貢獻，請編輯現有的擴充功能資訊清單 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 屬性現在同時包含 程式語言 和 程式碼片段，以便在 Marketplace 上輕鬆探索和篩選。

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

擴充功能包

您可以將個別的擴充功能捆綁在擴充功能包中。擴充功能包是一組將一起安裝的擴充功能。這讓您可以輕鬆地與其他使用者分享您最愛的擴充功能，或為特定情境（例如 PHP 開發）建立一組擴充功能，以協助 PHP 開發人員快速開始使用 VS Code。

擴充功能包使用 package.json 檔案內的 extensionPack 屬性來捆綁其他擴充功能。

例如，以下是一個適用於 PHP 的擴充功能包，其中包含偵錯工具和語言服務

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

安裝擴充功能包時，VS Code 現在也會安裝其擴充功能相依性。

擴充功能包應分類在 擴充功能包 Marketplace 類別中

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

若要建立擴充功能包，您可以使用 yo code Yeoman 產生器，並選擇新增擴充功能包選項。有一個選項可以使用您目前在 VS Code 執行個體中安裝的擴充功能集來初始化包。透過這種方式，您可以輕鬆地使用您最愛的擴充功能建立擴充功能包，將其發佈到 Marketplace，並與其他人分享。

擴充功能包不應與其捆綁的擴充功能有任何功能性相依性，且捆綁的擴充功能應可獨立於包進行管理。如果擴充功能依賴於另一個擴充功能，則應使用 extensionDependencies 屬性宣告該相依性。

擴充功能解除安裝勾點

如果您的擴充功能在從 VS Code 解除安裝時需要完成一些清理工作，您可以在擴充功能的 package.json 中 scripts 區段下註冊一個 node 腳本到解除安裝勾點 vscode:uninstall。

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

此腳本會在擴充功能從 VS Code 完全解除安裝時執行，也就是在擴充功能解除安裝後重新啟動 VS Code（關閉並啟動）時執行。

注意：僅支援 Node.js 腳本。

實用的 Node 模組

npmjs 上提供多個 Node.js 模組，可協助撰寫 VS Code 擴充功能。您可以將這些模組包含在擴充功能的 dependencies 區段中。

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

下一步

若要深入了解 VS Code 擴充性模型，請嘗試以下主題

• 貢獻點 - VS Code 貢獻點參考
• 啟用事件 - VS Code 啟用事件參考
• 擴充功能 Marketplace - 閱讀更多關於 VS Code 擴充功能 Marketplace 的資訊