這纔是官方的tapable中文文檔

原由

搜索引擎搜索tapable中文文檔,你會看見各類翻譯,點進去一看,確實是官方的文檔翻譯過來的,可是webpack的文檔確實還有不少須要改進的地方,既然是開源的爲何不去github上的tapable庫看呢,一看,確實,比webpack文檔上的描述得清楚得多.

tapable 是一個相似於nodejs 的EventEmitter 的庫, 主要是控制鉤子函數的發佈與訂閱,控制着webpack的插件系.webpack的本質就是一系列的插件運行.

Tapable

Tapable庫 提供了不少的鉤子類, 這些類能夠爲插件建立鉤子

const {
    SyncHook,
    SyncBailHook,
    SyncWaterfallHook,
    SyncLoopHook,
    AsyncParallelHook,
    AsyncParallelBailHook,
    AsyncSeriesHook,
    AsyncSeriesBailHook,
    AsyncSeriesWaterfallHook
 } = require("tapable");

安裝

npm install --save tapable

使用

全部的鉤子構造函數,都接受一個可選的參數,(這個參數最好是數組,不是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();

// Use the tap method to add a consument
// 使用tap 方法添加一個消費者,(生產者消費者模式)
myCar.hooks.brake.tap("WarningLampPlugin", () => warningLamp.on());

這須要你傳一個名字去標記這個插件:

你能夠接收參數

myCar.hooks.accelerate.tap("LoggerPlugin", newSpeed => console.log(`Accelerating to ${newSpeed}`));

在同步鉤子中, tap 是惟一的綁定方法,異步鉤子一般支持異步插件

// promise: 綁定promise鉤子的API
myCar.hooks.calculateRoutes.tapPromise("GoogleMapsPlugin", (source, target, routesList) => {
    // return a promise
    return google.maps.findRoute(source, target).then(route => {
        routesList.add(route);
    });
});
// tapAsync:綁定異步鉤子的API
myCar.hooks.calculateRoutes.tapAsync("BingMapsPlugin", (source, target, routesList, callback) => {
    bing.findRoute(source, target, (err, route) => {
        if(err) return callback(err);
        routesList.add(route);
        // call the callback
        callback();
    });
});

// You can still use sync plugins
// tap: 綁定同步鉤子的API
myCar.hooks.calculateRoutes.tap("CachedRoutesPlugin", (source, target, routesList) => {
    const cachedRoute = cache.get(source, target);
    if(cachedRoute)
        routesList.add(cachedRoute);
})

類須要調用被聲明的那些鉤子

class Car {
    /* ... */

    setSpeed(newSpeed) {    
        // call(xx) 傳參調用同步鉤子的API
        this.hooks.accelerate.call(newSpeed);
    }

    useNavigationSystemPromise(source, target) {
        const routesList = new List();
        // 調用promise鉤子(鉤子返回一個promise)的API
        return this.hooks.calculateRoutes.promise(source, target, routesList).then(() => {
            return routesList.getRoutes();
        });
    }

    useNavigationSystemAsync(source, target, callback) {
        const routesList = new List();
        // 調用異步鉤子API
        this.hooks.calculateRoutes.callAsync(source, target, routesList, err => {
            if(err) return callback(err);
            callback(null, routesList.getRoutes());
        });
    }
}

tapable會用最有效率的方式去編譯(構建)一個運行你的插件的方法,他生成的代碼依賴於一下幾點:

• 你註冊的插件的個數.
• 你註冊插件的類型.
• 你使用的調用方法(call, promise, async) // 其實這個類型已經包括了
• 鉤子參數的個數 // 就是你new xxxHook(['ooo']) 傳入的參數
• 是否應用了攔截器(攔截器下面有講)

這些肯定了儘量快的執行.

鉤子類型

每個鉤子均可以tap 一個或者多個函數, 他們如何運行,取決於他們的鉤子類型

• 基本的鉤子, (鉤子類名沒有waterfall, Bail, 或者 Loop 的 ), 這個鉤子只會簡單的調用每一個tap進去的函數
• Waterfall, 一個waterfall 鉤子,也會調用每一個tap進去的函數,不一樣的是,他會從每個函數傳一個返回的值到下一個函數
• Bail, Bail 鉤子容許更早的退出,當任何一個tap進去的函數,返回任何值, bail類會中止執行其餘的函數執行.(相似 Promise.race())
• Loop, TODO(我.... 這裏也沒描述,應該是寫文檔得時候 還沒想好這個要怎麼寫,我嘗試看他代碼去補全,不過可能須要點時間.)

此外,鉤子能夠是同步的,也能夠是異步的,Sync, AsyncSeries 和 AsyncParallel ,從名字就能夠看出,哪些是能夠綁定異步函數的

• Sync, 一個同步鉤子只能tap同步函數, 否則會報錯.
• AsyncSeries, 一個 async-series 鉤子 能夠tap 同步鉤子, 基於回調的鉤子(我估計是相似chunk的東西)和一個基於promise的鉤子(使用myHook.tap(), myHook.tapAsync() 和 myHook.tapPromise().).他會按順序的調用每一個方法.
• AsyncParallel, 一個 async-parallel 鉤子跟上面的 async-series 同樣 不一樣的是他會把異步鉤子並行執行(並行執行就是把異步鉤子所有一塊兒開啓,不按順序執行).

攔截器(interception)

全部鉤子都提供額外的攔截器API

// 註冊一個攔截器
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 每一個鉤子執行以前(多個鉤子執行多個),就會觸發這個函數

loop:(...args) => void 這個會爲你的每個循環鉤子(LoopHook, 就是類型到Loop的)觸發,具體何時沒說

register:(tap: Tap) => Tap | undefined 每添加一個Tap都會觸發 你interceptor上的register,你下一個攔截器的register 函數獲得的參數 取決於你上一個register返回的值,因此你最好返回一個 tap 鉤子.

Context(上下文)

插件和攔截器均可以選擇加入一個可選的 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` starts as an empty object if at least one plugin uses `context: true`.
        // 若是最少有一個插件使用 `context` 那麼context 一開始是一個空的對象
        // If no plugins use `context: true`, then `context` is undefined
        // 如過tap進去的插件沒有使用`context` 的 那麼內部的`context` 一開始就是undefined
        if (context) {
            // Arbitrary properties can be added to `context`, which plugins can then access.    
            // 任意屬性均可以添加到`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

一個 HookMap是一個Hooks映射的幫助類

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 => { /* ... */ });
}

鉤子映射接口(HookMap interface)

Public(權限公開的):

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

把其餘的Hook 重定向(轉化)成爲一個 MultiHook

const { MultiHook } = require("tapable");

this.hooks.allHooks = new MultiHook([this.hooks.hookA, this.hooks.hookB]);

OK 全部的內容我都已翻譯完成.

其中有不少不是直譯,這樣寫下來感受就是按照原文的脈絡從新寫了一遍....,應該能更清楚明白,要不是怕丟臉我就給個原創了,哈哈.

以後, 我還會寫一篇完整的原創解析,直擊源碼,搞定tapable, 徹底瞭解webpack插件系統(webpack原本就是一個插件的事件流), 很久沒寫原創了. 我本身也很期待.