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"
}
}]
}