插件清单

配置字段


名称 必须 类型 详细
name Y string 插件的名称必须用全小写无空格的字母组成。
version Y string SemVer版本模式兼容。
publisher Y string 发行方名称
engines Y object 一个至少包含vscode字段的对象,其值必须兼容 VS Code版本。不可以是*。例如:^0.10.5 表明最小兼容0.10.5版本的VS Code。
license string 参考npm’s documentation。如果你在插件根目录已经提供了LICENSE文件。那么license的值应该是"SEE LICENSE IN <filename>"
displayName string 插件市场所显示的插件名称。
description string 简单地描述一下你的插件是做什么的。
categories string[] 你想要使用的插件分类,可选值有:[Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs]
keywords array 关键字(数组),这样用户可以更方便地找到你的插件。到时候会和市场上的其他插件以标签筛选在一起。
galleryBanner object 根据你的icon格式化市场的头部显示。详情见下。
preview boolean 在市场中会显示Preview标记。
main string 你的插件入口
contributes object 描述插件发布内容的对象。
activationEvents array 激活事件数组。
badges array 显示在插件市场页面侧边栏的合法标记。 每个标记都是一个对象,包含了3个属性:url 标记的图片URL,当用户点击标记和description时,会跳转到href
markdown string 控制市场中使用的Markdown渲染引擎。可以是github (默认) 或 standard
qna marketplace (默认), string, false 控制市场中的Q & A 链接。 设置成marketplace时,自动使用市场默认的Q & A网址。或者提供一个URL转跳到你的Q & A 地址。设置为false时禁用。
dependencies object Node.js 运行时依赖。等同于npm’s dependencies.
devDependencies object Node.js 开发时依赖。 等同于npm’s devDependencies.
extensionDependencies array 插件依赖,由插件ID组成的数组。当主要插件安装完成后,其他插件会相应安装。插件ID的格式为 ${publisher}.${name}。比如:vscode.csharp
scripts object 等同于npm的 scripts,不过有VS Code额外字段如vscode:prepublishvscode:uninstall.
icon string icon的文件路径,最小 128x128 像素 (视网膜屏幕则需 256x256)。

你还可以参考npm的package.json

示例


下面是一份完整的package.json示例

  1. {
  2. "name": "wordcount",
  3. "displayName": "Word Count",
  4. "version": "0.1.0",
  5. "publisher": "ms-vscode",
  6. "description": "Markdown Word Count Example - reports out the number of words in a Markdown file.",
  7. "author": {
  8. "name": "seanmcbreen"
  9. },
  10. "categories": [
  11. "Other"
  12. ],
  13. "icon": "images/icon.png",
  14. "galleryBanner": {
  15. "color": "#C80000",
  16. "theme": "dark"
  17. },
  18. "activationEvents": [
  19. "onLanguage:markdown"
  20. ],
  21. "engines": {
  22. "vscode": "^1.0.0"
  23. },
  24. "main": "./out/extension",
  25. "scripts": {
  26. "vscode:prepublish": "node ./node_modules/vscode/bin/compile",
  27. "compile": "node ./node_modules/vscode/bin/compile -watch -p ./"
  28. },
  29. "devDependencies": {
  30. "vscode": "0.10.x",
  31. "typescript": "^1.6.2"
  32. },
  33. "license": "SEE LICENSE IN LICENSE.txt",
  34. "bugs": {
  35. "url": "https://github.com/Microsoft/vscode-wordcount/issues",
  36. "email": "smcbreen@microsoft.com"
  37. },
  38. "repository": {
  39. "type": "git",
  40. "url": "https://github.com/Microsoft/vscode-wordcount.git"
  41. },
  42. "homepage": "https://github.com/Microsoft/vscode-wordcount/blob/master/README.md"
  43. }

插件市场展示小贴士


下面是一些让你的插件在市场上看起来狂拽酷帅吊炸天的小建议。

使用npm install -g vsce安装最新的vsce

在插件根目录中新建一个README.md文件,我们会把里面的内容作为插件的介绍(在市场上),你可以在README.md提供图片的相对路径。

下面是两个栗子🌰:

  1. Word Count
  2. MD Tools

好的名字和描述是市场展示产品非常重要的部分。下述字符串用于VS Code文本搜索,带上关键字更容易被找到。

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

Icon和banner颜色会展示在市场页面头部,theme属性是指banner中使用的字体主题——darklight

  1. {
  2. "icon": "images/icon.png",
  3. "galleryBanner": {
  4. "color": "#C80000",
  5. "theme": "dark"
  6. },
  7. }

下面的几个可选链接(bugshomepagerepository)会在市场的Resources部分显示:

  1. {
  2. "license": "SEE LICENSE IN LICENSE.txt",
  3. "homepage": "https://github.com/Microsoft/vscode-wordcount/blob/master/README.md",
  4. "bugs": {
  5. "url": "https://github.com/Microsoft/vscode-wordcount/issues",
  6. "email": "smcbreen@microsoft.com"
  7. },
  8. "repository": {
  9. "type": "git",
  10. "url": "https://github.com/Microsoft/vscode-wordcount.git"
  11. },
  12. }
