扩展清单
每个 Visual Studio Code 扩展都需要一个清单文件 package.json
,它位于扩展目录结构的根目录。
字段
名称 | 必需 | 类型 | 详细信息 |
---|---|---|---|
name |
是 | 字符串 |
扩展的名称 - 应该是全部小写,没有空格。 名称在 Marketplace 中必须是唯一的。 |
version |
是 | 字符串 |
兼容 SemVer 的版本。 |
publisher |
是 | 字符串 |
发布者标识符 |
engines |
是 | 对象 |
一个对象,至少包含 vscode 键,用于匹配扩展兼容的 VS Code 版本。不能为 * 。例如:^0.10.5 表示与最低 VS Code 版本 0.10.5 兼容。 |
license |
字符串 |
请参阅 npm 的文档。如果你的扩展根目录中有一个 LICENSE 文件,则 license 的值应为 "SEE LICENSE IN <filename>" 。 |
|
displayName |
字符串 |
在 Marketplace 中使用的扩展显示名称。 显示名称在 Marketplace 中必须是唯一的。 |
|
description |
字符串 |
对你的扩展是什么以及做什么的简短描述。 | |
categories |
字符串数组 |
你想要用于扩展的类别。允许的值:[Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs, Data Science, Machine Learning, Visualization, Notebooks, Education, Testing] |
|
keywords |
数组 |
一个关键字数组,以便更容易找到扩展。这些关键字与 Marketplace 上的其他扩展标签一起包含。此列表目前限制为 5 个关键字。 | |
galleryBanner |
对象 |
帮助格式化 Marketplace 标题头以匹配你的图标。请参阅下面的详细信息。 | |
preview |
布尔值 |
将扩展设置为在 Marketplace 中标记为预览版。 | |
main |
字符串 |
你的扩展的入口点。 | |
browser |
字符串 |
你的 Web 扩展的入口点。 | |
contributes |
对象 |
一个对象,描述扩展的贡献。 | |
activationEvents |
数组 |
此扩展的激活事件数组。 | |
badges |
数组 |
要在 Marketplace 扩展页面的侧边栏中显示的批准的徽章数组。每个徽章都是一个对象,包含 3 个属性:徽章图像 URL 的 url ,用户单击徽章后将访问的链接的 href ,以及 description 。 |
|
markdown |
字符串 |
控制 Marketplace 中使用的 Markdown 渲染引擎。可以是 github (默认)或 standard 。 |
|
qna |
marketplace (默认)、string 、false |
控制 Marketplace 中的问答链接。设置为 marketplace 以启用默认的 Marketplace 问答站点。设置为字符串以提供自定义问答站点的 URL。设置为 false 以完全禁用问答。 |
|
sponsor |
对象 |
指定用户可以赞助你的扩展的位置。这是一个具有单个属性 url 的对象,该属性链接到一个用户可以赞助你的扩展的页面。 |
|
dependencies |
对象 |
你的扩展所需的任何运行时 Node.js 依赖项。与 npm 的 dependencies 完全相同。 |
|
devDependencies |
对象 |
你的扩展所需的任何开发 Node.js 依赖项。与 npm 的 devDependencies 完全相同。 |
|
extensionPack |
数组 |
一个包含可以一起安装的扩展 ID 的数组。扩展的 ID 始终是 ${publisher}.${name} 。例如:vscode.csharp 。 |
|
extensionDependencies |
数组 |
一个包含此扩展所依赖的扩展 ID 的数组。扩展的 ID 始终是 ${publisher}.${name} 。例如:vscode.csharp 。 |
|
extensionKind |
数组 |
一个数组,指示扩展应在远程配置中的哪个位置运行。值可以是 ui (本地运行)、workspace (在远程计算机上运行)或两者兼有,顺序设置首选项。例如:[ui, workspace] 表示扩展可以在任一位置运行,但首选在本地计算机上运行。有关更多详细信息,请参阅此处。 |
|
scripts |
对象 |
与 npm 的 scripts 完全相同,但具有额外的 VS Code 特定字段,例如 vscode:prepublish 或 vscode:uninstall。 |
|
icon |
字符串 |
至少 128x128 像素(Retina 屏幕为 256x256)的图标路径。 | |
pricing |
字符串 |
扩展的定价信息。允许的值:Free 、Trial 。默认值:Free 。有关更多详细信息,请参阅此处。 |
|
capabilities |
对象 |
一个对象,描述扩展在受限工作区中的功能:untrustedWorkspaces 、virtualWorkspaces 。 |
另请查看 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
中提供相对路径图像链接。
以下是一些示例
提供一个好的显示名称和描述。这对于 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"
}
}
Marketplace 资源链接 | package.json 属性 |
---|---|
问题 | bugs:url |
仓库 | repository:url |
主页 | homepage |
许可证 | license |
为你的扩展设置一个 category
。同一 category
中的扩展在 Marketplace 上分组在一起,这可以改进筛选和发现。
注意: 仅使用对你的扩展有意义的值。允许的值是
[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 问题,我们很乐意查看。
组合扩展贡献
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
,以便在 Marketplace 上轻松发现和筛选。
提示: 确保你合并的贡献使用相同的标识符。在上面的示例中,所有三个贡献都使用 "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
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 - 一个轻量级 Node.js 请求库,带代理支持
- vscode-extension-telemetry - 为 VS Code 扩展提供一致的遥测报告。
- vscode-languageclient - 轻松集成遵循语言服务器协议的语言服务器。
下一步
要了解有关 VS Code 可扩展性模型的更多信息,请尝试以下主题
- 贡献点 - VS Code 贡献点参考
- 激活事件 - VS Code 激活事件参考
- 扩展 Marketplace - 阅读更多关于 VS Code 扩展 Marketplace 的信息