初探vscode插件开发

趁着元旦假期最后一天，初次尝试了一下vscode插件开发，写了一个前端工具箱作为日常方便使用，记录一下

在vscode插件里面搜索：前端工具箱。或打开该网址安装即可 https://marketplace.visualstudio.com/items?itemName=poetries.fe-tools

# 搭建开发环境

我们先准备开发环境。我使用的操作系统：mac，首先确保安装了VS Code、Node.js 和 Git：

code -v
node -v
npm -v
git --version

@前端进阶之旅: 代码已经复制到剪贴板

https://code.visualstudio.com/api/get-started/your-first-extension

npm install -g yo generator-code

@前端进阶之旅: 代码已经复制到剪贴板

使用yo code指令初始化VSCode插件项目，然后需要回答一些简单的配置问题

yo code

# What type of extension do you want to create? 
# 创建那一种类型的扩展？

# What's the name of your extension?
# 扩展的名称？

# What's the identifier of your extension?
# 扩展的标示？

# What's the description of your extension?
# 扩展的描述

# Initialize a git repository? 
# 初始化git仓库

# Which package manager to use? 
# 使用那一种包管理器

@前端进阶之旅: 代码已经复制到剪贴板

# 运行插件

使用 VS Code 打开项目，在编辑器内部，按F5，编译并打开一个“扩展开发宿主机”窗口运行调试插件。为了叙述方便，把新打开的窗口称为运行窗口，旧窗口称为编辑窗口。在新窗口的命令面板（Ctrl+Shift+P）运行 Hello World 命令。看到右下角的 Hello World 通知信息了吗？恭喜你已经运行了一个自己编写的插件！

# 调试插件

使用 VS Code 调试扩展插件很容易。这里演示一下如何设置断点。在编辑窗口打开 extension.js 文件，点击编辑器行号左侧的边栏设置断点。在运行窗口命令面板输入 Hello World 命令运行插件，命中断点。

# 调试webview

按F5打开调试模式，在webview页面，按command+shift+p选择open webview

# 项目解析

接下来我们来深入研究一下 helloworld 插件。 helloworld 的功能很简单，就是用户可以在命令面板执行 Hello World 命令，输出 Hello World 信息

从实现的角度来看，helloworld 插件做了三件事：

注册激活事件 onCommand:extension.helloWorld：插件在extension.helloWorld 触发时被激活。
注册贡献点 contributes.commands:extension.helloWorld：在命令面板中使能 hello world 命令，并将其绑定到 extension.helloworld。
调用 VS Code API commands.registerCommand 给注册的命令 extension.helloWorld绑定处理函数。

# 基本概念

简单解释一下上面提到的三个概念：激活事件、贡献点和接口：

激活事件，译自 Activation Events，在配置清单 package.json 中静态声明，其实就是 JSON 数组 activationEvents 的值。当激活事件发生时，声明的扩展将被激活。以下是目前所有可用激活事件：onLanguage、onCommand、onDebug:onDebugInitialConfigurations、onDebugResolve、workspaceContains、onFileSystem、onView、onUri、onWebviewPanel、*；
贡献点，译自 Contribution Points，在配置清单 package.json 中静态声明，贡献点其实就是VS Code 的可以扩展的功能点。以下是目前所有可用的贡献点：configuration、configurationDefaults、commands、menus、keybindings、languages、debuggers、breakpoints、grammars、themes、snippets、jsonValidation、views、viewsContainers、problemMatchers、problemPatterns taskDefinitions、colors、typescriptServerPlugins、resourceLabelFormatters、contributes.configur。
VS Code 接口：可以在扩展代码中调用的一组 JavaScript API。链接中列举了所有可用的API，熟悉基本的，其他的用到的时候按需查找就行了。

一般来说，插件都会使用到这三个概念：激活事件、贡献点和 VS Code API。接下来我们分析一下 HelloWorld 示例的源代码，看看它是如何使用这些概念的。

# JavaScript 插件目录结构

VS Code 插件的目录结构很简单，根据命名大概就能知道作用。不同项目类型目录结构可能会有很大不同。对于 JavaScript 类型的项目来说，最重要的就是package.json 和 extension.js 。

# 清单文件：package.json

