gulp API 文檔 · gulp 中文文檔

## gulp API 文檔 ### gulp.src(globs[, options]) 輸出（Emits）符合所提供的匹配模式（glob）或者匹配模式的數組（array of globs）的文件。將返回一個 [Vinyl files](https://github.com/wearefractal/vinyl-fs) 的 [stream](http://nodejs.org/api/stream.html) 它可以被 [piped](http://nodejs.org/api/stream.html#stream_readable_pipe_destination_options) 到別的插件中。 ``` gulp.src('client/templates/*.jade') .pipe(jade()) .pipe(minify()) .pipe(gulp.dest('build/minified_templates')); ``` `glob` 請參考 [node-glob 語法](https://github.com/isaacs/node-glob) 或者，你也可以直接寫文件的路徑。 #### globs 類型： `String` 或 `Array` 所要讀取的 glob 或者包含 globs 的數組。 #### options 類型： `Object` 通過 [glob-stream](https://github.com/wearefractal/glob-stream) 所傳遞給 [node-glob](https://github.com/isaacs/node-glob) 的參數。除了 [node-glob](https://github.com/isaacs/node-glob#options) 和 [glob-stream](https://github.com/wearefractal/glob-stream) 所支持的參數外，gulp 增加了一些額外的選項參數： #### options.buffer 類型： `Boolean` 默認值： `true` 如果該項被設置為 `false`，那么將會以 stream 方式返回 `file.contents` 而不是文件 buffer 的形式。這在處理一些大文件的時候將會很有用。**注意：**插件可能并不會實現對 stream 的支持。 #### options.read 類型： `Boolean` 默認值： `true` 如果該項被設置為 `false`，那么 `file.contents` 會返回空值（null），也就是并不會去讀取文件。 #### options.base 類型： `String` 默認值：將會加在 glob 之前 (請看 [glob2base](https://github.com/wearefractal/glob2base)) 如, 請想像一下在一個路徑為 `client/js/somedir` 的目錄中，有一個文件叫 `somefile.js` ： ``` gulp.src('client/js/**/*.js') // 匹配 'client/js/somedir/somefile.js' 并且將 `base` 解析為 `client/js/` .pipe(minify()) .pipe(gulp.dest('build')); // 寫入 'build/somedir/somefile.js' gulp.src('client/js/**/*.js', { base: 'client' }) .pipe(minify()) .pipe(gulp.dest('build')); // 寫入 'build/js/somedir/somefile.js' ``` ### gulp.dest(path[, options]) 能被 pipe 進來，并且將會寫文件。并且重新輸出（emits）所有數據，因此你可以將它 pipe 到多個文件夾。如果某文件夾不存在，將會自動創建它。 ``` gulp.src('./client/templates/*.jade') .pipe(jade()) .pipe(gulp.dest('./build/templates')) .pipe(minify()) .pipe(gulp.dest('./build/minified_templates')); ``` 文件被寫入的路徑是以所給的相對路徑根據所給的目標目錄計算而來。類似的，相對路徑也可以根據所給的 base 來計算。請查看上述的 `gulp.src` 來了解更多信息。 #### path 類型： `String` or `Function` 文件將被寫入的路徑（輸出目錄）。也可以傳入一個函數，在函數中返回相應路徑，這個函數也可以由 [vinyl 文件實例](https://github.com/wearefractal/vinyl) 來提供。 #### options 類型： `Object` #### options.cwd 類型： `String` 默認值： `process.cwd()` 輸出目錄的 `cwd` 參數，只在所給的輸出目錄是相對路徑時候有效。 #### options.mode 類型： `String` 默認值： `0777` 八進制權限字符，用以定義所有在輸出目錄中所創建的目錄的權限。 ### gulp.task(name[, deps], fn) 定義一個使用 [Orchestrator](https://github.com/robrich/orchestrator) 實現的任務（task）。 ``` gulp.task('somename', function() { // 做一些事 }); ``` #### name 任務的名字，如果你需要在命令行中運行你的某些任務，那么，請不要在名字中使用空格。 #### deps 類型： `Array` 一個包含任務列表的數組，這些任務會在你當前任務運行之前完成。 ``` gulp.task('mytask', ['array', 'of', 'task', 'names'], function() { // 做一些事 }); ``` **注意：** 你的任務是否在這些前置依賴的任務完成之前運行了？請一定要確保你所依賴的任務列表中的任務都使用了正確的異步執行方式：使用一個 callback，或者返回一個 promise 或 stream。 #### fn 該函數定義任務所要執行的一些操作。通常來說，它會是這種形式：`gulp.src().pipe(someplugin())`。 #### 異步任務支持任務可以異步執行，如果 `fn` 能做到以下其中一點： ##### 接受一個 callback ``` // 在 shell 中執行一個命令 var exec = require('child_process').exec; gulp.task('jekyll', function(cb) { // 編譯 Jekyll exec('jekyll build', function(err) { if (err) return cb(err); // 返回 error cb(); // 完成 task }); }); ``` ##### 返回一個 stream ``` gulp.task('somename', function() { var stream = gulp.src('client/**/*.js') .pipe(minify()) .pipe(gulp.dest('build')); return stream; }); ``` ##### 返回一個 promise ``` var Q = require('q'); gulp.task('somename', function() { var deferred = Q.defer(); // 執行異步的操作 setTimeout(function() { deferred.resolve(); }, 1); return deferred.promise; }); ``` **注意：** 默認的，task 將以最大的并發數執行，也就是說，gulp 會一次性運行所有的 task 并且不做任何等待。如果你想要創建一個序列化的 task 隊列，并以特定的順序執行，你需要做兩件事： * 給出一個提示，來告知 task 什么時候執行完畢， * 并且再給出一個提示，來告知一個 task 依賴另一個 task 的完成。對于這個例子，讓我們先假定你有兩個 task，"one" 和 "two"，并且你希望它們按照這個順序執行： 1. 在 "one" 中，你加入一個提示，來告知什么時候它會完成：可以再完成時候返回一個 callback，或者返回一個 promise 或 stream，這樣系統會去等待它完成。 2. 在 "two" 中，你需要添加一個提示來告訴系統它需要依賴第一個 task 完成。因此，這個例子的實際代碼將會是這樣： ``` var gulp = require('gulp'); // 返回一個 callback，因此系統可以知道它什么時候完成 gulp.task('one', function(cb) { // 做一些事 -- 異步的或者其他的 cb(err); // 如果 err 不是 null 或 undefined，則會停止執行，且注意，這樣代表執行失敗了 }); // 定義一個所依賴的 task 必須在這個 task 執行之前完成 gulp.task('two', ['one'], function() { // 'one' 完成后 }); gulp.task('default', ['one', 'two']); ``` ### gulp.watch(glob [, opts], tasks) 或 gulp.watch(glob [, opts, cb]) 監視文件，并且可以在文件發生改動時候做一些事情。它總會返回一個 EventEmitter 來發射（emit） `change` 事件。 ### gulp.watch(glob[, opts], tasks) #### glob 類型： `String` or `Array` 一個 glob 字符串，或者一個包含多個 glob 字符串的數組，用來指定具體監控哪些文件的變動。 #### opts 類型： `Object` 傳給 [`gaze`](https://github.com/shama/gaze) 的參數。 #### tasks 類型： `Array` 需要在文件變動后執行的一個或者多個通過 `gulp.task()` 創建的 task 的名字， ``` var watcher = gulp.watch('js/**/*.js', ['uglify','reload']); watcher.on('change', function(event) { console.log('File ' + event.path + ' was ' + event.type + ', running tasks...'); }); ``` ### gulp.watch(glob[, opts, cb]) #### glob 類型： `String` or `Array` 一個 glob 字符串，或者一個包含多個 glob 字符串的數組，用來指定具體監控哪些文件的變動。 #### opts 類型： `Object` 傳給 [`gaze`](https://github.com/shama/gaze) 的參數。 #### cb(event) 類型： `Function` 每次變動需要執行的 callback。 ``` gulp.watch('js/**/*.js', function(event) { console.log('File ' + event.path + ' was ' + event.type + ', running tasks...'); }); ``` callback 會被傳入一個名為 `event` 的對象。這個對象描述了所監控到的變動： ##### event.type 類型： `String` 發生的變動的類型：`added`, `changed` 或者 `deleted`。 ##### event.path 類型： `String` 觸發了該事件的文件的路徑。 ## gulp 命令行（CLI）文檔 ### 參數標記 gulp 只有你需要熟知的參數標記，其他所有的參數標記只在一些任務需要的時候使用。 * `-v` 或 `--version` 會顯示全局和項目本地所安裝的 gulp 版本號 * `--require <module path>` 將會在執行之前 reqiure 一個模塊。這對于一些語言編譯器或者需要其他應用的情況來說來說很有用。你可以使用多個`--require` * `--gulpfile <gulpfile path>` 手動指定一個 gulpfile 的路徑，這在你有很多個 gulpfile 的時候很有用。這也會將 CWD 設置到該 gulpfile 所在目錄 * `--cwd <dir path>` 手動指定 CWD。定義 gulpfile 查找的位置，此外，所有的相應的依賴（require）會從這里開始計算相對路徑 * `-T` 或 `--tasks` 會顯示所指定 gulpfile 的 task 依賴樹 * `--tasks-simple` 會以純文本的方式顯示所載入的 gulpfile 中的 task 列表 * `--color` 強制 gulp 和 gulp 插件顯示顏色，即便沒有顏色支持 * `--no-color` 強制不顯示顏色，即便檢測到有顏色支持 * `--silent` 禁止所有的 gulp 日志命令行會在 process.env.INIT_CW 中記錄它是從哪里被運行的。 #### Task 特定的參數標記請參考 [StackOverflow](http://stackoverflow.com/questions/23023650/is-it-possible-to-pass-a-flag-to-gulp-to-have-it-run-tasks-in-different-ways) 了解如何增加任務特定的參數標記。 ### Tasks Task 可以通過 `gulp <task> <othertask>` 方式來執行。如果只運行 `gulp` 命令，則會執行所注冊的名為 `default` 的 task，如果沒有這個 task，那么 gulp 會報錯。 ### 編譯器你可以在 [interpret](https://github.com/tkellen/node-interpret#jsvariants) 找到所支持的語言列表。如果你想要增加一個語言的支持，請在這里提交一個 pull request 或者 issue。