扩展清单

每个 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 Marketplace上显示时看起来很棒。

始终使用最新的 vsce，因此请运行 npm install -g @vscode/vsce 以确保您拥有它。

在您的扩展根文件夹中有一个README.md Markdown文件，我们将在扩展详情的主体中包含其内容（在Marketplace上）。您可以在README.md中提供相对路径的图像链接。

以下是一些示例：

1. Word Count
2. MD Tools

提供一个好的显示名称和描述。这对于市场和在产品展示中非常重要。这些字符串也用于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。在Marketplace上，相同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.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（仅来自工作流程）
• 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属性现在包括Programming Languages和Snippets，以便在市场上轻松发现和过滤。

提示： 确保您合并的贡献使用相同的标识符。在上面的示例中，所有三个贡献都使用“latex”作为语言标识符。这让 VS Code 知道颜色器（grammars）和代码片段是针对 LaTeX 语言的，并且在编辑 LaTeX 文件时将会激活。

扩展包

您可以将单独的扩展捆绑在扩展包中。扩展包是一组将一起安装的扩展。这使得可以轻松地与其他用户分享您喜欢的扩展，或者为特定场景（如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生成器并选择新建扩展包选项。有一个选项可以将你当前在VS Code实例中安装的扩展集作为种子添加到包中。通过这种方式，你可以轻松创建一个包含你最喜欢的扩展的扩展包，将其发布到市场，并与他人分享。

扩展包不应与其捆绑的扩展有任何功能依赖关系，并且捆绑的扩展应可独立于包进行管理。如果一个扩展依赖于另一个扩展，则应使用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 - 一个轻量级的Node.js请求库，支持代理
• vscode-extension-telemetry - 为VS Code扩展提供一致的遥测报告。
• vscode-languageclient - 轻松集成遵循语言服务器协议的语言服务器。

下一步

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

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