vscode-扩展插件

title: vscode-扩展插件
categories: VSCode
tags: [vscode, 插件, 扩展]
date: 2018-10-31 14:44:18
comments: false

因为 vscode 已经是我的主用开发工具, 已经抛弃了 sublime text, vs. 开发 unity, shader, lua, h5 等几乎都是用它了. 很多时候需要偷懒, 就写个插件辅助一下. ( 工欲善其事必先利其器 )

本地插件保存路径

可以参考别人写插件的方式来写自己的插件.

已有插件所在目录

os	path
windows	%USERPROFILE%.vscode\extensions
macOS	~/.vscode/extensions
Linux	~/.vscode/extensions

插件保存文件夹名字规则, [作者名].[插件名].[版本号] , 例如

官方samples

官方插件示例 - https://github.com/Microsoft/vscode-extension-samples

如果运行时报错. 一下步骤逐步执行测试

安装相关依赖, 直接在工作区输入命令: npm install
当前工作区已有 npm watch 任务在运行. 可以在终端 kill. 也可直接切换成别的工作区再切回来

可能是旧版本未更新, 更新一下

package.json 文件中 scripts 字段修改为一下内容

  "scripts": {"vscode:prepublish": "npm run compile","compile": "tsc -p ./","watch": "tsc -watch -p ./","postinstall": "node ./node_modules/vscode/bin/install","test": "npm run compile && node ./node_modules/vscode/bin/test"},

tasks.json 文件中

{"version": "2.0.0","tasks": [{"type": "npm","script": "watch","problemMatcher": "$tsc-watch","isBackground": true,"presentation": {"reveal": "never"}}]
}

launch.json 文件修改

{"version": "0.2.0","configurations": [{"name": "Extension","type": "extensionHost","request": "launch","runtimeExecutable": "${execPath}","args": ["--extensionDevelopmentPath=${workspaceFolder}"],"outFiles": ["${workspaceFolder}/out/**/*.js"],"preLaunchTask": "npm: watch"}]
}

前置物料

安装 Yeoman , 命令 : npm install -g yo
安装 Yeoman 的 generator-code, 命令 : npm install -g generator-code
安装打包插件的工具命令 : npm install -g vsce

初始化工程

初始化一个新工程, 命令: yo code . 这里选择的是 ts extension 工程. 然后照着提示输入 name, description 等等

C:\Users\Administrator>yo code_-----_     ╭──────────────────────────╮|       |    │   Welcome to the Visual  │|--(o)--|    │   Studio Code Extension  │`---------´   │        generator!        │( _´U`_ )    ╰──────────────────────────╯/___A___\   /|  ~  |__'.___.'__´   `  |° ´ Y `? What type of extension do you want to create? New Extension (TypeScript)
? What's the name of your extension? VSC-Plugin001
? What's the identifier of your extension? wilkeryun
? What's the description of your extension? my custom plugin
? What's your publisher name (more info: https://code.visualstudio.com/docs/tools/vscecli#_publishing-extensions)? yangxuan0261
? Enable stricter TypeScript checking in 'tsconfig.json'? Yes
? Setup linting using 'tslint'? Yes
? Initialize a git repository? Yescreate wilkeryun\.vscode\launch.json...
vscode.d.ts successfully installed!wilkeryun@0.0.1 C:\Users\Administrator\wilkeryun

生成目录结构
package.json : 定义入口文件, 命令, 显示在那些地方 (左边栏, 标题栏等等), 插件描述等信息. 基本所有的配置这里

新建一个命令

在 package.json 文件中加入相关配置

{..."activationEvents": ["onCommand:extension.sayHello","onCommand:myext.copyLuaFileName" // 3. 激活这个命令],"main": "./out/extension","contributes": {"commands": [{"command": "extension.sayHello","title": "Hello World title"},{ // 1. 新增一个命令 myext.copyLuaFileName"command": "myext.copyLuaFileName","title": "复制lua文件" // 命名显示名称}],"menus": {"explorer/context": [{ // 2. 设置这个定义出现在左边栏"when": "!explorerResourceIsFolder", // 自定义显示条件, 非文件夹就显示"command": "myext.copyLuaFileName","group": "navigation"}]}},...
}

在 extension.ts 文件中注册这个命令及对应的相关自定义逻辑

export function activate(context: vscode.ExtensionContext) {...let run = vscode.commands.registerCommand("myext.copyLuaFileName", (fileUri) => {vscode.window.showInformationMessage('复制的文件 fileUri:' + fileUri);});context.subscriptions.push(run);
}

测试. 按 F5 , 会运行一个新的vscode进程

打包使用插件

打包

在插件根目录下使用命令: vsce package , 会在该目录下生产一个 xxx.vsix 插件文件

F:\git_repo\wilkeryun>vsce package
Executing prepublish script 'npm run vscode:prepublish'...
...
A 'repository' field is missing from the 'package.json' manifest file.
Do you want to continue? [y/N] y
Created: F:\git_repo\wilkeryun\wilkeryun-0.0.1.vsix (7 files, 3.21KB)

TODO: 这个报错暂时未去查
过程中可能会提示你先修改 README.md 文件才能打包，简单描述功能即可。

使用

安装, 手动安装插件文件

然后选择 从 VSIX 安装…, 选择 xxx.vsix 文件即可
可以在插件列表中看到这个插件, ctrl + shift + x 显示插件列表

打包, 发布参考: http://jdc.jd.com/archives/212586

发布

参考: https://liiked.github.io/VS-Code-Extension-Doc-ZH/#/extension-authoring/publish-extension , 获取Personal Access Token (PAT)

创建发布者,

F:\git_repo\wilkeryun>vsce create-publisher wilker // wilker 这个随意
Publisher human-friendly name: (wilker)
E-mail: wolegequ@live.com // 这个邮箱是微软的登录账号
Personal Access Token: **************************************************** // (PAT)Successfully created publisher 'wilker'.

发布

F:\git_repo\wilkeryun>vsce publish -p hqg5tqkkjsdasdasdasdadasdasdasdasd //(PAT)
Executing prepublish script 'npm run vscode:prepublish'...> wilkeryun@0.0.1 vscode:prepublish F:\git_repo\wilkeryun
> npm run compile> wilkeryun@0.0.1 compile F:\git_repo\wilkeryun
> tsc -p ./A 'repository' field is missing from the 'package.json' manifest file.
Do you want to continue? [y/N] y
Publishing yangxuan0261.wilkeryun@0.0.1...
Successfully published yangxuan0261.wilkeryun@0.0.1! // 发布成功
Your extension will live at https://marketplace.visualstudio.com/items?itemName=yangxuan0261.wilkeryun (might take a few seconds for it to show up).

然后就可以看到发布结果 (这是改了名称和版本的截图)

搜索使用

踩坑

报错

Error: Failed Request: Unauthorized(401) - https://marketplace.visualstudio.com/_apis/gallery
Be sure to use a Personal Access Token which has access to **all accessible accounts**.
See https://code.visualstudio.com/docs/tools/vscecli#_common-questions for more information.

没有赋予最高权限

扩展清单文件 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：

{"name": "Spell","displayName": "Spelling and Grammar Checker","description": "Detect mistakes as you type and suggest fixes - great for Markdown.","icon": "images/spellIcon.svg","version": "0.0.19","publisher": "seanmcbreen","galleryBanner": {"color": "#0000FF","theme": "dark"},"license": "SEE LICENSE IN LICENSE.md","bugs": {"url": "https://github.com/Microsoft/vscode-spell-check/issues","email": "smcbreen@microsoft.com"},"homepage": "https://github.com/Microsoft/vscode-spell-check/blob/master/README.md","repository": {"type": "git","url": "https://github.com/Microsoft/vscode-spell-check.git"},"categories": ["Linters", "Languages", "Other"],"engines": {"vscode": "0.10.x"},"main": "./out/extension","activationEvents": ["onLanguage:markdown"],"contributes": {"commands": [{"command": "Spell.suggestFix","title": "Spell Checker Suggestions"}],"keybindings": [{"command": "Spell.suggestFix","key": "Alt+."}]},"scripts": {"vscode:prepublish": "node ./node_modules/vscode/bin/compile","compile": "node ./node_modules/vscode/bin/compile -watch -p ./"},"dependencies": {"teacher": "^0.0.1"},"devDependencies": {"vscode": "^0.11.x"}
}

相关api

关于 contributes.configuration

参考: https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributesconfiguration

关于 contributes.commands

参考: https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributescommands

关于 contributes.menus

参考: https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributesmenus

踩坑

在左边栏或这编辑区右键时, 可以办当前文件 uri 传进去的, 但是如果将这个命令注册为快捷键, 使用快捷键时是无法获取到这个uri的, 为 null
```
let run = vscode.commands.registerCommand("myext.copyLuaFileName", (fileUri) => {console.log("--- fileUri 111:", fileUri);});
```
但是可以通过api获取到当前激活的文档, 从而获取到 fileUri
```
if (fileUri === undefined) {fileUri =  vscode.window.activeTextEditor!.document.uri;
}
```
目前还不支持 vscode.window.showInformationMessage 提示框的关闭, 必须手动关闭

参考 - https://stackoverflow.com/questions/34893733/how-to-programmatically-close-vscode-windows-showinformationmessage-box

但是支持在 底部状态栏 中显示信息, 并设置自动关闭时间. vscode.window.setStatusBarMessage

关于 when

在显示在相关菜单时有个条件 (when) 可以让其判断是否显示.

"contributes": {"menus": {"editor/context": [{"when": "config.wilker-cfg.showLuaCopy && editorLangId == lua && !inOutput", // 在 configuration 中定义这个配置, 必须是 bool 值"command": "wilker-ext.copyLuaFileName","group": "myGroup@110"}]},"configuration": {"type": "object","title": "Wilker Plugin Configuration","properties": {"wilker-cfg.showLuaCopy": { // 这个值可以暴露给用户设置在 全局 或 工作区"type": "boolean","default": false,"description": "是否显示 复制lua 在右键菜单中","scope": "resource"}}}
}

这样是配死定义, 不能动态变化根据文件是否是某些特定文件才让其是否显示在右键中. 有个方法可以动态修改这个值, 不过应该是有点消耗性能的, 就是注册一个切换编辑文件回调, 动态修改配置值
```
vscode.window.onDidChangeActiveTextEditor((e) => {// 判断条件let isShow = true;let cfg = vscode.workspace.getConfiguration("wilker-cfg");cfg.update("showLuaCopy", isShow, vscode.ConfigurationTarget.Workspace);
});
```
ps: 这是曲线救国的方式, 不知道正确的姿势是怎么样. 局限性是只能在 切换编辑文件 时能触发到

内置when条件

参考 vscode 源码, 所属关键字 new RawContextKey<boolean>( , 看到的都是可用内置条件

使用正则表达式

格式: sameName =~ /正则表达式/

{"when": "editorLangId =~ /(lua|csharp)/", // 表示只有文件是 lua或者csharp 时, 条件才为 true...
},

注意中间的符号是 =~, 如果使用的是 == 则为普通的判断

参考: https://github.com/Microsoft/vscode/issues/26044

关于 activate deactivate

这两个函数都在入口文件 extension.ts 中

activate

这个函数的调用时机可以根据需要配置.

  "activationEvents": ["onCommand:wilker-ext.copyLuaFileName" // 调用这个命令是才调用 activate],"activationEvents": ["*" // 已启动vscode 调用 activate],

参考 Activation Events - package.json - https://code.visualstudio.com/docs/extensionAPI/activation-events

deactivate

关闭vscode时会触发, 如果有异步的必须返回 Promise. Extension must return a Promise fromdeactivate()if the cleanup process is asynchronous

export function deactivate() {return new Promise<boolean>(async (resolve, reject) => {await mycleanfunc();resolve();});
}

关于 TextDocument.languageId

切换编辑文件时可用于一些逻辑判断

参考 Language Identifiers - https://code.visualstudio.com/docs/languages/identifiers

显示命令的各种地方

配置在 package.json

{"contributes": {"menus": { // 配置在这个字段中"explorer/context": [{"when": "!explorerResourceIsFolder","command": "myext.copyLuaFileName","group": "navigation"}]...}},}

左边栏右键

key : "explorer/context"

编辑区右键

key: "editor/context"