每个 VS Code 插件都必须有一个用来描述插件的清单文件 package.json。VS Code 的清单文件是声明式的 JSON 格式，用于声明插件名（name）、插件展示名（ displayName ）、描述信息（description）、版本（ version ）、引擎（ engines ）、类别（ categories ）、依赖（ devDependencies ）、脚本（scripts）、贡献点（ contributes ）、入口文件（ main ）、激活事件（ activationEvents ）等。

下面是 helloworld 插件的清单文件内容，为了便于理解，我加了一些注释。

{
    "name": "helloworld", //插件名
    "displayName": "helloworld", // 插件市场显示的插件名，支持中文
    "description": "demo", // 插件市场显示的描述信息
    "version": "0.0.1", // 版本号
    // 最低支持的 VS Code 版本
    "engines": {
        "vscode": "^1.38.0"
    },
    // 插件市场分类
    "categories": [
        "Other"
    ],
    // 激活事件
    "activationEvents": [
        "onCommand:extension.helloWorld"
    ],
    "main": "./extension.js", // 指定入口文件
    // 贡献点
    "contributes": {
        "commands": [{
            "command": "extension.helloWorld",
            "title": "Hello World"
        }]
    },
    // 脚本
    "scripts": {
        "test": "node ./test/runTest.js"
    },
    // 依赖，包含版本信息
    "devDependencies": {
        "@types/glob": "^7.1.1",
        "@types/mocha": "^5.2.6",
        "@types/node": "^10.12.21",
        "@types/vscode": "^1.38.0",
        "eslint": "^5.13.0",
        "glob": "^7.1.4",
        "mocha": "^6.1.4",
        "typescript": "^3.3.1",
        "vscode-test": "^1.2.0"
    }
}

@前端进阶之旅: 代码已经复制到剪贴板

# 插件入口文件：extension.js

插件的入口文件是在清单文件中指定的，如果项目比较大，源文件比较多，也可以统一放在 src 目录里。

一个插件必须在其主模块实现并导出 activate()和 deactivate() 函数。

activate() 函数初始化插件。当任何指定的激活事件发生时，VS Code 会调用并且只调用它一次。
deactivate() 函数清理插件。如果清理过程是异步的， deactivate() 函数必须返回一个 Promise 对象。如果清理运行同步，则 deactivate() 函数返回 undefined 。

# Webview

插件可以分为多种，比如主题样式类型的插件，图标插件，语言支持类型的插件。Webview类型的插件只是Vscode插件的一个大类。大致的实现大家可以参考文档，文档的示例使用的是html字符串，但这不适合复杂的Webview的开发。在GameNews这个插件中，模版部分，我使用了vue以及pug。

// 静态资源的目录。绝对路径，并且使用了vscode-resource协议
// vscode-resource:/Users/Desktop/game-news/views
const webviewDir = path.join(context.extensionPath, 'views');

// 创建一个Webview的面板
const panel = vscode.window.createWebviewPanel(
    viewType,
    title,
    vscode.ViewColumn.One,
    {
        enableScripts: true, // 允许运行js脚本，默认是关闭的
        retainContextWhenHidden: true, // webview不可见时，脚本就会被挂起
        // 指定允许加载的本地资源的根目录
        localResourceRoots: [vscode.Uri.file(webviewDir)]
    }
);

// 模版文件
const tpl = path.join(webviewDir, 'index.pug');

// 通过pug渲染模版文件，到webview上
panel.webview.html = pug.renderFile(tpl, options);

@前端进阶之旅: 代码已经复制到剪贴板

# 本地资源的使用

Webview中，我们会需要使用本地的css，js文件。虽然可以使用行间js或者行间样式，但是总归不太好。使用本地文件，就会涉及的静态文件路径的问题，在VScode中，我们需要使用绝对路径。并且是vscode-resource协议的路径。

const webviewDir = path.join(context.extensionPath, 'views');
// 静态资源的绝对目录
let URI = vscode.Uri.file(path.join(webviewDir, 'js', 'vue.js'))
// 使用vscode-resource协议头
// 然后这个URL就可以使用在我们的webview的模版中了
URI = URI.with({ scheme: 'vscode-resource' });

@前端进阶之旅: 代码已经复制到剪贴板

# Webview与插件通信

下面是GameNews插件的例子，我通过事件将游戏新闻的url，发送给插件。插件会调用系统的命令，使用本地的浏览器打开url。

# 打包、发布和升级

趁着元旦假期最后一天，初次尝试了一下vscode插件开发，写了一个前端工具箱作为日常方便使用，记录一下

在vscode插件里面搜索：前端工具箱。或打开该网址安装即可 https://marketplace.visualstudio.com/items?itemName=poetries.fe-tools

# 搭建开发环境

我们先准备开发环境。我使用的操作系统：mac，首先确保安装了VS Code、Node.js 和 Git：

code -v
node -v
npm -v
git --version

@前端进阶之旅: 代码已经复制到剪贴板

https://code.visualstudio.com/api/get-started/your-first-extension

npm install -g yo generator-code

@前端进阶之旅: 代码已经复制到剪贴板

使用yo code指令初始化VSCode插件项目，然后需要回答一些简单的配置问题

yo code

# What type of extension do you want to create? 
# 创建那一种类型的扩展？

# What's the name of your extension?
# 扩展的名称？

# What's the identifier of your extension?
# 扩展的标示？

# What's the description of your extension?
# 扩展的描述

# Initialize a git repository? 
# 初始化git仓库

# Which package manager to use? 
# 使用那一种包管理器

@前端进阶之旅: 代码已经复制到剪贴板

# 运行插件

使用 VS Code 打开项目，在编辑器内部，按F5，编译并打开一个“扩展开发宿主机”窗口运行调试插件。为了叙述方便，把新打开的窗口称为运行窗口，旧窗口称为编辑窗口。在新窗口的命令面板（Ctrl+Shift+P）运行 Hello World 命令。看到右下角的 Hello World 通知信息了吗？恭喜你已经运行了一个自己编写的插件！

# 调试插件

使用 VS Code 调试扩展插件很容易。这里演示一下如何设置断点。在编辑窗口打开 extension.js 文件，点击编辑器行号左侧的边栏设置断点。在运行窗口命令面板输入 Hello World 命令运行插件，命中断点。

# 调试webview

按F5打开调试模式，在webview页面，按command+shift+p选择open webview

# 项目解析

接下来我们来深入研究一下 helloworld 插件。 helloworld 的功能很简单，就是用户可以在命令面板执行 Hello World 命令，输出 Hello World 信息

从实现的角度来看，helloworld 插件做了三件事：

注册激活事件 onCommand:extension.helloWorld：插件在extension.helloWorld 触发时被激活。
注册贡献点 contributes.commands:extension.helloWorld：在命令面板中使能 hello world 命令，并将其绑定到 extension.helloworld。
调用 VS Code API commands.registerCommand 给注册的命令 extension.helloWorld绑定处理函数。

# 基本概念

简单解释一下上面提到的三个概念：激活事件、贡献点和接口：

激活事件，译自 Activation Events，在配置清单 package.json 中静态声明，其实就是 JSON 数组 activationEvents 的值。当激活事件发生时，声明的扩展将被激活。以下是目前所有可用激活事件：onLanguage、onCommand、onDebug:onDebugInitialConfigurations、onDebugResolve、workspaceContains、onFileSystem、onView、onUri、onWebviewPanel、*；
贡献点，译自 Contribution Points，在配置清单 package.json 中静态声明，贡献点其实就是VS Code 的可以扩展的功能点。以下是目前所有可用的贡献点：configuration、configurationDefaults、commands、menus、keybindings、languages、debuggers、breakpoints、grammars、themes、snippets、jsonValidation、views、viewsContainers、problemMatchers、problemPatterns taskDefinitions、colors、typescriptServerPlugins、resourceLabelFormatters、contributes.configur。
VS Code 接口：可以在扩展代码中调用的一组 JavaScript API。链接中列举了所有可用的API，熟悉基本的，其他的用到的时候按需查找就行了。

一般来说，插件都会使用到这三个概念：激活事件、贡献点和 VS Code API。接下来我们分析一下 HelloWorld 示例的源代码，看看它是如何使用这些概念的。

# JavaScript 插件目录结构

VS Code 插件的目录结构很简单，根据命名大概就能知道作用。不同项目类型目录结构可能会有很大不同。对于 JavaScript 类型的项目来说，最重要的就是package.json 和 extension.js 。

# 清单文件：package.json

