扩展清单文件 - package.json

每个VS Code扩展需要一个清单文件package.json,该文件位于扩展的根目录中。

字段

名称 是否必要 类型 说明
name string 扩展的名称,该名称必须为小写且不能有空格。
version string SemVer 兼容版本.
publisher string 发布人名字
engines object 一个至少包含vscode键值对的对象,该键表示的是本扩展可兼容的VS Code的版本,其值不能为*。比如 ^0.10.5 表示扩展兼容VS Code的最低版本是0.10.5
license string 参考 npm’s 文档. 如果你确实需要在扩展根目录下有一个授权文档,那么应该把license值设为"SEE LICENSE IN <filename>"
displayName string 用于在扩展市场中本扩展显示的名字。
description string 一份简短的说明,用来说明本插件是什么以及做什么
categories string[] 你希望你的扩展属于哪一类,只允许使用这几种值:[Languages, Snippets, Linters, Themes, Debuggers, Other]
keywords array 一组 关键字 或者 标记,方便在市场中查找。
galleryBanner object 帮助格式化市场标题以匹配你的图标,详情如下。
preview boolean 在市场中把本扩展标记为预览版本。
main string 扩展的入口点。
contributes object 一个描述扩展 贡献点的对象。
activationEvents array 一组用于本扩展的 激活事件
dependencies object 你的扩展所需的任何运行时的Node.js依赖项,和 npm’s dependencies一样。
devDependencies object 你的扩展所需的任何开发的Node.js依赖项. 和 npm’s devDependencies一样。
extensionDependencies array 一组本扩展所需的其他扩展的ID值。扩展的ID值始终是 ${publisher}.${name}。比如:vscode.csharp
scripts object npm’s scripts一样,但还有一些额外VS Code特定字段.
icon string 一个128x128像素图标的路径。

也可以查看npm’s package.json参考文档.

范例

这里有一个完整的package.json

  1. {
  2. "name": "Spell",
  3. "displayName": "Spelling and Grammar Checker",
  4. "description": "Detect mistakes as you type and suggest fixes - great for Markdown.",
  5. "icon": "images/spellIcon.svg",
  6. "version": "0.0.19",
  7. "publisher": "seanmcbreen",
  8. "galleryBanner": {
  9. "color": "#0000FF",
  10. "theme": "dark"
  11. },
  12. "license": "SEE LICENSE IN LICENSE.md",
  13. "bugs": {
  14. "url": "https://github.com/Microsoft/vscode-spell-check/issues",
  15. "email": "smcbreen@microsoft.com"
  16. },
  17. "homepage": "https://github.com/Microsoft/vscode-spell-check/blob/master/README.md",
  18. "repository": {
  19. "type": "git",
  20. "url": "https://github.com/Microsoft/vscode-spell-check.git"
  21. },
  22. "categories": [
  23. "Linters", "Languages", "Other"
  24. ],
  25. "engines": {
  26. "vscode": "0.10.x"
  27. },
  28. "main": "./out/extension",
  29. "activationEvents": [
  30. "onLanguage:markdown"
  31. ],
  32. "contributes": {
  33. "commands": [
  34. {
  35. "command": "Spell.suggestFix",
  36. "title": "Spell Checker Suggestions"
  37. }
  38. ],
  39. "keybindings": [
  40. {
  41. "command": "Spell.suggestFix",
  42. "key": "Alt+."
  43. }
  44. ]
  45. },
  46. "scripts": {
  47. "vscode:prepublish": "node ./node_modules/vscode/bin/compile",
  48. "compile": "node ./node_modules/vscode/bin/compile -watch -p ./"
  49. },
  50. "dependencies": {
  51. "teacher": "^0.0.1"
  52. },
  53. "devDependencies": {
  54. "vscode": "^0.11.x"
  55. }
  56. }

市场呈现要点

为了让你自己的扩展在[VS Code市场]中看起来更好,这里有几个要点和建议。

