webpack入门（七） API in LOADERS

介绍

loaders允许你用require() 预处理文件（preprocess files）或者加载他们，在其他的构建工具中，loaders就是一种像“任务（tasks）”的东西。他提供了一种处理前端构建的强大的方式。loaders可以从不同语言类型的文件来转换文件，比如coffeescript，内联image的data url。loaders甚至允许你在你的js文件中用require()加载css文件。

让webpack用loader转换一个模块，你可以指定模块需要的loader，就像在require（）的调用。

var moduleWithOneLoader = require("my-loader!./my-awesome-module");

注意，！语法将loader从模块路径中分离开。loaders像模块一样可以指定一个相对路径，而不是它的loader名。

require("./loaders/my-loader!./my-awesome-module");

loaders可以被链式调用并用！分割开。这有利于在管道中转换多个文件

require("style-loader!css-loader!less-loader!./my-styles.less");

当使用链式调用的时候，loaders会被从右到左的应用。在上面的例子中，my-styles.less会首先被less-loader转换为css文件。然后被传入到css-loader中处理url，字体和一些其他资源。最后被传入到style-loader中转换成script标签。

参数

loaders可以接受查询字符串。

require("loader?with=parameter!./file");

查询字符串的格式取决于loaders，所以去文档里查找该loaders接受的查询字符串的格式。通常大部分loaders接受传统的查询字符串格式。

loaders的配置

每个模块具体的loaders都可以重复（brittle and repetitive），webpack提供了一个在webpack配置文件中指定那个loaders应用于不用同文件类型的方式。在大多数情况下，推荐（recommended ）在配置中指定，因为它不会在代码中添加任何特定的语法，使其更可重用（reusable）。

{
    module: {
        loaders: [
            { test: /.coffee$/, loader: "coffee-loader" }
        ],
        preLoaders: [
            { test: /.coffee$/, loader: "coffee-hint-loader" }
        ]
    }
};

See the configuration page for more information about configuring loaders. 查看配置页得到关于配置loaders的更多信息。<-点击

loader的顺序

文件在文件系统中读取后，loaders按下列顺序执行。

preloaders specified in the configuration
loaders specified in the configuration
loaders specified in the request (e.g. require('raw!./file.js'))
postLoaders specified in the configuration

您还可以重写模块请求中的配置加载程序以适应特定的情况。

　　在一个请求中添加!!将禁用在配置中指定的所有loaders

　　　　require("!raw!./script.coffee")

　　在一个请求中添加!!将禁用在配置中指定的所有loaders

　　　　require("!!raw!./script.coffee")

　　在一个请求中添加-!将会禁用配置中的preLoaders和loaders但是不禁用postLoaders

　　　　require("-!raw!./script.coffee")

编写loaders

写一个loaders相当简单，一个loader就是一个导出函数的一个文件。编译器调用这个函数，传入上一个的loader的结果或者源文件，这个函数的this上下文被编译器填充了一些允许loader做的有用的方法，在其他方面，改用异步调用方式和得到查询查询字符串，第一个loader被传入一个参数:源文件的内容。编译器期望从最后一个loader得到一个结果，结果应该为一个字符串或者一个buffer（被字符串转换而来），代表模块的js源码。SourceMap的结果（作为JSON对象）可选的被传入。一个单一的结果必须同步返回，多结果的回调函数（this.callback ）必须被调用，异步模式下，this.async() 必须被调用，它返回this.callback。然后loader必须返回undefined并调用回调。

错误可以被同步模式抛出或者调用它的回调函数传入错误

webpack在任何情况下都允许异步模式。

enhanced-require仅在require.ensure或者AMD加载的时候允许异步模式。

更详细的说明和指南，check out How to write a loader.

例子

同步loader

module.exports = function(content) {
    return someSyncOperation(content);
};

异步loader

module.exports = function(content) {
    var callback = this.async();
    if(!callback) return someSyncOperation(content);
    someAsyncOperation(content, function(err, result) {
        if(err) return callback(err);
        callback(null, result);
    });
};

注意:建议给一个异步loader回落到同步模式的模式。不需要webpack但允许用enhanced-require运行同步的loader

raw loader

默认的源文件会作为utf-8编码的字符串被传入到loader，设置raw为true，loader就会作为原Buffer被传入。

每个loader都允许把结果作为字符串或者作为Buffer，编译器会在loader间转换他们。

