初识 Vscode 插件开发

我心飞翔 分类:javascript

what-is-vscode.png
之前一直觉得插件开发很难,迟迟不敢接触,但每次看到或者用别人开发的插件时,又非常羡慕,这次刚好有个项目开需要开发 vscode 插件,借此机会终于要对 vscode 插件下手了。本篇文章主要包含入门开发和过程中遇到的一些问题,希望能给大家带来帮助,避免跟我一样踩坑。下面就具体的来看一下吧:

安装脚手架

​使用官方脚手架生成项目,要先安装脚手架,命令如下:

npm install -g yo generator-code
 

生成项目

​切到对应目录,执行 yo code,将会出现如下图的一个选择,根据自己的需求选择对应类型的扩展模板,剩下的就根据提示一步步操作即可,运行完后就生成了一个 vscode 插件项目。

image-20210402094946242

初识 Vscode 插件开发

项目核心结构

​ 执行 yo code 生成项目后,仔细看下项目结构,我们比较重要的其实就两个文件,分别是 package.json 和 extension.js。package.json 是整个插件工程的配置文件,extension.js 是工程的入口文件,下面我们详细介绍一下这两个文件。

pacgage.json

下面是 package.json 文件的常用配置:

{
// 插件名称,需用全小写无空格的字母组成
"name": "vue-typescript-snippets-plugin",
// 插件市场显示的插件名称
"displayName": "vue-typescript-snippets-plugin",
// 简单描述插件的功能
"description": "生成 ts 的 vue 代码片段",
"version": "0.0.1",
// 插件支持的 vscode 最低版本
"engines": {
"vscode": "^1.55.0"
},
// 插件的应用市场分类,可选值包括 [Programming Languages, Snippets, Linters, Themes, Debuggers,Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs]
"categories": [
"Other"
],
// 扩展的激活事件数组
"activationEvents": [
"onCommand:vue-typescript-snippets-plugin.helloWorld"
],
// 插件入口
"main": "./dist/extension.js",
// 配置内容项
"contributes": {
// 命令
"commands": [
{
"command": "vue-typescript-snippets-plugin.helloWorld",
"title": "Hello World"
}
]
},
"scripts": {
"vscode:prepublish": "yarn run package",
"compile": "webpack",
"watch": "webpack --watch",
"package": "webpack --mode production --devtool hidden-source-map",
"test-compile": "tsc -p ./",
"test-watch": "tsc -watch -p ./",
"pretest": "yarn run test-compile && yarn run lint",
"lint": "eslint src --ext ts",
"test": "node ./out/test/runTest.js"
},
"devDependencies": {
"@types/vscode": "^1.55.0",
"@types/glob": "^7.1.3",
"@types/mocha": "^8.0.4",
"@types/node": "^12.11.7",
"eslint": "^7.19.0",
"@typescript-eslint/eslint-plugin": "^4.14.1",
"@typescript-eslint/parser": "^4.14.1",
"glob": "^7.1.6",
"mocha": "^8.2.1",
"typescript": "^4.1.3",
"vscode-test": "^1.5.0",
"ts-loader": "^8.0.14",
"webpack": "^5.19.0",
"webpack-cli": "^4.4.0"
}
}

这个就是我们初始化生成的 package.json 文件,其中比较核心的是 activationEventscontributes

activationEvents

activationEvents 是配置激活事件的,我们插件一开始是没有被激活的,只有当触发了 activationEvents 中配置的事件,插件才会被激活,激活的事件列表如下:

  • onLanguage: 打开指定语言文件时会激活

    "activationEvents": [
    "onLanguage:html"
    ]
    
  • onCommand: 调用命令时会激活

    "activationEvents": [
    "onCommand:extension.sayHello"
    ]
    
  • onDebug: 调试会话启动前会激活

    "activationEvents": [
    "onDebug"
    ]
    
  • workspaceContains: 工作区有包含符合 glob模式的文件时会激活

    "activationEvents": [
    "workspaceContains:**/.editorconfig"
    ]
    
  • onFileSystem: 以协议打开文件或文件夹时会激活

    "activationEvents": [
    "onFileSystem:sftp"
    ]
    
  • onView: 指定 id 的视图展开时会激活

    "activationEvents": [
    "onView:nodeDependencies"
    ]
    
  • onUri: 插件的系统级 URI 打开时会激活,这个URI 协议需要带上vscode或者vscode-insiders协议。

    "activationEvents" [
    "onUri"
    ]
    
  • onWebviewPannel: 当 vscode 需要恢复一个符合 viewType 的 webview 时会激活。

    "activationEvents": [
    "onWebviewPanel:catCoding"
    ]
    
  • onCustomEditor: 当 vscode 需要创建一个符合 viewType 的自定义编辑器时会激活。

    "activationEvents": [
    "onCustomEditor:catCustoms.pawDraw"
    ]
    
  • onStartupFinished: 在 vscode 启动后一段时间会激活,类似于”*“, 但是不会减慢 vscode 的启动速度。

    "activationEvents": [
    "onStartupFinished"
    ]
    
  • *: vscode启动时会激活,为确保用户体验,请在没有其他激活事件时使用。

    "activationEvents": [
    "*"
    ]
    

