VS Code 插件开发中文文档

# 插件清单

# 配置字段

名称 必须 类型 详细
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:prepublish或vscode:uninstall.
icon string icon的文件路径，最小 128x128 像素 (视网膜屏幕则需 256x256)。

你还可以参考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": "seanmcbreen"
    },
    "categories": [
        "Other"
    ],
    "icon": "images/icon.png",
    "galleryBanner": {
        "color": "#C80000",
        "theme": "dark"
    },
    "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": {
        "vscode": "0.10.x",
        "typescript": "^1.6.2"
    },
    "license": "SEE LICENSE IN LICENSE.txt",
    "bugs": {
        "url": "https://github.com/Microsoft/vscode-wordcount/issues",
        "email": "smcbreen@microsoft.com"
    },
    "repository": {
        "type": "git",
        "url": "https://github.com/Microsoft/vscode-wordcount.git"
    },
    "homepage": "https://github.com/Microsoft/vscode-wordcount/blob/master/README.md"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

# 插件市场展示小贴士

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

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

在插件根目录中新建一个README.md文件，我们会把里面的内容作为插件的介绍（在市场上），你可以在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.",
1
2

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

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

下面的几个可选链接（bugs，homepage，repository）会在市场的Resources部分显示：

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

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

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

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

TIP

The Extension Manifest Editor 插件可以帮你预览预览你的插件中的README.md 和 package.json， 生成的预览就像你已经发布到插件市场了一样。

# 使用认证过的徽章

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

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

# 整合插件配置

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

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

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

{
    "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"
        }]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

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

TIP

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

# 插件包

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

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

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

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

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

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

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

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

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

# 插件卸载钩子

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

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

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

注意

只支持Node.js脚本

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

# 下一步

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

← 内置命令 →