VSCode插件 package.json字段解析及核心属性解析
欢迎关注前端早茶，与广东靓仔携手共同进阶
前端早茶专注前端，一起结伴同行，紧跟业界发展步伐~
学习vscode插件开发，学会package.json和extension.ts文件后，就可以轻松的进行VSCode插件开发啦！
一、package.json
{ // 插件的名字，必须全部小写且不能有空格 "name": "cat-extension", // 用于显示在应用市场的名称，支持中文 "displayName": "cat_extension", // 对于插件的描述 "description": "cat extension", // 版本号 "version": "0.0.1", // 表示插件最低支持的vscode版本 "engines": { "vscode": "^1.68.0" }, // 插件应用市场分类 "categories": [ "Other" ], // 插件的图标 "icon":"", // 扩展的激活事件的数组，就是这个插件可以被哪些事件激活 "activationEvents": [ "onCommand:cat-extension.helloWorld" ], // 插件的主入口 "main": "./dist/extension.js", // 插件的配置项 "contributes": { "commands": [{ "command": "cat-extension.helloWorld", "title": "Hello World" }] }, "scripts": { "vscode:prepublish": "npm run package", "compile": "webpack", "watch": "webpack --watch", "package": "webpack --mode production --devtool hidden-source-map", "compile-tests": "tsc -p . --outDir out", "watch-tests": "tsc -p . -w --outDir out", "pretest": "npm run compile-tests && npm run compile && npm run lint", "lint": "eslint src --ext ts", "test": "node ./out/test/runTest.js" }, // 开发依赖 "devDependencies": { "@types/vscode": "^1.68.0", "@types/glob": "^7.2.0", "@types/mocha": "^9.1.1", "@types/node": "16.x", "@typescript-eslint/eslint-plugin": "^5.27.0", "@typescript-eslint/parser": "^5.27.0", "eslint": "^8.16.0", "glob": "^8.0.3", "mocha": "^10.0.0", "typescript": "^4.7.2", "ts-loader": "^9.3.0", "webpack": "^5.72.1", "webpack-cli": "^4.9.2", "@vscode/test-electron": "^2.1.3" } }
二、activationEvents属性
插件的激活事件数组，在什么情况下插件会被激活，当激活事件发生时，插件将被激活。
1、onLanguage
每当打开解析为特定语言的文件时，就会触发激活事件
"activationEvents": [ // 可以声明多种语言 "onLanguage:javascript"， "onLanguage:json"， "onLanguage:python"， ],
2、onCommand
每次调用命令时，就会触发激活事件
"activationEvents": [ "onCommand:test-extension.helloWorld" ],
还需要在contributes进行配置
"contributes": { "commands": [{ // 与激活事件中onCommand指令相对应 "command": "test-extension.helloWorld", //激活插件的命令 "title": "Hello World" }] },
3、onDebug
在启动调试会话之前，会触发激活事件
"activationEvents": [ "onDebug" ]
4、workspaceContains
每当打开文件夹并且该文件夹包含至少一个与glob模式匹配的文件时，会激活事件
"activationEvents": [ "workspaceContains:**/.editorconfig" ]
5、onFileSystem
以协议（scheme）打开文件或文件夹时触发激活事件。通常是file-协议，也可以用自定义的文件供应器函数替换掉，比如ftp、ssh。
"activationEvents": [ "onFileSystem:sftp" ]
6、onView
只要在VSCode侧边栏中展开指定ID的视图时，就会触发激活事件
"activationEvents": [ "onView:nodeDependencies" ]
７、onUri
只要打开该插件的系统范围URI，就会触发激活事件。这个URI协议需要带上vscode或者vscode-insiders协议。
"activationEvents": [ "onUri" ]
8、onWebviewPanel
vscode需要恢复匹配到viewType的webview视图时触发
"activationEvents": [ "onWebviewPanel:catCoding" ]
9、*
当VSCode启动时，插件就会被激活
"activationEvents": [ "*" ]
三、contributes属性
1、configuration
暴露给用户的配置，用户可以从”用户设置“和”工作区设置“中修改暴露的选项。
可以通过vscode.workspace.getConfiguration(“title”)来读取配置
"contributes": { "configuration": { "type": "object", "title": "TypeScript configuration", "properties": { "typescript.useCodeSnippetsOnMethodSuggest": { "type": "boolean", "default": false, "description": "Complete functions with their parameter signature." }, "typescript.tsdk": { "type": ["string", "null"], "default": null, "description": "Specifies the folder path containing the tsserver and lib*.d.ts files to use." } } } }
2、configurationDefaults
为特定的语言配置编译器的默认值，修改这个配置会覆盖编译器已经为语言提供的默认配置
"contributes": { "configurationDefaults": { // 修改markdown语言的默认配置 "[markdown]": { "editor.wordWrap": "on", "editor.quickSuggestions": false } } }
3、commands
设置命令标题和命令体，然后这个命令会显示在命令面板中。
category可以设置前缀，在命令面板中会以分类显示
"contributes": { "commands": [{ "command": "extension.sayHello", "title": "Hello World",// 在命令面板中显示的命令 "category": "Hello" }] }
4、menus
1、为编译器或者文件管理器设置命令的菜单项，即当点击菜单项时会触发命令。
2、至少包含两个属性：
- 选中时调用的命令 command
- 何时显示这个菜单项 when
3、group：定义了菜单的分组，navigation值不同于普通的group值。
4、可以配置菜单项的地方有：
- 全局命令面板:commandPalette
- 资源管理器上下文菜单：explorer/context
- 编译器上下文菜单：editor/context
- 编译器标题栏：editor/title
- 编译器标题上下文菜单：editor/title/context
- 调试栈视图的上下文菜单：debug/callstack/context
- SCM标题菜单：scm/title
- SCM 资源组：scm/resourceGroup/context
- SCM资源：scm/resource/context
- SCM改变标题：scm/change/title
- 视图的标题菜单：view/title
- 视图项的菜单：view/item/context
5、示例：当打开文件为markdown类型时，在编译器标题栏添加菜单项。
"contributes": { "commands": [{ "command": "extensionts.helloWorld", "title": "Hello World" }], "menus": { // 在哪里添加菜单项 "editor/title": [{ // 何时触发 "when":"resourceLangId == markdown", // 要触发的命令 "command": "extensiondemo.helloWorld", // 分组 "group": "navigation" }] } }
5、groupSorting
菜单项可以通过组来分类，具体的分类不再阐述。
6、keybindings
设置快捷键
"contributes": { "keybindings": [{ // 要执行的命令 "command": "extension.sayHello", // 在Windows和Linux下 "key": "ctrl+f1", // 在mac下 "mac": "cmd+f1", "when": "editorTextFocus" }] }
7、languages
配置一门语言，引入一门新的语言或者加强VS Code已有的语言支持。
... "contributes": { "languages": [{ "id": "python", "extensions": [ ".py" ], // 包含这门语言的可读性 "aliases": [ "Python", "py" ], "filenames": [ ... ], "firstLine": "^#!/.*\\bpython[0-9.-]*\\b", // 语言配置文件的路径 "configuration": "./language-configuration.json" }] }
8、debuggers
配置VS Code的调试器
"contributes": { "debuggers": [{ // 用于加载配置的调试器唯一标识 "type": "node", // 会在UI中显示的调试器名称 "label": "Node Debug", // 调试适配的路径 "program": "./out/node/nodeDebug.js", // 如果调试适配器的路径是不可执行程序，那么就会用到这个运行时 "runtime": "node", "languages": ["javascript", "typescript", "javascriptreact", "typescriptreact"], // 调试器的启动配置参数 "configurationAttributes": { "launch": { "required": [ "program" ], "properties": { "program": { "type": "string", "description": "The program to debug." } } } }, // 列出初始化lanuch.json需要加载的配置 "initialConfigurations": [{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/app.js" }], // 列出编译器launch.json文件可以提供的加载配置智能提示 "configurationSnippets": [ { "label": "Node.js: Attach Configuration", "description": "A new configuration for attaching to a running node program.", "body": { "type": "node", "request": "attach", "name": "${2:Attach to Port}", "port": 9229 } } ], // 引入替代变量，并绑定到调试器插件实现的命令上 "variables": { "PickProcess": "extension.node-debug.pickNodeProcess" } }] }
9、breakpoints
通常调试器插件会有contributes.breakpoints入口，插件可以设置哪些语言可以设置断点
"contributes": { "breakpoints": [ { "language": "javascript" }, { "language": "javascriptreact" } ] }
10、grammars
为一门语言配置TextMate语法，必须提供应用语法的language，Text Mate的scopeName确定了语法和文件路径
"contributes": { "grammars": [{ "language": "markdown", "scopeName": "text.html.markdown", "path": "./syntaxes/markdown.tmLanguage.json", "embeddedLanguages": { "meta.embedded.block.frontmatter": "yaml", ... } }] }
11、themes
为VS Code添加Text Mate主题，必须添加label来指定主题
"contributes": { "themes": [{ "label": "Monokai", "uiTheme": "vs-dark", "path": "./themes/Monokai.tmTheme" }] }
12、snippets
为语言添加代码片段，language是语言标识符，path是VSCode代码片段格式的代码片段文件的相对路径
"contributes": { "snippets": [{ "language": "go", "path": "./snippets/go.json" }] }
13、view、viewsContainers
view属性为VSCode添加视图
viewsContainers配置自定义视图的视图容器
"contributes": { "viewsContainers": { //activitybar:配置活动栏 "activitybar": [ { "id": "package-explorer", "title": "Package Explorer", "icon": "resources/package-explorer.svg" } ] }, "views": { "package-explorer": [ { "id": "package-dependencies", "name": "Dependencies" } ] } }
14、colors
状态栏的编译器装饰器，定义之后可以通过workspace.colorCustomization自定义颜色
"contributes": { "colors": [{ "id": "superstatus.error", "description": "Color for error message in the status bar.", "defaults": { "dark": "errorForeground", "light": "errorForeground", "highContrast": "#010203" } }] }
欢迎关注前端早茶，与广东靓仔携手共同进阶
前端早茶专注前端，一起结伴同行，紧跟业界发展步伐~