contributes

还有一个比较核心的配置是contributes,它被称为 Contribution Points,可以用来注册各种配置项来扩展 vscode 的能力。下面是目前可用的配置项列表:

configuration:配置的内容会暴露给用户,可以从”用户设置“和”工作区设置“中修改你暴露的选项。

configurationDefaults:为特定语言配置编辑器的默认值。

commands:设置命令标题和命令体,会展示在命令面板(⇧⌘P)。

menus:为编辑器或文件管理器设置命令的菜单项。至少包含菜单显示的时机和选择菜单执行的命令。

keybindings:配置快捷键

languages:配置语言,引入新的语言或加强 vscode 已有的语言支持。

debuggers:配置 vscode 调试器。

breakpoints:配置哪些语言可以设置断点。

grammars:为一门语言配置 TextMate 语法

themes:为 vscode 增加主题

iconThemes:配置 vscode 的文件图标主题

productIconThemes:配置 vscode 的产品图标主题

snippets:为一门语言增加代码片段

jsonValidation:配置 json 文件的校验器

views:为 vscode 增加视图

viewsWelcome:配置自定义视图的欢迎内容

viewsContainers:配置自定义视图的视图容器

problemMatchers:配置问题定位器的模式

problemPatterns:配置可以在问题定位器(见上)中可以使用的模式名称

taskDefinitions:配置和定义一个 object 结构,定义系统中唯一的配置任务

colors:配置可用于编辑器装饰器和状态栏的颜色

typescriptServerPlugins:配置 vscode 的 js 和 ts 支持的 Typescript 服务器插件

resourceLabelFormatters: 配置资源标签格式化程序,它将指定如何在工作台中的任何地方显示 URI

extension.js

  
extension.js 是插件的入口文件,会导出两个函数:activate 和的activate,当注册的激活事件被触发时,即会执行 activate 中的代码,deactivate 则提供了插件关闭前执行清理工作的机会。由于这里的代码只会被执行一次,所以需要在 activate 中使用 registerCommand 来注册命令,这里的参数必须与 package.json 中定义的 一致,下面是简单的示例:

image-20210402174828752

  
registerCommand的第二个参数匿名函数中的代码,在每次该命令被触发时都会执行一次。我们在vscode 中启动调试之后,会看到弹出一个新的窗口,在新窗口按下 command+shift+p 即可调用插件,输入我们定义的 Hello world 会触发上面匿名函数内的代码,启动我们的插件,在 vscode 的右下角出现一个通知框,这就表示我们的插件启动成功了,接下来我们就可以根据需求开发自己想要的功能了。

运行调试

我们在插件开发过程中,如何实时看到自己插件的效果呢,vscode 提供给我们了,按下图中的顺序操作,1 将切到 debug 的操作面板,点击 2 会开启一个新的窗口,同时出现 3 这样一个操作 bar,可以停止和刷新已经在运行中的插件。还可以直接在对应的代码前加断点,执行命令触发断点后开始调试,也可以通过 console.log() 将日志打印在控制台,但是过于复杂的对象就不能显示了。

image-20210415135934408

image-20210415143508117

打包发布

  • 安装 vsce(Visual Studio Code Extension)

    npm i vsce -g
    
  • 打包成 vsix 文件:

    vsce package
    

    tips:生成的 vsix 文件不能直接拖入安装,只能从扩展的右上角选择 Install from VSIX 安装。

  • 发布到应用市场

    注册登陆网站:登陆网站 dev.azure.com/vscode 获取一个 access token,用这个 token 来创建一个 publisher。

    创建发布者账号: vsce create-publisher (publisher name)

    登陆账号: vsce login (publisher name)

  • 发布

    vsce publish
    

    增量发布:版本号(major.minor.patch)

    vsce publish patch(minor/major)
    

    取消发布:

    vsce unpublish (publisher name).(extension name)
    
  • 更新

    修改版本号,重新执行 vsce publish 即可

问题及解决方案

  1. 生成的 demo 运行后,触发 sayHello 的命令报错: image-20210330094850353

    原因是:vscode 版本低于插件要求的最低版本,即在 package.json 中定义的 engines 属性。

  2. 写snippets时,测试发现并不生效,跟官方文档对比后,发现少写了一个属性 scope,之前看的教程比较老,没有这个属性也可以,但是看最新文档写的是四个属性都为必填值时才能生效。

    image-20210330173246357

参考资料

  1. VSCode插件开发全攻略
  2. vscode 插件开发中文文档
  3. vscode 插件开发英文文档

回复

我来回复
  • 暂无回复内容