Inside Tasks

在任务运行期间，Grunt 通过 this 对象在任务函数内部公开了许多任务特定的实用属性和方法。这个对象也作为 grunt.task.current 暴露出来，以便在模板中使用，例如，属性 this.name 也可以作为 grunt.task.current.name 访问。

所有任务内部

this.async

如果任务是异步的，必须调用此方法来指示 Grunt 等待。它返回一个"done"函数的句柄，当任务完成时应调用该函数。可以向 done 函数传递 false 或 Error 对象，以指示 Grunt 任务已失败。

如果没有调用 this.async 方法，任务将同步执行。

// 告诉 Grunt 这个任务是异步的。
var done = this.async();
// 您的异步代码。
setTimeout(function() {
  // 模拟有时会出错。
  var success = Math.random() > 0.5;
  // 全部完成！
  done(success);
}, 1000);

this.requires

如果一个任务依赖于另一个任务（或多个任务）的成功完成，可以使用此方法强制 Grunt 在其他任务未运行或失败时中止。任务列表可以是任务名称数组或单个任务名称参数。

请注意，这不会实际运行指定的任务，只是在它们尚未成功运行时使当前任务失败。

this.requires(tasksList)

this.requiresConfig

如果缺少一个或多个必需的配置属性，则使当前任务失败。可以指定一个或多个字符串或数组配置属性。

this.requiresConfig(prop [, prop [, ...]])

有关配置属性的更多信息，请参见 grunt.config 文档。

此方法是 grunt.config.requires 方法的别名。

this.name

任务的名称，如在 grunt.registerTask 中定义。例如，如果一个 "sample" 任务以 grunt sample 或 grunt sample:foo 运行，在任务函数内部，this.name 将是 "sample"。

注意，如果任务已使用 grunt.task.renameTask 重命名，此属性将反映新名称。

this.nameArgs

任务的名称，包括在命令行上指定的任何冒号分隔的参数或标志。例如，如果一个 "sample" 任务以 grunt sample:foo 运行，在任务函数内部，this.nameArgs 将是 "sample:foo"。

注意，如果任务已使用 grunt.task.renameTask 重命名，此属性将反映新名称。

this.args

传递给任务的参数数组。例如，如果一个 "sample" 任务以 grunt sample:foo:bar 运行，在任务函数内部，this.args 将是 ["foo", "bar"]。

注意，在多任务中，当前目标从 this.args 数组中省略。

this.flags

从传递给任务的参数生成的对象。例如，如果一个 "sample" 任务以 grunt sample:foo:bar 运行，在任务函数内部，this.flags 将是 {foo: true, bar: true}。

注意，在多任务中，目标名称不设置为标志。

this.errorCount

在此任务期间发生的 grunt.log.error 调用的数量。这可用于在任务期间记录错误时使任务失败。

this.options

返回一个选项对象。可选参数 defaultsObj 的属性将被任务级别 options 对象的属性覆盖，在多任务中，目标级别 options 对象的属性将进一步覆盖。

this.options([defaultsObj])

这个示例展示了任务如何使用 this.options 方法：

var options = this.options({
  enabled: false,
});

doSomething(options.enabled);

配置任务指南从任务用户的角度展示了如何指定选项的示例。

多任务内部

this.target

在多任务中，此属性包含当前正在迭代的目标的名称。例如，如果一个 "sample" 多任务以 grunt sample:foo 运行，配置数据为 {sample: {foo: "bar"}}，在任务函数内部，this.target 将是 "foo"。

this.files

在多任务中，使用任何 Grunt 支持的文件格式和选项、通配符模式或动态映射指定的所有文件将自动标准化为单一格式：文件数组文件格式。

这意味着任务不需要包含大量样板代码来显式处理自定义文件格式、通配符模式、将源文件映射到目标文件或过滤文件或目录。任务用户只需按照配置任务指南指定文件，Grunt 将处理所有细节。

您的任务应遍历 this.files 数组，利用该数组中每个对象的 src 和 dest 属性。this.files 属性将始终是一个数组。src 属性也将始终是一个数组，以防您的任务关心每个目标文件的多个源文件。

请注意，src 值中可能包含不存在的文件，因此您可能需要在使用它们之前显式测试源文件是否存在。

这个示例展示了一个简单的 "concat" 任务如何使用 this.files 属性：

this.files.forEach(function(file) {
  var contents = file.src.filter(function(filepath) {
    // 删除不存在的文件（由您决定是否过滤或警告）。
    if (!grunt.file.exists(filepath)) {
      grunt.log.warn('Source file "' + filepath + '" not found.');
      return false;
    } else {
      return true;
    }
  }).map(function(filepath) {
    // 读取并返回文件的源。
    return grunt.file.read(filepath);
  }).join('\n');
  // 将连接的内容写入目标文件路径。
  grunt.file.write(file.dest, contents);
  // 打印成功消息。
  grunt.log.writeln('File "' + file.dest + '" created.');
});

如果您需要原始文件对象属性，它们在每个单独的文件对象的 orig 属性下可用，但目前尚不清楚访问原始属性的用例。

this.filesSrc

在多任务中，通过任何文件格式指定的所有 src 文件都缩减为单个数组。如果您的任务是"只读"且不关心目标文件路径，请使用此数组而不是 this.files。

这个示例展示了一个简单的 "lint" 任务如何使用 this.filesSrc 属性：

// 检查指定文件。
var files = this.filesSrc;
var errorCount = 0;
files.forEach(function(filepath) {
  if (!lint(grunt.file.read(filepath))) {
    errorCount++;
  }
});

// 如果记录了错误，则使任务失败。
if (errorCount > 0) { return false; }

// 否则，打印成功消息。
grunt.log.ok('Files lint free: ' + files.length);

this.data

在多任务中，这是给定目标在 Grunt 配置对象中存储的实际数据。 例如，如果一个 "sample" 多任务以 grunt sample:foo 运行，配置数据为 {sample: {foo: "bar"}}，在任务函数内部，this.data 将是 "bar"。

建议使用 this.options、this.files 和 this.filesSrc，而不是 this.data，因为它们的值是标准化的。