市场资源链接 对应的package.json属性
Issues bugs:url
Repository repository:url
Homepage homepage
License license

设置插件的categorycategory一样的插件会分类到一起以便用户查找和筛选。

注意:请使用有意义的分类值,允许的值有[Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs]。有语法高亮、代码补全功能的插件,请使用Programming LanguagesLanguage Packs分类是为本地化保留的插件类别(例如:简体中文(本地化))。

  1. {
  2. "categories": [
  3. "Linters", "Programming Languages", "Other"
  4. ],
  5. }

?> 小贴士: The Extension Manifest Editor 插件可以帮你预览预览你的插件中的README.mdpackage.json, 生成的预览就像你已经发布到插件市场了一样。

使用认证过的徽章

出于安全考虑,我们只允许可信服务商提供的标志。 我们允许来自下列URL前缀的标志:

如果你想用其他标志,欢迎在我们的Github issue页面提供建议。

整合插件配置


yo code可以帮你轻松地打包TextMate 主题,着色器,代码片段和创建新插件。当你运行了生成器,每一次配置都会创建一个完整、独立的插件包。但是,将多个配置内容整合进一个插件会更方便。比如:你想要支持一门新的语言,你会希望同时提供语法高亮和代码片段,甚至调试支持。

为了整合插件配置,编辑已有的package.json文件,然后添加新的配置内容,关联相关文件。

下面是一个包含了LaTex语言定义(语言标识符和相关文件插件),(语法)着色器和代码片段。

  1. {
  2. "name": "language-latex",
  3. "description": "LaTex Language Support",
  4. "version": "0.0.1",
  5. "publisher": "someone",
  6. "engines": {
  7. "vscode": "0.10.x"
  8. },
  9. "categories": [
  10. "Programming Languages",
  11. "Snippets"
  12. ],
  13. "contributes": {
  14. "languages": [{
  15. "id": "latex",
  16. "aliases": ["LaTeX", "latex"],
  17. "extensions": [".tex"]
  18. }],
  19. "grammars": [{
  20. "language": "latex",
  21. "scopeName": "text.tex.latex",
  22. "path": "./syntaxes/latex.tmLanguage.json"
  23. }],
  24. "snippets": [{
  25. "language": "latex",
  26. "path": "./snippets/snippets.json"
  27. }]
  28. }
  29. }

注意插件的categories字段现在包含了Programming LanguagesSnippets,以便用户在市场中找到这个插件。

?> 小贴士: 整合好的配置文件应该使用同样的标识符。在上述例子中,所有的标识符都用了”latex”。这样VS Code 才知道(语法)着色器和代码片段是为LaTeX语言准备的,当编辑LaTeX文件的时候才会激活插件。

插件包


你也可以将几个独立的插件打包成一个“插件包”。插件包是指一组可以无冲突安装的插件集合。然后你就可以很方便地把插件分享给其他人,或者为特定情境创建一组插件,比如帮助PHP工程师在VS Code中快速上手。

一个插件包可以包含其他插件,或者直接将其打包到自身中。package.json中的extensionDependencies描述了这项依赖。

举个例子🌰,下面是一个PHP插件包,其中包含了调试器,语言服务器和格式化器。

  1. {
  2. "extensionDependencies": [
  3. "felixfbecker.php-debug",
  4. "felixfbecker.php-intellisense",
  5. "Kasik96.format-php"
  6. ]
  7. }

当安装插件包的时候,VS Code会连同它的插件依赖一起安装。

插件包需要使用市场分类中的Extension Packs

  1. {
  2. "categories": [
  3. "Extension Packs"
  4. ],
  5. }

想要创建插件包,你可以使用yo codeYeoman生成器。另外,你也可以用你VS Code中已有的一些插件生成插件包,然后你就可以很轻松地从喜欢的插件中创建出插件包,再发布到市场上或者分享给其他用户。

插件包不应该有除了它内部打包之外的其他插件包,打包好的插件包应该是在整个包里面可以独立管理的。如果一个插件非常依赖另外一个插件,那么这个依赖性应该在extensionDependencies中声明。

插件卸载钩子


如果你的插件在删除时需要做一些清理工作,你可以在package.json中的卸载钩子vscode:uninstall中注册一个node脚本。

  1. {
  2. "scripts": {
  3. "vscode:uninstall": "node ./out/src/lifecycle"
  4. }
  5. }

这个脚本会在插件完全卸载之后执行,也就是插件完全卸载之后——VS Code重载(关闭然后启动)之后执行。

!> 注意:只支持Node.js脚本

下面有几个npmjs的Node.js 模块,可以帮你实现VS Code插件。你可以在插件的dependencies部分包含进去。

下一步

学习更多VS Code扩展性模型,看看下面的话题: