🚀 在 VS Code 中

扩展清单

每个 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(默认)、stringfalse 控制 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:prepublishvscode:uninstall
icon 字符串 至少 128x128 像素(Retina 屏幕为 256x256)的图标路径。
pricing 字符串 扩展的定价信息。允许的值:FreeTrial。默认值:Free。有关更多详细信息,请参阅此处
capabilities 对象 一个对象,描述扩展在受限工作区中的功能:untrustedWorkspacesvirtualWorkspaces

另请查看 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 中提供相对路径图像链接。

以下是一些示例

  1. Word Count
  2. MD Tools

提供一个好的显示名称和描述。这对于 Marketplace 和产品展示非常重要。这些字符串也用于 VS Code 中的文本搜索,拥有相关的关键字将非常有帮助。

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

图标和对比鲜明的横幅颜色在 Marketplace 页面标题头中看起来很棒。theme 属性指的是要在横幅中使用的字体 - darklight

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

你可以设置几个可选链接(bugshomepagerepository),这些链接显示在 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 LanguagesSnippets,以便在 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 部分中。

下一步

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