grunt.task

注册、运行和加载外部任务。

有关更多信息,请查看 任务库源代码任务实用工具库源代码

任务 API

在任务运行期间,Grunt 通过 this 对象在任务函数内部公开了许多特定于任务的实用属性和方法。请参见 任务内部 指南,了解这些属性和方法的列表。

许多实用属性和方法可以在任务内部通过 this 对象使用。

请注意,任何标有 ☃(unicode 雪人)的方法也可以直接在 grunt 对象上使用。仅供参考。请参见 API 主页 以获取更多使用信息。

创建任务

grunt.task.registerTask ☃

注册一个"别名任务"或任务函数。此方法支持以下两种签名:

别名任务

如果指定了任务列表,则新任务将是一个或多个其他任务的别名。每当运行这个"别名任务"时,taskList 中指定的每个任务都将按指定顺序运行。taskList 参数必须是任务数组。

grunt.task.registerTask(taskName, taskList)

当传递可选的 description 字符串时,它将在运行 grunt --help 时显示:

grunt.task.registerTask(taskName, description, taskList)

此示例别名任务定义了一个"default"任务,如果执行 Grunt 时没有指定任何任务,则自动运行"jshint"、"qunit"、"concat"和"uglify"任务:

task.registerTask('default', ['jshint', 'qunit', 'concat', 'uglify']);

还可以指定任务参数。在此示例中,别名"dist"运行"concat"和"uglify"任务,每个任务都带有"dist"参数:

task.registerTask('dist', ['concat:dist', 'uglify:dist']);

函数任务

如果传递了 descriptiontaskFunction,则每当运行该任务时都会执行指定的函数。此外,指定的描述将在运行 grunt --help 时显示。任务特定的属性和方法在任务函数内部作为 this 对象的属性可用。如果任务函数返回 false,则表示任务已失败。

请注意,下面解释的 grunt.task.registerMultiTask 方法可用于定义一种称为"多任务"的特殊任务类型。

grunt.task.registerTask(taskName, description, taskFunction)

如果通过 grunt foo:testing:123 运行 Grunt,此示例任务将记录 foo, testing 123。如果不带参数运行任务 grunt foo,则任务记录 foo, no args

grunt.task.registerTask('foo', 'A sample task that logs stuff.', function(arg1, arg2) {
  if (arguments.length === 0) {
    grunt.log.writeln(this.name + ", no args");
  } else {
    grunt.log.writeln(this.name + ", " + arg1 + " " + arg2);
  }
});

请参见 创建任务 文档,了解更多任务和别名任务的示例。

此方法也可作为 grunt.registerTask 使用。

grunt.task.registerMultiTask ☃

注册一个"多任务"。多任务是一种任务,如果未指定目标,则隐式迭代其所有命名子属性(又称目标)。除了默认属性和方法外,额外的多任务特定属性在任务函数内部作为 this 对象的属性可用。

许多贡献任务,包括 jshint 任务concat 任务uglify 任务 都是多任务。

grunt.task.registerMultiTask(taskName, description, taskFunction)

给定指定的配置,此示例多任务将在通过 grunt log:foo 运行 Grunt 时记录 foo: 1,2,3,或者在通过 grunt log:bar 运行 Grunt 时记录 bar: hello world。但是,如果通过 grunt log 运行 Grunt,它将记录 foo: 1,2,3,然后 bar: hello world,然后 baz: false

grunt.initConfig({
  log: {
    foo: [1, 2, 3],
    bar: 'hello world',
    baz: false
  }
});

grunt.task.registerMultiTask('log', 'Log stuff.', function() {
  grunt.log.writeln(this.target + ': ' + this.data);
});

请参见 创建任务 文档,了解更多多任务的示例。

此方法也可作为 grunt.registerMultiTask 使用。

grunt.task.requires

如果某些其他任务失败或从未运行,则使任务失败。

grunt.task.requires(taskName);

grunt.task.exists

在 0.4.5 版本中添加

检查名称,查看任务是否存在于已注册的任务中。返回一个布尔值。

grunt.task.exists(name)

grunt.task.renameTask ☃

重命名任务。如果要覆盖任务的默认行为,同时保留旧名称,这可能很有用。

注意,如果任务已重命名,this.namethis.nameArgs 属性将相应地更改。

grunt.task.renameTask(oldname, newname)

此方法也可作为 grunt.renameTask 使用。

加载外部定义的任务

对于大多数项目,任务将在 Gruntfile 中定义。对于较大的项目,或者在需要跨项目共享任务的情况下,可以从一个或多个外部目录或 Npm 安装的 Grunt 插件加载任务。

grunt.task.loadTasks ☃

从指定目录加载与任务相关的文件,相对于 Gruntfile。通过指定该插件的"tasks"子目录的路径,可以使用此方法从本地 Grunt 插件加载与任务相关的文件。

grunt.task.loadTasks(tasksPath)

此方法也可作为 grunt.loadTasks 使用。

grunt.task.loadNpmTasks ☃

从指定的 Grunt 插件加载任务。此插件必须通过 npm 本地安装,并且必须相对于 Gruntfile。可以使用 grunt-init gruntplugin 模板创建 Grunt 插件:grunt init:gruntplugin

grunt.task.loadNpmTasks(pluginName)

此方法也可作为 grunt.loadNpmTasks 使用。

任务排队

Grunt 自动对命令行上指定的所有任务进行排队和运行,但单个任务可以对要运行的其他任务进行排队。

grunt.task.run

对一个或多个任务进行排队。taskList 中指定的每个任务都将在当前任务完成后立即运行,按指定顺序运行。任务列表可以是任务数组或单个任务参数。

grunt.task.run(taskList)

grunt.task.clearQueue

完全清空任务队列。除非对其他任务进行排队,否则不会再运行任何任务。

grunt.task.clearQueue()

grunt.task.normalizeMultiTaskFiles

将任务目标配置对象规范化为 src-dest 文件映射数组。此方法由多任务系统内部使用,用于 this.files / grunt.task.current.files 属性。

grunt.task.normalizeMultiTaskFiles(data [, targetname])