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