grunt.task

grunt.task

注冊、執(zhí)行和加載外部任務。

參見 task lib source 和 task util lib source 獲取更多信息。

The task API

當一個任務正在執(zhí)行時，Grunt 通過this 對象向此任務函數暴露了很多任務特定的屬性和方法。參見 深入任務內幕指南，這里可以找到完整的屬性和方法列表。

很多屬性和方法都可以通過 this 對象訪問到。

注意，任何標記為的 ? (unicode snowman) 方法也可以直接通過 grunt 對象直接訪問到。參見 API首頁以獲取更多信息。

創(chuàng)建任務

grunt.task.registerTask

注冊 "別名任務" 或 任務函數。此方法支持以下兩種類型：

別名任務

如果指定了一個任務列表，那么，新注冊的任務將會是這一個或多個任務的別名（alias）。當此"別名任務"執(zhí)行時，taskList中的所有任務都將按指定的順序依次執(zhí)行。taskList 參數必須是一個任務數組。

grunt.task.registerTask(taskName, taskList)

下面這個案例展示的是定義一個"default" 任務，當執(zhí)行 Grunt 且不通過參數指定任務時， "jshint"、 "qunit"、"concat" 和 "uglify" 任務將自動執(zhí)行：

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

還可以指定任務的參數。下面的這個案例中，別名"dist"執(zhí)行了 "concat" 和 "uglify" 這兩個任務，并且都指定了"dist" 參數：

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

任務函數

如果傳入description和taskFunction，每當任務運行時，指定的函數（taskFunction）都會被執(zhí)行。此外，當執(zhí)行 grunt --help時，前面指定的描述（description）就會顯示出來。特定任務的屬性和方法在任務函數內部通過this對象的屬性即可訪問。如果任務函數返回false表示任務失敗。

注意，grunt.task.registerMultiTask方法將稍候介紹，它可以被用于定義一種特殊類型的任務，即"復合任務"。

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

下面這個案例中，當 Grunt 運行grunt foo:testing:123時，日志輸出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);
  }
});

參見 創(chuàng)建任務 文檔,查看更多任務實現案例和別名任務。

此方法還可以通過 grunt.registerTask調用。

grunt.task.registerMultiTask

注冊一個 "復合任務（multi task）"。 復合任務是指在不指定目標（target）時，將依次執(zhí)行其所包含的所有已命名的子屬性（sub-properties） (也就是 目標) 。除了默認的屬性和方法外，還可以通過this對象訪問復合任務獨有的屬性。

大多數的contrib任務，包括 jshint task、concat task 和 uglify task 都是復合任務。

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

給定以下配置信息，當執(zhí)行grunt log:foo時，下面的復合任務將輸出日志foo: 1,2,3；當執(zhí)行grunt log:bar時，將輸出日志bar: hello world。如果只是執(zhí)行grunt log，那么，將先輸出日志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);
});

參見 創(chuàng)建任務 文檔以獲取更多復合任務的案例。

此方法還可以通過 grunt.registerMultiTask 調用。

grunt.task.requires

Fail the task if some other task failed or never ran.

grunt.task.requires(taskName);

grunt.task.exists

Added in 0.4.5

Check with the name, if a task exists in the registered tasks. Return a boolean.

grunt.task.exists(name)

grunt.task.renameTask

重命名任務。如果你希望覆蓋某個任務的默認行為，并且希望保留原來的名字，這個函數將會很有用。

注意，如果一個任務已經被重命名了， this.name 和 this.nameArgs 屬性都會發(fā)生相應的變化。

grunt.task.renameTask(oldname, newname)

此方法還可以通過 grunt.renameTask 調用。

加載外部定義的任務

對于多數項目來說，Gruntfile 文件中可能會定義很多任務。對于大型項目或者需要在多個項目中共享任務的情況，可以從一個或多個外部目錄加載任務，或者從npm安裝的 Grunt 插件加載任務。

grunt.task.loadTasks

從指定的目錄（注意：相對于 Gruntfile 所在目錄）加載任務相關的文件。此方法可以從本地Grunt插件加載任務相關的文件，只需指定包含"tasks"子目錄的插件目錄即可。

grunt.task.loadTasks(tasksPath)

此方法還可以通過 grunt.loadTasks 調用。

grunt.task.loadNpmTasks

從指定的 Grunt 插件中加載任務。此插件必須通過npm安裝到本地，并且是參照 Gruntfile 文件的相對路徑。Grunt插件還可以通過 grunt-init grunt插件模版創(chuàng)建： grunt init:gruntplugin。

grunt.task.loadNpmTasks(pluginName)

此方法還可以通過 grunt.loadNpmTasks 調用。

隊列任務

Grunt自動將命令行中指定的任務加入隊列并執(zhí)行，但是，一些獨特的任務可以向隊列中加入額外需要執(zhí)行的任務。

grunt.task.run

將一個或多個任務放入隊列中。 taskList 中的每個任務都會按照其在隊列中的順序，在當前任務執(zhí)行完畢后立即執(zhí)行。任務列表可以是一個任務數組或單個任務。

grunt.task.run(taskList)

grunt.task.clearQueue

完全清空任務隊列。除非將額外的任務加入隊列，否則將不會執(zhí)行任何任務。

grunt.task.clearQueue()

grunt.task.normalizeMultiTaskFiles

將目標（target）的配置對象標準化為一個src-dest文件映射數組。此方法在內部由復合任務系統(tǒng)的this.files / grunt.task.current.files屬性調用。

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