module.exports = function(content) {
    assert(content instanceof Buffer);
    return someSyncOperation(content);
    // return value can be a Buffer too
    // This is also allowed if loader is not "raw"
};
module.exports.raw = true;

pitching loader

这些loaders被从右到左被调用。但有些时候，这些loaders不关心这些结果是来自上一个loader还是文件，他们只关心元数据（metadata）；loader的 pitch方法会在loaders被调用之前被从左到右的调用，如果一个loader用pitch方法提供了结果，程序就会回转并跳过剩下的loaders，继续调用更多的左边的loaders。数据可以在 pitch和普通调用间传递。

module.exports = function(content) {
    return someSyncOperation(content, this.data.value);
};
module.exports.pitch = function(remainingRequest, precedingRequest, data) {
    if(someCondition()) {
        // fast exit
        return "module.exports = require(" + JSON.stringify("-!" + remainingRequest) + ");";
    }
    data.value = 42;
};

loader context

这些东西（stuff）在loader的this上是可用的。例如，这需要调用：

/abc/file.js:

require("./loader1?xyz!loader2!./resource?rrr");

版本

loader api的版本，当前1。

内容

字符串，模块的目录，可以用作解决其他问题的上下文。

在这个例子中：/abc因为resource.js 在目录里。（/abc because resource.js is in this directory）

`request`

The resolved request string.

In the example: "/abc/loader1.js?xyz!/abc/node_modules/loader2/index.js!/abc/resource.js?rrr"

`query`

A string. The query of the request for the current loader.

In the example: in loader1: "?xyz", in loader2: ""

`data`

A data object shared between the pitch and the normal phase.

`cacheable`

cacheable(flag = true: boolean)

Make this loader result cacheable. By default it’s not cacheable.

A cacheable loader must have a deterministic result, when inputs and dependencies haven’t changed. This means the loader shouldn’t have other dependencies than specified with this.addDependency. Most loaders are deterministic and cacheable.

`loaders`

loaders = [{request: string, path: string, query: string, module: function}]

An array of all the loaders. It is writeable in the pitch phase.

In the example:

[
  { request: "/abc/loader1.js?xyz",
    path: "/abc/loader1.js",
    query: "?xyz",
    module: [Function]
  },
  { request: "/abc/node_modules/loader2/index.js",
    path: "/abc/node_modules/loader2/index.js",
    query: "",
    module: [Function]
  }
]

`loaderIndex`

The index in the loaders array of the current loader.

In the example: in loader1: 0, in loader2: 1

`resource`

The resource part of the request, including query.

In the example: "/abc/resource.js?rrr"

`resourcePath`

The resource file.

In the example: "/abc/resource.js"

`resourceQuery`

The query of the resource.

In the example: "?rrr"

`emitWarning`

emitWarning(message: string)

Emit a warning.

`emitError`

emitError(message: string)

Emit an error.

`exec`

exec(code: string, filename: string)

Execute some code fragment like a module.

Hint: Don’t use require(this.resourcePath), use this function to make loaders chainable!

`resolve`

resolve(context: string, request: string, callback: function(err, result: string))

Resolve a request like a require expression.

`resolveSync`

resolveSync(context: string, request: string) -> string

Resolve a request like a require expression.

`addDependency`

addDependency(file: string)
dependency(file: string) // shortcut

Add a file as dependency of the loader result.

`addContextDependency`

addContextDependency(directory: string)

Add a directory as dependency of the loader result.

`clearDependencies`

clearDependencies()

Remove all dependencies of the loader result. Even initial dependencies and these of other loaders. Consider using pitch.

`values` (out)

Pass values to the next loaders inputValues. If you know what your result exports if executed as module, set this value here (as a only element array).

`inputValues`

Passed from the last loader. If you would execute the input argument as module, consider reading this variable for a shortcut (for performance).

`options`

The options passed to the Compiler.

`debug`

A boolean flag. It is set when in debug mode.

`minimize`

Should the result be minimized.

`sourceMap`

Should a SourceMap be generated.

`target`

Target of compilation. Passed from configuration options.

Example values: "web", "node"

`webpack`

Set to true when this is compiled by webpack.

`emitFile`

emitFile(name: string, content: Buffer|String, sourceMap: {...})

Emit a file. This is webpack-specific

`_compilation`

Hacky access to the Compilation object of webpack.

`_compiler`

Hacky access to the Compiler object of webpack.