始终使用最新的vsce,即用npm install -g vsce可保证最新。

在你的扩展根目录中编写一个README.md的MAERKDOWN文档,这样我们会在市场中的扩展信息中显示其中的内容。你可以在README.md中提供图片的相对路径链接。

这里有几个例子做说明:

  1. Spell-Checker
  2. MD Tools

请提供一个良好的显示名称和描述。这对于市场和产品显示都非常重要。在VS Code中这些字符串能用于文本搜索,并且有相关关键字将有很大帮助。

  1. "displayName": "Spelling and Grammar Checker",
  2. "description": "Detect mistakes as you type and suggest fixes - great for Markdown.",

在市场页面头中,有一个图标以及对比色横幅也会让扩展看起来非常棒,theme属性指的是在横幅中使用的字体:dark或者是light

  1. "icon": "images/spellIcon.svg",
  2. "galleryBanner": {
  3. "color": "#5c2d91",
  4. "theme": "dark"
  5. },

你也可以设置一些其他的链接(错误、主页、代码库),他们会在市场中资源一栏所呈现出来。

  1. "license": "SEE LICENSE IN LICENSE.md",
  2. "bugs": {
  3. "url": "https://github.com/Microsoft/vscode-spell-check/issues"
  4. },
  5. "homepage": "https://github.com/Microsoft/vscode-spell-check/blob/master/README.md",
  6. "repository": {
  7. "type": "git",
  8. "url": "https://github.com/Microsoft/vscode-spell-check.git"
  9. }
市场资源链接 package.json 属性
支持 bugs:url
开始页 repository:url
主页 homepage
授权 license

为你的扩展设置category。在市场中,同一个category将会放在一起,这样就方便过滤和查找。

注意 为你的扩展使用正确的值,只能使用这些值[Languages, Snippets, Linters, Themes, Debuggers, Other]

  1. "categories": [
  2. "Linters", "Languages", "Other"
  3. ],

结合扩展贡献

yo code生成器能让你轻松打包文本主题、颜色设置和代码片段并创建新的扩展。当生成器运行时,它为每个选项创建一个完整的独立扩展包。然而很多时候我们更倾向于创建一个包含多个贡献点的扩展。比如说,如果你希望为一门新语言添加支持,则希望为用户提供带有代码着色的语言定义和代码段功能,甚至可以提供调试支持。

要使能够结合扩展贡献,仅仅只需要编辑已经存在的清单文件package.json并添加新的贡献点和关联文件即可。

以下是一个扩展的清单文件,它包含了Latex语言定义(语言标识符和文件扩展名)、着色器(grammar)和代码段。

  1. {
  2. "name": "language-latex",
  3. "description": "LaTex Language Support",
  4. "version": "0.0.1",
  5. "publisher": "someone",
  6. "engines": {
  7. "vscode": "0.10.x"
  8. },
  9. "categories": [
  10. "Languages",
  11. "Snippets"
  12. ],
  13. "contributes": {
  14. "languages": [{
  15. "id": "latex",
  16. "aliases": ["LaTeX", "latex"],
  17. "extensions": [".tex"]
  18. }],
  19. "grammars": [{
  20. "language": "latex",
  21. "scopeName": "text.tex.latex",
  22. "path": "./syntaxes/latex.tmLanguage"
  23. }],
  24. "snippets": [{
  25. "language": "latex",
  26. "path": "./snippets/snippets.json"
  27. }]
  28. }
  29. }

注意,扩展的清单文件中categories属性现在可以同时包含LanguagesSnippets,这样方便在市场中查找和过滤。

要点 确保你的多个贡献点使用的是相同的标识符。在上例中,三个贡献点都是使用“latex”作为语言标识符。这让VS Code知道语法着色器和代码段是用于LaTeX语言并当编辑LaTex文件时激活它。

下一步

要想了解更多关于VS Code可扩展性模型, 可以查看这些主题:

常见问题

暂无