Tapable是一个为插件创造钩子的库,他也是webpack的核心库。Tapable v1之后的版本跟之前的用法差别非常大,主要区别是以前用继承class A extends tapable, 现在直接在类里面定义私有成员this.hooks. 貌似网上很多都是老版本的用法,鉴于马上就要v2了,翻译走一波,顺便点一下目前1.1版本的坑
原文github.com/webpack/tap…
Tapable
tapable提供很多钩子类(Hook classes),他们可以被用来为插件创造钩子。
const {
SyncHook, // 同步钩子
SyncBailHook, // 同步早退钩子
SyncWaterfallHook, // 同步瀑布钩子
SyncLoopHook, // 同步循环钩子
AsyncParallelHook, // 异步并发钩子
AsyncParallelBailHook, // 异步并发可早退钩子
AsyncSeriesHook, // 异步顺序钩子
AsyncSeriesBailHook, // 异步顺序可早退钩子
AsyncSeriesWaterfallHook // 异步顺序瀑布钩子
} = require("tapable");
安装
npm install --save tapable
使用
所有的钩子类的构造器都接受一个可选参数,它是一个 这个钩子所接受参数的参数名数组。
const hook = new SyncHook(["arg1", "arg2", "arg3"]);
最佳做法是一次性在hooks属性里面定义好所用的钩子:
class Car {
constructor() {
this.hooks = {
// 以下分别是油门,刹车,计算路线钩子
accelerate: new SyncHook(["newSpeed"]),
brake: new SyncHook(),
calculateRoutes: new AsyncParallelHook(["source", "target", "routesList"])
};
}
/* ... */
}
其他人现在就能使用以上的钩子了:
const myCar = new Car();
// 使用tap方法添加具体的执行逻辑
myCar.hooks.brake.tap("WarningLampPlugin", () => warningLamp.on()); // 亮灯插件,逻辑为刹车时亮灯
为了定位你的插件,一个合适的名字(上面WarningLampPlugin)是必须的。
你定义的函数可以接收参数
myCar.hooks.accelerate.tap("LoggerPlugin", newSpeed => console.log(`Accelerating to ${newSpeed}`));
对于同步的钩子,tap是仅有的添加插件的有效方法。异步钩子还支持异步插件,除了tap外,还有tapPromise,tapAsync等方法。
myCar.hooks.calculateRoutes.tapPromise("GoogleMapsPlugin", (source, target, routesList) => {
// 谷歌的找路线的异步方法返回promise
return google.maps.findRoute(source, target).then(route => {
routesList.add(route);
});
});
myCar.hooks.calculateRoutes.tapAsync("BingMapsPlugin", (source, target, routesList, callback) => {
// bing的找路线异步方法用的callback方式
bing.findRoute(source, target, (err, route) => {
if(err) return callback(err);
routesList.add(route);
// call the callback
callback();
});
});
// 异步钩子也可以使用同步方法,比如下例取出缓存的版本
myCar.hooks.calculateRoutes.tap("CachedRoutesPlugin", (source, target, routesList) => {
const cachedRoute = cache.get(source, target);
if(cachedRoute)
routesList.add(cachedRoute);
})
然后声明了这些钩子的类需要用他们时:
class Car {
/* 我作为一辆车,我只在乎我有以下功能,但这些功能的具体实现交给了第三方,
* 我给这些第三方提供能修改逻辑的权限就好了 */
setSpeed(newSpeed) {
// 下面的call没有返回值
this.hooks.accelerate.call(newSpeed);
}
useNavigationSystemPromise(source, target) {
const routesList = new List();
return this.hooks.calculateRoutes.promise(source, target, routesList).then((res) => {
// res是undefined
return routesList.getRoutes();
});
}
useNavigationSystemAsync(source, target, callback) {
const routesList = new List();
this.hooks.calculateRoutes.callAsync(source, target, routesList, err => {
if(err) return callback(err);
callback(null, routesList.getRoutes());
});
}
}
(注:此处例子用的是SyncHook和AsyncParallelHook, 所以他们是没有返回值的,即使你返回了也只能得到undefined。要想得到返回值请用SyncWaterfallHook和AsyncSeriesWaterfallHook!而且注意waterfall钩子总会返回值(即使你不return))
我们会用最高效的方式编译一个运行你提供的插件的方法,生成的代码取决于:
- 注册插件的数量(0,1,多个)
- 注册插件的类型(同步,异步回调,异步promise)
- 使用的调用方法(call, promise,callAsync)
- 参数的数量
- 是否用拦截器
这点特性保证了最快的执行。
钩子类型
每个钩子可以关联多个函数,它们怎么执行取决于钩子类型:
- 基础钩子(名字里没有waterfall, bail, loop的):这种钩子简单地按顺序调用每个添加的函数。
- 瀑布钩子(waterfall):也会按顺序调用函数,不同的是,他会传递每个函数的返回值到下一个函数。如果你不显式地return值,那么函数会返回你的第一个参数当返回值,所以记得总要返回一个值(我会return 'defined';)!
- 早退钩子(bail):当有任何添加的函数返回了任何值,这种钩子就会停止执行后面的函数。
- 循环钩子(loop):还在开发中...
另外钩子还分为同步或异步:
- 同步(sync):同步钩子只能添加同步函数(使用myHook.tap())
- 异步序列(AsyncSeries):可以添加同步方法,基于回调的异步方法,基于promise的异步方法(使用.tap(), .tapAsync(), .tapPromise())。按出现的顺序调用添加的异步方法。
- 异步平行(AsyncParallel):跟上面一样,只不过并发的调用添加的异步方法。
你可以通过这些钩子类的名字判断他们的模型, 比如AsyncSeriesWaterfallHook代表按顺序执行异步方法,并且按顺序传递返回值。
拦截器
所有的钩子都提供拦截器接口:
myCar.hooks.calculateRoutes.intercept({
call: (source, target, routesList) => {
console.log("Starting to calculate routes");
},
register: (tapInfo) => {
// tapInfo = { type: "promise", name: "GoogleMapsPlugin", fn: ... }
console.log(`${tapInfo.name} is doing its job`);
return tapInfo; // may return a new tapInfo object
}
})
call:(...args) => void 当你的钩子被触发时,拦截器里面的call方法就被触发,此时你可以访问到钩子的参数。
tap:(tap: Tap) => void 当你的自定义插件被添加进钩子时触发,此时你可以访问这个tap对象,但只读。
register: (tap: Tap) => Tap | undefined 当你的自定义插件被添加进钩子时触发,此时你可以访问这个tap对象,可修改并返回新的tap对象。
loop: (...args) => void 循环钩子的每个循环都会被触发。
上下文
插件和拦截器可以可选地访问上下文对象context,它可以被用来传递任意值给后面的插件或者拦截器。
myCar.hooks.accelerate.intercept({
context: true,
tap: (context, tapInfo) => {
// tapInfo = { type: "sync", name: "NoisePlugin", fn: ... }
console.log(`${tapInfo.name} is doing it's job`);
// `context` 从一个空对象开始如果至少有一个插件里写了 `context: true`.
// 如果没有插件定义 `context: true`, 那么 `context` 是 undefined.
if (context) {
// 你可以添加任意值,之后的插件都能访问到.
context.hasMuffler = true;
}
}
});
myCar.hooks.accelerate.tap({
name: "NoisePlugin",
context: true
}, (context, newSpeed) => {
if (context && context.hasMuffler) {
console.log("Silence...");
} else {
console.log("Vroom!");
}
});
HookMap
这是一个钩子的字典帮助类,比起你直接用js的字典类new Map([['key', hook]]),这个类可能用起来更简单:
const keyedHook = new HookMap(key => new SyncHook(["arg"]))
keyedHook.tap("some-key", "MyPlugin", (arg) => { /* ... */ });
keyedHook.tapAsync("some-key", "MyPlugin", (arg, callback) => { /* ... */ });
keyedHook.tapPromise("some-key", "MyPlugin", (arg) => { /* ... */ });
const hook = keyedHook.get("some-key");
if(hook !== undefined) {
hook.callAsync("arg", err => { /* ... */ });
}
Hook/HookMap接口
公有的
interface Hook {
tap: (name: string | Tap, fn: (context?, ...args) => Result) => void,
tapAsync: (name: string | Tap, fn: (context?, ...args, callback: (err, result: Result) => void) => void) => void,
tapPromise: (name: string | Tap, fn: (context?, ...args) => Promise<Result>) => void,
intercept: (interceptor: HookInterceptor) => void
}
interface HookInterceptor {
call: (context?, ...args) => void,
loop: (context?, ...args) => void,
tap: (context?, tap: Tap) => void,
register: (tap: Tap) => Tap,
context: boolean
}
interface HookMap {
for: (key: any) => Hook,
tap: (key: any, name: string | Tap, fn: (context?, ...args) => Result) => void,
tapAsync: (key: any, name: string | Tap, fn: (context?, ...args, callback: (err, result: Result) => void) => void) => void,
tapPromise: (key: any, name: string | Tap, fn: (context?, ...args) => Promise<Result>) => void,
intercept: (interceptor: HookMapInterceptor) => void
}
interface HookMapInterceptor {
factory: (key: any, hook: Hook) => Hook
}
interface Tap {
name: string,
type: string
fn: Function,
stage: number,
context: boolean
}
protected(定义钩子的类才能用的)
interface Hook {
isUsed: () => boolean,
call: (...args) => Result,
promise: (...args) => Promise<Result>,
callAsync: (...args, callback: (err, result: Result) => void) => void,
}
interface HookMap {
get: (key: any) => Hook | undefined,
for: (key: any) => Hook
}
MultiHook类
这是一个像钩子的类,用来重定向钩子的插件到其他钩子:
const { MultiHook } = require("tapable");
this.hooks.allHooks = new MultiHook([this.hooks.hookA, this.hooks.hookB]);