如果通过 HotModuleReplacementPlugin
启用了 模块热替换 (Hot Module Replacement),其接口将通过 module.hot
属性以及 import.meta.webpackHot
属性暴露。请注意,只有 import.meta.webpackHot
可以在 严格 ESM 中使用。
通常,用户会检查接口是否可访问,然后开始使用它。例如,以下是您如何 accept
更新的模块的方法
if (module.hot) {
module.hot.accept('./library.js', function () {
// Do something with the updated library module...
});
}
// or
if (import.meta.webpackHot) {
import.meta.webpackHot.accept('./library.js', function () {
// Do something with the updated library module…
});
}
支持以下方法...
接受给定 dependencies
的更新,并触发 callback
以响应这些更新,此外,您还可以附加一个可选的错误处理程序
module.hot.accept(
dependencies, // Either a string or an array of strings
callback, // Function to fire when the dependencies are updated
errorHandler // (err, {moduleId, dependencyId}) => {}
);
// or
import.meta.webpackHot.accept(
dependencies, // Either a string or an array of strings
callback, // Function to fire when the dependencies are updated
errorHandler // (err, {moduleId, dependencyId}) => {}
);
当使用 ESM import
时,从 dependencies
导入的所有符号都会自动更新。注意:依赖字符串必须与 import
中的 from
字符串完全匹配。在某些情况下,甚至可以省略 callback
。在这里,在 callback
中使用 require()
没有意义。
当使用 CommonJS 时,您需要在 callback
中使用 require()
手动更新依赖。在这里,省略 callback
没有意义。
(err, {moduleId, dependencyId}) => {}
err
:在 ESM 依赖执行时,回调函数中抛出的错误或在依赖执行过程中抛出的错误。moduleId
:当前模块 ID。dependencyId
:(第一个) 更改的依赖模块 ID。接受自身的更新。
module.hot.accept(
errorHandler // Function to handle errors when evaluating the new version
);
// or
import.meta.webpackHot.accept(
errorHandler // Function to handle errors when evaluating the new version
);
当此模块或依赖项更新时,此模块可以被处理并重新评估,而无需通知父级。如果此模块没有导出(或以其他方式更新了导出),则这样做是有意义的。
当此模块(或依赖项)的评估抛出异常时,将触发 errorHandler
。
(err, {moduleId, module}) => {}
err
:评估新版本时发生的错误。moduleId
:当前模块 ID。module
:当前模块实例。
module.hot
:允许使用出错模块实例的 HMR API。常见情况是再次自身接受它。添加处理处理程序来传递数据也是有意义的。请注意,出错的模块可能已经部分执行,因此请确保不要进入不一致的状态。您可以使用 module.hot.data
存储部分状态。module.exports
:可以被覆盖,但请小心,因为在生产模式下属性名可能会被混淆。拒绝给定 dependencies
的更新,强制更新以 'decline'
代码失败。
module.hot.decline(
dependencies // Either a string or an array of strings
);
// or
import.meta.webpackHot.decline(
dependencies // Either a string or an array of strings
);
将依赖标记为不可更新。当此依赖的导出更改无法处理或尚未实现处理时,这样做是有意义的。根据您的 HMR 管理代码,对这些依赖(或其未接受的依赖)的更新通常会导致页面完全重新加载。
拒绝自身的更新。
module.hot.decline();
// or
import.meta.webpackHot.decline();
将此模块标记为不可更新。当此模块具有不可逆的副作用,或者尚未为此模块实现 HMR 处理时,这样做是有意义的。根据您的 HMR 管理代码,对此模块(或未接受的依赖项)的更新通常会导致页面完全重新加载。
添加一个处理程序,当当前模块代码被替换时执行。这应该用于移除您已声明或创建的任何持久资源。如果您想将状态转移到更新的模块,请将其添加到给定的 data
参数中。此对象将在更新后通过 module.hot.data
可用。
module.hot.dispose((data) => {
// Clean up and pass data to the updated module...
});
// or
import.meta.webpackHot.dispose((data) => {
// Clean up and pass data to the updated module...
});
调用此方法将使当前模块失效,这会在应用 HMR 更新时处理并重新创建它。这就像此模块的正常更新一样传播。此模块不能自身接受 invalidate
。
在 idle
状态下调用时,将创建包含此模块的新 HMR 更新。HMR 将进入 ready
状态。
在 ready
或 prepare
状态下调用时,此模块将被添加到当前 HMR 更新中。
在 check
状态下调用时,当有更新可用时,此模块将被添加到更新中。如果没有更新可用,它将创建新更新。HMR 将进入 ready
状态。
在 dispose
或 apply
状态下调用时,HMR 将在退出这些状态后接收它。
条件接受
一个模块可以接受一个依赖,但当依赖的更改无法处理时,可以调用 invalidate
。
import { x, y } from './dep';
import { processX, processY } from 'anotherDep';
const oldY = y;
processX(x);
export default processY(y);
module.hot.accept('./dep', () => {
if (y !== oldY) {
// This can't be handled, bubble to parent
module.hot.invalidate();
return;
}
// This can be handled
processX(x);
});
条件自身接受
一个模块可以自身接受,但当更改无法处理时,可以使自身失效。
const VALUE = 'constant';
export default VALUE;
if (
module.hot.data &&
module.hot.data.value &&
module.hot.data.value !== VALUE
) {
module.hot.invalidate();
} else {
module.hot.dispose((data) => {
data.value = VALUE;
});
module.hot.accept();
}
触发自定义 HMR 更新
const moduleId = chooseAModule();
const code = __webpack_modules__[moduleId].toString();
__webpack_modules__[moduleId] = eval(`(${makeChanges(code)})`);
if (require.cache[moduleId]) {
require.cache[moduleId].hot.invalidate();
module.hot.apply();
}
移除通过 dispose
或 addDisposeHandler
添加的处理程序。
module.hot.removeDisposeHandler(callback);
// or
import.meta.webpackHot.removeDisposeHandler(callback);
检索热模块替换过程的当前状态。
module.hot.status(); // Will return one of the following strings...
// or
import.meta.webpackHot.status();
状态 | 描述 |
---|---|
空闲 | 进程正在等待调用 check |
检查 | 进程正在检查更新 |
准备 | 进程正在为更新做准备(例如下载更新的模块) |
就绪 | 更新已准备就绪并可用 |
处理 | 进程正在对将被替换的模块调用 dispose 处理程序 |
应用 | 进程正在调用 accept 处理程序并重新执行自身接受的模块 |
中止 | 更新已中止,但系统仍处于其先前的状态 |
失败 | 更新抛出了异常,系统状态已受损 |
测试所有已加载模块的更新,如果存在更新,则 apply
它们。
module.hot
.check(autoApply)
.then((outdatedModules) => {
// outdated modules...
})
.catch((error) => {
// catch errors
});
// or
import.meta.webpackHot
.check(autoApply)
.then((outdatedModules) => {
// outdated modules...
})
.catch((error) => {
// catch errors
});
autoApply
参数可以是布尔值,也可以是调用 apply
方法时传递的 options
。
继续更新过程(只要 module.hot.status() === 'ready'
)。
module.hot
.apply(options)
.then((outdatedModules) => {
// outdated modules...
})
.catch((error) => {
// catch errors
});
// or
import.meta.webpackHot
.apply(options)
.then((outdatedModules) => {
// outdated modules...
})
.catch((error) => {
// catch errors
});
可选的 options
对象可以包含以下属性
ignoreUnaccepted
(布尔值):忽略对未接受模块的更改。ignoreDeclined
(布尔值):忽略对拒绝模块的更改。ignoreErrored
(布尔值):忽略在接受处理程序、错误处理程序中以及重新评估模块时抛出的错误。onDeclined
(函数(info)):拒绝模块的通知器onUnaccepted
(函数(info)):未接受模块的通知器onAccepted
(函数(info)):接受模块的通知器onDisposed
(函数(info)):已处理模块的通知器onErrored
(函数(info)):错误的通知器info
参数将是一个包含以下部分值的对象
{
type: 'self-declined' | 'declined' |
'unaccepted' | 'accepted' |
'disposed' | 'accept-errored' |
'self-accept-errored' | 'self-accept-error-handler-errored',
moduleId: 4, // The module in question.
dependencyId: 3, // For errors: the module id owning the accept handler.
chain: [1, 2, 3, 4], // For declined/accepted/unaccepted: the chain from where the update was propagated.
parentId: 5, // For declined: the module id of the declining parent
outdatedModules: [1, 2, 3, 4], // For accepted: the modules that are outdated and will be disposed
outdatedDependencies: { // For accepted: The location of accept handlers that will handle the update
5: [4]
},
error: new Error(...), // For errors: the thrown error
originalError: new Error(...) // For self-accept-error-handler-errored:
// the error thrown by the module before the error handler tried to handle it.
}
注册一个函数来监听 status
的变化。
module.hot.addStatusHandler((status) => {
// React to the current status...
});
// or
import.meta.webpackHot.addStatusHandler((status) => {
// React to the current status...
});
请记住,当状态处理程序返回 Promise
时,HMR 系统将等待 Promise
解析后才会继续。
移除一个已注册的状态处理程序。
module.hot.removeStatusHandler(callback);
// or
import.meta.webpackHot.removeStatusHandler(callback);