参加你附近的 ,了解 VS Code 中的 AI 辅助开发。

扩展清单

每个 Visual Studio Code 扩展在其扩展目录结构的根目录下都需要一个清单文件 package.json

字段

名称 必需 类型 详细信息
name Y 字符串 扩展的名称 - 应该全部小写,没有空格。
此名称在 Marketplace 中必须是唯一的。
版本 Y 字符串 SemVer 兼容版本。
发布者 Y 字符串 发布者标识符
引擎 Y 对象 一个对象,至少包含 vscode 键,其值与扩展程序兼容的 VS Code 版本匹配。不能为 *。例如:^0.10.5 表示与最低 VS Code 版本 0.10.5 兼容。
许可证 字符串 请参阅 npm 的文档。如果您的扩展根目录下确实有 LICENSE 文件,则 license 的值应为 "SEE LICENSE IN <filename>"
displayName 字符串 在 Marketplace 中使用的扩展显示名称。
显示名称在 Marketplace 中必须是唯一的。
描述 字符串 对您的扩展是什么以及做什么的简短描述。
类别 string[] 您要用于扩展的类别。允许的值:[Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs, Data Science, Machine Learning, Visualization, Notebooks, Education, Testing]
关键词 数组 一个关键字数组,以便更容易找到扩展。这些关键字与 Marketplace 上的其他扩展标签一起包含在内。此列表目前限制为 30 个关键字。
galleryBanner 对象 有助于格式化 Marketplace 标头以匹配您的图标。详见下文。
预览 布尔值 将扩展设置为在 Marketplace 中标记为预览。
主要 字符串 您的扩展入口点。
浏览器 字符串 您的Web 扩展的入口点。
贡献 对象 一个描述扩展贡献的对象。
激活事件 数组 此扩展的激活事件数组。
徽章 数组 用于在 Marketplace 扩展页面的侧边栏中显示的批准徽章数组。每个徽章都是一个对象,包含 3 个属性:url 用于徽章图像 URL,href 用于用户点击徽章时将跟随的链接,以及 description
Markdown 字符串 控制 Marketplace 中使用的 Markdown 渲染引擎。可以是 github(默认)或 standard
问答 marketplace(默认)、stringfalse 控制 Marketplace 中的问答链接。设置为 marketplace 以启用默认的 Marketplace 问答站点。设置为字符串以提供自定义问答站点的 URL。设置为 false 以完全禁用问答。
赞助商 对象 指定用户可以赞助您的扩展的位置。这是一个带有单个属性 url 的对象,该属性链接到用户可以赞助您的扩展的页面。
依赖项 对象 您的扩展所需的任何运行时 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] 表示扩展可以在任一位置运行,但更倾向于在本地机器上运行。有关更多详细信息,请参阅此处
脚本 对象 npm 的 scripts 完全相同,但包含额外的 VS Code 特定字段,例如 vscode:prepublishvscode:uninstall
图标 字符串 图标路径,至少 128x128 像素(Retina 屏幕为 256x256)。
定价 字符串 扩展的定价信息。允许的值:FreeTrial。默认值:Free。有关更多详细信息,请参阅此处
功能 对象 一个描述扩展在受限工作区中能力的对象: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
许可证 许可证

为您的扩展设置一个 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.travis-ci.com
  • app.fossa.io
  • badge.buildkite.com
  • badge.fury.io
  • badgen.net
  • badges.frapsoft.com
  • badges.gitter.im
  • cdn.travis-ci.com
  • 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
  • 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
  • visualstudio.com
  • vsmarketplacebadges.dev

注意:请将 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 可扩展性模型的更多信息,请尝试以下主题