load(url, context, nextLoad)
加载器 API 正在重新设计。 这个钩子可能会消失,或者它的签名可能会改变。 不要依赖下面描述的 API。
在此 API 的先前版本中,它被拆分为 3 个单独的、现已弃用的钩子(
getFormat
、getSource
和transformSource
)。
url
<string>resolve
链返回的 URLcontext
<Object>conditions
<string[]> 相关package.json
的导出条件format
<string> | <null> | <undefined>resolve
钩子链可选提供的格式importAssertions
<Object>
nextLoad
<Function> 链中后续的load
钩子,或者用户提供的最后一个load
钩子之后的 Node.js 默认load
钩子- 返回: <Object>
format
<string>shortCircuit
<undefined> | <boolean> 此钩子打算终止resolve
钩子链的信号。 默认值:false
source
<string> | <ArrayBuffer> | <TypedArray> Node.js 评估的来源
load
钩子提供了一种方式来定义确定网址应如何解释、检索、以及解析的自定义方法。
它还负责验证导入断言。
format
的最终值必须是以下之一:
format | 描述 | Acceptable types for source returned by load |
---|---|---|
'builtin' | 加载 Node.js 内置模块 | 不适用 |
'commonjs' | 加载 Node.js CommonJS 模块 | 不适用 |
'json' | 加载 JSON 文件 | { string , ArrayBuffer , TypedArray } |
'module' | 加载 ES 模块 | { string , ArrayBuffer , TypedArray } |
'wasm' | 加载 WebAssembly 模块 | { ArrayBuffer , TypedArray } |
source
的值对于类型 'builtin'
被忽略,因为目前无法替换 Node.js 内置(核心)模块的值。
source
的值对于类型 'commonjs'
被忽略,因为 CommonJS 模块加载器没有为 ES 模块加载器提供覆盖 CommonJS 模块返回值 的机制。
这个限制将来可能会被克服。
警告:ESM
load
钩子和来自 CommonJS 模块的命名空间导出不兼容。 尝试将它们一起使用将导致导入中的空对象。 这可能会在未来得到解决。
这些类型都对应于 ECMAScript 中定义的类。
- 特定的
ArrayBuffer
对象是SharedArrayBuffer
。 - 特定的
TypedArray
对象是Uint8Array
。
如果基于文本的格式(即 'json'
、'module'
)的源值不是字符串,则使用 util.TextDecoder
将其转换为字符串。
load
钩子提供了一种方法来定义用于检索 ES 模块说明符的源代码的自定义方法。
这将允许加载器潜在地避免从磁盘读取文件。
它还可以用于将无法识别的格式映射到支持的格式,例如 yaml
到 module
。
export async function load(url, context, nextLoad) {
const { format } = context;
if (Math.random() > 0.5) { // 某些条件
/*
For some or all URLs, do some custom logic for retrieving the source.
Always return an object of the form {
format: <string>,
source: <string|buffer>,
}.
*/
return {
format,
shortCircuit: true,
source: '...',
};
}
// 推迟到链中的下一个钩子。
return nextLoad(url);
}
在更高级的场景中,这也可用于将不受支持的源转换为受支持的源(请参阅下面的示例)。
The loaders API is being redesigned. This hook may disappear or its signature may change. Do not rely on the API described below.
In a previous version of this API, this was split across 3 separate, now deprecated, hooks (
getFormat
,getSource
, andtransformSource
).
url
<string> The URL returned by theresolve
chaincontext
<Object>conditions
<string[]> Export conditions of the relevantpackage.json
format
<string> | <null> | <undefined> The format optionally supplied by theresolve
hook chainimportAssertions
<Object>
nextLoad
<Function> The subsequentload
hook in the chain, or the Node.js defaultload
hook after the last user-suppliedload
hook- Returns: <Object>
format
<string>shortCircuit
<undefined> | <boolean> A signal that this hook intends to terminate the chain ofresolve
hooks. Default:false
source
<string> | <ArrayBuffer> | <TypedArray> The source for Node.js to evaluate
The load
hook provides a way to define a custom method of determining how
a URL should be interpreted, retrieved, and parsed. It is also in charge of
validating the import assertion.
The final value of format
must be one of the following:
format | Description | Acceptable types for source returned by load |
---|---|---|
'builtin' | Load a Node.js builtin module | Not applicable |
'commonjs' | Load a Node.js CommonJS module | Not applicable |
'json' | Load a JSON file | { string , ArrayBuffer , TypedArray } |
'module' | Load an ES module | { string , ArrayBuffer , TypedArray } |
'wasm' | Load a WebAssembly module | { ArrayBuffer , TypedArray } |
The value of source
is ignored for type 'builtin'
because currently it is
not possible to replace the value of a Node.js builtin (core) module. The value
of source
is ignored for type 'commonjs'
because the CommonJS module loader
does not provide a mechanism for the ES module loader to override the
CommonJS module return value. This limitation might be
overcome in the future.
Caveat: The ESM
load
hook and namespaced exports from CommonJS modules are incompatible. Attempting to use them together will result in an empty object from the import. This may be addressed in the future.
These types all correspond to classes defined in ECMAScript.
- The specific
ArrayBuffer
object is aSharedArrayBuffer
. - The specific
TypedArray
object is aUint8Array
.
If the source value of a text-based format (i.e., 'json'
, 'module'
)
is not a string, it is converted to a string using util.TextDecoder
.
The load
hook provides a way to define a custom method for retrieving the
source code of an ES module specifier. This would allow a loader to potentially
avoid reading files from disk. It could also be used to map an unrecognized
format to a supported one, for example yaml
to module
.
export async function load(url, context, nextLoad) {
const { format } = context;
if (Math.random() > 0.5) { // Some condition
/*
For some or all URLs, do some custom logic for retrieving the source.
Always return an object of the form {
format: <string>,
source: <string|buffer>,
}.
*/
return {
format,
shortCircuit: true,
source: '...',
};
}
// Defer to the next hook in the chain.
return nextLoad(url);
}
In a more advanced scenario, this can also be used to transform an unsupported source to a supported one (see Examples below).