尝试以扩展 VS Code 中的代理模式!

扩展清单

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

字段

名称 必需 类型 详细信息
name 字符串 扩展的名称 - 应该全部小写且不含空格。
该名称在应用商店中必须是唯一的。
版本 字符串 SemVer 兼容版本。
发布者 字符串 发布者标识符
引擎 对象 一个对象,至少包含 vscode 键,其值与扩展程序兼容的 VS Code 版本匹配。不能是 *。例如:^0.10.5 表示与最低 VS Code 版本 0.10.5 兼容。
许可证 字符串 请参阅 npm 文档。如果您的扩展根目录中有 LICENSE 文件,则 license 的值应为 "SEE LICENSE IN <filename>"
显示名称 字符串 在应用商店中使用的扩展显示名称。
该显示名称在应用商店中必须是唯一的。
描述 字符串 对您的扩展是什么以及做什么的简短描述。
类别 字符串数组 您希望用于扩展的类别。允许值:[Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs, Data Science, Machine Learning, Visualization, Notebooks, Education, Testing]
关键词 数组 一个关键词数组,以便更容易找到扩展。这些关键词会与应用商店中的其他扩展标签一起显示。此列表目前限制为 30 个关键词。
图库横幅 对象 有助于格式化应用商店标题以匹配您的图标。详见下文。
预览 布尔值 将扩展在应用商店中标记为预览版。
主文件 字符串 您的扩展的入口点。
浏览器 字符串 您的Web 扩展的入口点。
贡献点 对象 一个描述扩展贡献点的对象。
激活事件 数组 此扩展的激活事件数组。
徽章 数组 一个数组,包含在应用商店扩展页面侧边栏中显示的认可的徽章。每个徽章都是一个对象,包含 3 个属性:徽章图片 URL 的 url,用户点击徽章时将跟随的链接的 hrefdescription
Markdown 字符串 控制应用商店中使用的 Markdown 渲染引擎。可以是 github(默认)或 standard
问答 marketplace(默认)、stringfalse 控制应用商店中的问答链接。设置为 marketplace 可启用默认的应用商店问答网站。设置为字符串可提供自定义问答网站的 URL。设置为 false 可完全禁用问答功能。
赞助 对象 指定用户可以赞助您的扩展的位置。这是一个只有一个属性 url 的对象,该属性链接到用户可以赞助您的扩展的页面。
依赖项 对象 您的扩展所需的任何运行时 Node.js 依赖项。与 npm 的 dependencies 完全相同。
开发依赖项 对象 您的扩展所需的任何开发 Node.js 依赖项。与 npm 的 devDependencies 完全相同。
扩展包 数组 一个数组,包含可以一起安装的扩展 ID。扩展的 ID 始终是 ${publisher}.${name}。例如:vscode.csharp
扩展依赖项 数组 一个数组,包含此扩展所依赖的扩展 ID。扩展的 ID 始终是 ${publisher}.${name}。例如:vscode.csharp
扩展类型 数组 一个数组,指示扩展在远程配置中应运行的位置。值为 ui(本地运行)、workspace(在远程机器上运行)或两者皆可,顺序表示偏好。例如:[ui, workspace] 表示扩展可以在任一位置运行,但优先在本地机器上运行。有关更多详细信息,请参阅此处
脚本 对象 npm 的 scripts 完全相同,但增加了 VS Code 特有的字段,例如 vscode:prepublishvscode:uninstall
图标 字符串 图标的路径,至少 128x128 像素(Retina 屏幕为 256x256 像素)。
定价 字符串 扩展的定价信息。允许值:Free(免费)、Trial(试用)。默认值: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"
}

应用商店展示技巧

以下是一些提示和建议,可让您的扩展在 VS Code 应用商店中显示时表现出色。

始终使用最新的 vsce,即运行 npm install -g @vscode/vsce 以确保您已安装它。

在扩展的根文件夹中包含一个 README.md Markdown 文件,我们将在扩展详细信息(在应用商店中)的正文中包含其内容。您可以在 README.md 中提供相对路径的图片链接。

以下是一些示例

  1. 字数统计
  2. MD 工具

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

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

图标和对比鲜明的横幅颜色在应用商店页面标题上看起来很棒。theme 属性指的是横幅中使用的字体 - dark(深色)或 light(浅色)。

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

您可以设置几个可选链接(bugshomepagerepository),这些链接会显示在应用商店的资源部分下。

{
  "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"
  }
}
应用商店资源链接 package.json 属性
问题 bugs:url
仓库 repository:url
主页 homepage
许可证 许可证

为您的扩展设置一个 category。同一 category 中的扩展会在应用商店中组合在一起,从而改善筛选和发现。

注意:只使用对您的扩展有意义的值。允许值包括 [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,以便在应用商店中轻松发现和筛选。

提示:请确保您合并的贡献点使用相同的标识符。在上面的示例中,所有三个贡献点都使用“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 类别中。

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

要创建扩展包,您可以使用 yo code Yeoman 生成器并选择 New Extension Pack(新建扩展包)选项。有一个选项可以使用您当前在 VS Code 实例中安装的扩展集来初始化该包。通过这种方式,您可以轻松地创建包含您喜欢的扩展的扩展包,将其发布到应用商店,并与他人分享。

扩展包不应与其捆绑的扩展存在任何功能依赖关系,并且捆绑的扩展应该独立于扩展包进行管理。如果一个扩展依赖于另一个扩展,则应使用 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 可扩展性模型的更多信息,请尝试以下主题