在 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 上的其他扩展标签一起显示。此列表目前限制为 30 个关键词。
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. 字数统计
  2. MD 工具

提供一个好的显示名称和描述。这对于 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 LanguagesLanguage 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(仅限 Workflows)
  • 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 现在还将安装其扩展依赖项。

扩展包应归类到 Marketplace 的 Extension Packs 类别中

{
  "categories": ["Extension Packs"]
}

要创建扩展包,您可以使用 yo code Yeoman 生成器并选择新建扩展包选项。有一个选项可以将您当前在 VS Code 实例中安装的扩展集作为种子添加到包中。通过这种方式,您可以轻松地创建包含您喜爱的扩展的扩展包,将其发布到 Marketplace,并与他人分享。

扩展包不应与其捆绑的扩展存在任何功能依赖关系,并且捆绑的扩展应独立于扩展包进行管理。如果一个扩展依赖于另一个扩展,则该依赖关系应使用 extensionDependencies 属性声明。

扩展卸载钩子

如果您的扩展在从 VS Code 卸载时需要进行一些清理工作,您可以在扩展的 package.json 文件中的 scripts 部分下,为卸载钩子 vscode:uninstall 注册一个 node 脚本。

{
  "scripts": {
    "vscode:uninstall": "node ./out/src/lifecycle"
  }
}

此脚本在扩展从 VS Code 完全卸载后(即在扩展卸载后重新启动 VS Code 时,包括关闭和启动)执行。

注意:仅支持 Node.js 脚本。

有用的 Node 模块

npmjs 上有几个 Node.js 模块可帮助编写 VS Code 扩展。您可以将它们包含在扩展的 dependencies 部分中。

后续步骤

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