每个 VS Code 插件都必须有一个用来描述插件的清单文件 package.json。VS Code 的清单文件是声明式的 JSON 格式，用于声明插件名（name）、插件展示名（ displayName ）、描述信息（description）、版本（ version ）、引擎（ engines ）、类别（ categories ）、依赖（ devDependencies ）、脚本（scripts）、贡献点（ contributes ）、入口文件（ main ）、激活事件（ activationEvents ）等。

下面是 helloworld 插件的清单文件内容，为了便于理解，我加了一些注释。

{
    "name": "helloworld", //插件名
    "displayName": "helloworld", // 插件市场显示的插件名，支持中文
    "description": "demo", // 插件市场显示的描述信息
    "version": "0.0.1", // 版本号
    // 最低支持的 VS Code 版本
    "engines": {
        "vscode": "^1.38.0"
    },
    // 插件市场分类
    "categories": [
        "Other"
    ],
    // 激活事件
    "activationEvents": [
        "onCommand:extension.helloWorld"
    ],
    "main": "./extension.js", // 指定入口文件
    // 贡献点
    "contributes": {
        "commands": [{
            "command": "extension.helloWorld",
            "title": "Hello World"
        }]
    },
    // 脚本
    "scripts": {
        "test": "node ./test/runTest.js"
    },
    // 依赖，包含版本信息
    "devDependencies": {
        "@types/glob": "^7.1.1",
        "@types/mocha": "^5.2.6",
        "@types/node": "^10.12.21",
        "@types/vscode": "^1.38.0",
        "eslint": "^5.13.0",
        "glob": "^7.1.4",
        "mocha": "^6.1.4",
        "typescript": "^3.3.1",
        "vscode-test": "^1.2.0"
    }
}

@前端进阶之旅: 代码已经复制到剪贴板

# 插件入口文件：extension.js

插件的入口文件是在清单文件中指定的，如果项目比较大，源文件比较多，也可以统一放在 src 目录里。

一个插件必须在其主模块实现并导出 activate()和 deactivate() 函数。

activate() 函数初始化插件。当任何指定的激活事件发生时，VS Code 会调用并且只调用它一次。
deactivate() 函数清理插件。如果清理过程是异步的， deactivate() 函数必须返回一个 Promise 对象。如果清理运行同步，则 deactivate() 函数返回 undefined 。

# Webview

插件可以分为多种，比如主题样式类型的插件，图标插件，语言支持类型的插件。Webview类型的插件只是Vscode插件的一个大类。大致的实现大家可以参考文档，文档的示例使用的是html字符串，但这不适合复杂的Webview的开发。在GameNews这个插件中，模版部分，我使用了vue以及pug。

// 静态资源的目录。绝对路径，并且使用了vscode-resource协议
// vscode-resource:/Users/Desktop/game-news/views
const webviewDir = path.join(context.extensionPath, 'views');

// 创建一个Webview的面板
const panel = vscode.window.createWebviewPanel(
    viewType,
    title,
    vscode.ViewColumn.One,
    {
        enableScripts: true, // 允许运行js脚本，默认是关闭的
        retainContextWhenHidden: true, // webview不可见时，脚本就会被挂起
        // 指定允许加载的本地资源的根目录
        localResourceRoots: [vscode.Uri.file(webviewDir)]
    }
);

// 模版文件
const tpl = path.join(webviewDir, 'index.pug');

// 通过pug渲染模版文件，到webview上
panel.webview.html = pug.renderFile(tpl, options);

@前端进阶之旅: 代码已经复制到剪贴板

# 本地资源的使用

Webview中，我们会需要使用本地的css，js文件。虽然可以使用行间js或者行间样式，但是总归不太好。使用本地文件，就会涉及的静态文件路径的问题，在VScode中，我们需要使用绝对路径。并且是vscode-resource协议的路径。

const webviewDir = path.join(context.extensionPath, 'views');
// 静态资源的绝对目录
let URI = vscode.Uri.file(path.join(webviewDir, 'js', 'vue.js'))
// 使用vscode-resource协议头
// 然后这个URL就可以使用在我们的webview的模版中了
URI = URI.with({ scheme: 'vscode-resource' });

@前端进阶之旅: 代码已经复制到剪贴板

# Webview与插件通信

下面是GameNews插件的例子，我通过事件将游戏新闻的url，发送给插件。插件会调用系统的命令，使用本地的浏览器打开url。