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']);
函数任务
如果传递了 description
和 taskFunction
,则每当运行该任务时都会执行指定的函数。此外,指定的描述将在运行 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.name 和 this.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])