扩展清单

每个 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"
}

插件市场展示建议

以下是一些建议和推荐，旨在使您的扩展在 VS Code 插件市场上展示效果更好。

始终使用最新版本的 vsce，因此请执行 npm install -g @vscode/vsce 以确保版本更新。

在扩展的根文件夹中准备一个 README.md Markdown 文件，我们将把其内容包含在扩展详情的正文中（在插件市场上）。您可以在 README.md 中提供相对路径的图片链接。

以下是一些示例

1. 字数统计
2. MD 工具

提供一个好的显示名称和描述。这对于插件市场和产品展示非常重要。这些字符串也用于 VS Code 中的文本搜索，拥有相关的关键字将大有裨益。

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

图标和对比鲜明的横幅颜色在插件市场页面头部看起来非常棒。theme 属性是指横幅中要使用的字体颜色 - dark 或 light。

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

您可以设置几个可选链接（bugs、homepage、repository），它们将显示在插件市场的资源（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 下的扩展在插件市场上会被归类在一起，从而改善过滤和发现效果。

注意：仅使用对您的扩展有意义的值。允许的值包括 [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 主题、着色器和代码片段，并创建新扩展。运行生成器时，它会为每个选项创建一个完整的独立扩展包。但是，通常将多个贡献组合在一个扩展中会更方便。例如，如果您要添加对新语言的支持，您可能希望同时提供带有着色功能的语言定义、代码片段，甚至可能提供调试支持。

要合并扩展贡献，请编辑现有的扩展清单 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，以便在插件市场上进行更轻松的发现和筛选。

提示：确保您合并的贡献使用相同的标识符。在上面的示例中，所有三个贡献都使用 "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 现在也会安装其扩展依赖项。

扩展包应归类在 Extension Packs 插件市场类别中。

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

要创建扩展包，您可以使用 yo code Yeoman 生成器并选择 New Extension Pack 选项。有一个选项可以使用您当前 VS Code 实例中已安装的扩展集合来初始化该包。通过这种方式，您可以轻松创建一个包含您喜爱扩展的扩展包，将其发布到插件市场，并与他人分享。

扩展包不应与其捆绑的扩展有任何功能性耦合，且捆绑的扩展应能独立于该包进行管理。如果一个扩展对另一个扩展有依赖，该依赖应通过 extensionDependencies 属性声明。

扩展卸载钩子

如果您的扩展在从 VS Code 卸载时需要进行清理工作，您可以向扩展的 package.json 中 scripts 部分下的卸载钩子 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 - 支持国际化和本地化。
• vscode-uri - VS Code 及其扩展使用的 URI 实现。
• jsonc-parser - 一个容错性强的扫描器和解析器，用于处理带或不带注释的 JSON。
• request-light - 一个带有代理支持的轻量级 Node.js 请求库。
• vscode-extension-telemetry - 为 VS Code 扩展提供一致的遥测报告。
• vscode-languageclient - 轻松集成遵循 语言服务器协议（Language Server Protocol） 的语言服务器。

后续步骤

要了解有关 VS Code 可扩展性模型的更多信息，请尝试以下主题

• 贡献点 - VS Code 贡献点参考
• 激活事件 - VS Code 激活事件参考
• 扩展市场 - 了解更多关于 VS Code 扩展市场的信息