目录
- VSCode插件如何集成基建的脚手架和组件库?(FAW保姆级教程)
前言
我们程序员每天的产出大部分都是在IDE中完成,大家在日常开发过程中,多多少少会有些自己的特殊定制需求去提升开发效率,比如写shell脚本、浏览器插件等,在Visual Studio Code (VSCode)中我们也能开发一些插件去满足日常工作需要。比如现在业务要新开发一个项目,设计稿风格和之前系统类似。那我第一想法肯定是去拷贝已有项目的代码(或者使用组内抽象的模板),然后稍作修改满足当前需求。但如果是新同学往往需要经历咨询已有项目/模板相关人员->开通各种权限->复用部分代码并做个性化修改->借助组件库、工具库进入业务功能开发,这个过程有一定沟通和时间成本。所以我期望能有一个更直观的方式让新同学了解组内有哪些基建并投入使用,比如能直接在VSCode中罗列当前的模板项目,预览后选择特定模板进行项目初始化,并且将一些个性化基础配置通过表单形式进行填写并渲染,避免遗漏。而且在开发过程能在VSCode中直观的展示当前有哪些组件和工具函数可以使用,然后通过点点点操作实现组件的添加和快速使用。本文也将带着下面几个问题去讲解开发VSCode插件的过程:VSCode插件中如何新建项目、新建页面、组件...?
VSCode插件能做什么
- 可视化搭建页面(面向开发者的低代码)(AppWorks)
VSCode可扩展能力
本章大部分内容在官网中已有说明,此次做简单了解
那VSCode 提供哪些能力去实现上一章所提到的效果?
基于Electron能力
VSCode本身是使用Electron开发的,那他也支持对应的能力。
扩展工作台
VSCode提供了各种 API,允许您将自己的组件添加到工作台。- 活动栏(Tree View Container):
Azure 应用服务扩展添加了一个视图容器 - 侧边栏(Tree View):内置的
NPM 扩展在 Explorer 视图中添加了一个树视图 - 编辑器组(Webview):内置的
Markdown 扩展在编辑器组中的其他编辑器旁边添加了一个 Webview
扩展编辑器
限制
与此同时,也存在一些限制,比如插件不能访 问 VSCode UI 的 DOM 节点。(如果强行改动,VSCode 会提示自身损坏)开发插件
首先对VSCode插件能力有个大概认识,然后从HelloWorld初始化项目去入门,再去集成Webview。由于VSCode本身是使用Electron开发的,且Electron是基于Chromium,渲染进程是使用Web页面作为 UI 显示。那在VSCode中也能集成webview。初始化项目
npm i -g yo generator-code
yo code
? What type of extension do you want to create? New Extension (TypeScript)
? What\'s the name of your extension? HelloWorld
## Press <Enter> to choose default for all options below ###
? What\'s the identifier of your extension? helloworld
? What\'s the description of your extension? LEAVE BLANK
? Initialize a git repository? Yes
? Bundle the source code with webpack? No
? Which package manager to use? npm
? Do you want to open the new folder with Visual Studio Code? Open with `code`
.
├── package.json # 插件配置
├── src
│ ├── extension.ts # 入口文件
├── tsconfig.json
{
// 扩展的激活事件
\"activationEvents\": [
\"onCommand:extension.sayHello\"
],
// 入口文件
\"main\": \"./src/extension\",
// 贡献点,vscode插件大部分功能配置都在这里
\"contributes\": {
\"commands\": [
{
\"command\": \"extension.sayHello\",
\"title\": \"Hello World\"
}
]
}
}
const vscode = require(\'vscode\');
// 插件被激活时触发,所有代码总入口
exports.activate = function(context) {
// 注册命令 与`package.json`中`contributes.commands`
context.subscriptions.push(vscode.commands.registerCommand(\'extension.sayHello\', function () {
vscode.window.showInformationMessage(\'Hello World!\');
}));
};
// 插件被释放时触发
exports.deactivate = function() {};
然后在编辑器中按F5 即可打开新的窗口在命令面板中(⌘⇧P)运行 Hello World 命令进行调试插件:
集成Webview
下方示例为在VSCode集成通过ice生成的webviewmkdir web
cd web
yarn create ice
# or
yarn create @umijs/umi-app
{
\"activationEvents\": [\"onCommand:project-creator.create-project.start\"],
\"contributes\": {
\"commands\": {
\"command\": \"project-creator.create-project.start\",
\"title\": \"创建项目webview\"
}
}
}
activationEvents字段值为数组,通过onCommand注册激活事件project-creator.create-project.start,而project-creator.create-project.start将在contributes.commands中定义contributes字段可以配置扩展VSCode各种能力,比如commands命令、configuration配置...commands中的command将在src/extension.ts中进行注册事件回调
3.配置src/extension.ts创建webview的具体逻辑- 注册命令
project-creator.create-project.start projectCreatorWebviewPanel
VSCode中的Webview本质就是一个iframe,所以是可以在其中执行脚本,但是VSCode默认禁用JavaScript,所以需要配置enableScripts=true开启此功能。提供Webview内容
通过getHtmlForWebview获取 webview 的内容。由于使用icejs进行构建项目,yarn build后的目录结构为index.html、css/index.css、js/index.js,如果开启MPA,则还有vendor.css/js。如果使用其他框架比如 umijs,则采取不同的处理方式即可。
其中通过getNonce生成一个随机数,设置到script的 nonce属性,作用是在加密通信中使用一次随机数避免重复攻击,保证不同的消息与该秘钥加密的秘钥流不同。此代码拷贝自VSCode提供的官网示例。Webview和VSCode通信
一个很常见的场景,我们在webview中通过调接口获取数据,然后渲染页面。但是在vscode webview中是不允许发送ajax请求,所有请求都是跨域(因为webview本身没有host),所以需要在VScode中进行真实的接口请求。此过程则变为在Webview端使用vscode.postMessage,然后在VScode中使用webview.onDidReceiveMessage接收到消息后做相应处理。将交互过程封装成connectService和callService进行统一注册和调用。在options中提供当前页面需要使用的所有服务services的定义,然后再接收到调用事件时,通过const api =
services && services[service] && services[service][method]获取到具体的方法,并将参数进行传递,一定程度去抹平API的差异,减少重复代码量。国际化
配置项国际化
我们可以在package.json中配置VSCode的配置项,这些配置项的国际化是约定在package.nls.json和package.nls.zh-cn.json这些文件中。比如可以在package.nls.json中配置插件英文名称:{
\"projectCreator.create-project.commands.start.title\": \"Select Scaffold to Create Application\"
}
在package.nls.zh-cn.json中配置插件中文名称:{
\"projectCreator.create-project.commands.start.title\": \"选择模板创建应用\"
}
\"contributes\": {
\"commands\": [
{
\"command\": \"project-creator.create-project.start\",
\"title\": \"%projectCreator.create-project.commands.start.title%\"
}
]
}
VScode代码国际化
在代码中进行注册,并且可以通过vscode.env.language获取VSCode当前语言环境。import * as vscode from \'vscode\';
import I18nService from \'./i18n\';
import * as zhCNTextMap from \'./locales/zh-CN.json\'; // { \"webViewTitle\": \"Create Project\" }
import * as enUSTextMap from \'./locales/en-US.json\'; // { \"webViewTitle\": \"创建项目\" }
// 注册语言表
const i18n = new I18nService();
i18n.registry(\'zh-cn\', zhCNTextMap);
i18n.registry(\'en\', enUSTextMap);
// 设置使用的语言
i18n.setLocal(vscode.env.language);
export default i18n;
projectCreatorWebviewPanel = vscode.window.createWebviewPanel(
\'project-creator\', // webview 标识,只供内部使用
i18n.format(\'webViewTitle\'), // 标题
vscode.ViewColumn.One, // 新开一个编辑器视图
{
enableScripts: true, // 启用 JavaScript 脚本
retainContextWhenHidden: true, // 隐藏时保留上下文
},
);
Webview代码国际化
在Webview中我们采用icejs搭建项目,那就可以使用react-intl来配置国际化。然后在代码中进行使用:
VSCode插件集成基建
- 按需求场景根据外部或组内脚手架、组件库、工具库...进行编码调试
- 构建部署阶段:大部分企业都有自研的
devops解决方案 - 对上述过程进行复盘、总结、抽象,进入下一轮需求开发
当我们进入一个新团队时,往往期望能对团队内部的前端研发全链路有一个基本认识,进而可以快速进入开发或投身到感兴趣的技术建设。
当我们开发一个新项目时,往往期望能参考老项目看是否能复用部分,进而减少不必要的重复性工作。基于上面章节对VSCode插件所提供的能力介绍,我们完全可以将前端研发全链路的基建集成到我们日常编码IDE中,并且提供可视化的操作界面,让我们能安心在IDE中进行开发调试,从一定程度减少我们开发过程到处检索而分心低效的问题。
AppWorks
AppWorks是一款基于VSCode插件的前端研发工具集,通过 GUI 操作、物料组装、代码辅助等功能让前端开发更加简单。不过由于下面几个原因,我们决定基于AppWorks做个性化改造以便满足部门内部使用。- 他对
icejs、Rax类型项目支持友好,但由于我们部门中后台项目技术选型为umijs,在使用AppWorks时面板内容显得有点冗余。 - 架构,在
slave项目中不少配置是期望在初始化模板时就自动配置好。 - 方面我们有自己一套组件库并且放在私有
npm,自定义物料的方式也期望能保留我们当前发包结构 - 分为组件(component)、区块(block)和项目(scaffold)三种类型
基于上述考虑,我们做了二次开发并产出了FAW,下面将从使用效果去揭秘他的核心逻辑实现。
FAW使用效果
- 4. 如果模板提供
ask-for-vscode.js文件,则根据配置生成表单 - 主要是配置
publicPath、basePath、mountElementId、id...
6. 生成项目后在当前窗口打开新项目,即可进入开发
FAW整体架构
根据开发插件章节,可以将模板选择、填写配置这些交互功能放在展示层webview中实现,而将获取模板、拷贝模板并渲染这些功能交由业务层VSCode实现。于此同时可以在入口AppWorks中“捆绑”组内高频使用插件,实现安装一个插件时可以安装一系列插件。并且将一些公共配置项、国际化、创建项目和创建物料的核心逻辑...放入packages中使用lerna做管理并在插件中使用。物料基本信息放在配置平台中做统一配置;项目模板存放在Gitlab做版本管理;组件库放在私有npm做管理。
FAW新建项目
逻辑类似前端工程化-打造企业通用脚手架-focus create projectName核心流程
核心流程
- 3. 选择“具体模板”后,拉取所有版本(版本默认约定为在
Gitlab端打的tag
- 4. 选择“具体版本”后,判断当前模板是否提供
ask-for-vscode.js文件
- 4.1 如果没提供则对本模板本版本做本地缓存,方便下次使用。则进入第6步
- 4.2 如果提供则根据配置项渲染为表单供开发者填写
- 配置项一般为
publicPath、basePath、mountElementId、id...
- 5. 通过
ncp把代码拷贝到本地临时目录,然后根据 4.2 填写的内容渲染变量在ejs模板,最后通过metalsmith遍历所有文件做插入修改
核心代码实现
其中第2步定义模板物料的结构,然后在配置平台维护一个json存放所有模板。在第3步中选择具体模板后拉取所有版本,主要借助Gitlab提供的开放能力 https://docs.gitlab.com/ee/api/api_resources.html。在第4步中选择具体版本后,拉取对应代码,并判断是否存在ask-for-vscode.js文件并解析其内容:因为require需要以require(/Users/${filename}.js)的形式导入绝对路径+变量,然而我们模板的名字以及配置都名为变量,故获取不到。// 此方式可行 ✅
const code = require(\'/Users/careteen/Desktop/admin-umi-template/ask-for-vscode.js\')
// 此方式不可行 ❌
const templateName = \'admin-umi-template\'
const configName = \'ask-for-vscode\'
const args = require(`/Users/careteen/Desktop/${templateName}/${configName}.js`)
所以此处采用readFileSync和new Function(code)()的方式获取js文件内容。其中内容如下:// 需要根据用户填写修改的字段
const requiredPrompts = [
{
type: \'input\',
name: \'repoNameEn\',
message: \'please input repo English Name ? (e.g. `smart-phone`.focus.cn)\',
},
{
type: \'input\',
name: \'repoNameEnCamel\',
message: \'please input repo English Camel Name ?(e.g. smart-case.focus.cn/`smartPhone`)\',
},
{
type: \'input\',
name: \'repoNameZh\',
message: \'please input repo Chinese Name ?(e.g. `智能话机`)\',
},
];
return {
requiredPrompts,
};
用这部分内容渲染成表单,然后再根据用户输入内容渲染ejs模板,比如配置文件config/config.ts