[译] Gulp 4.0 API 文档 #55

cssmagic · 2015-11-10T07:31:02Z

[译] Gulp 4.0 API 文档

Original: gulp API docs #4.0

Translated by: cssmagic

索引

gulp.src - Emit files matching one or more globs

gulp.dest - Write files to directories

gulp.symlink - Write files to symlinks

gulp.task - Define tasks

gulp.lastRun - Get timestamp of last successful run

gulp.parallel - Run tasks in parallel

gulp.series - Run tasks in series

gulp.watch - Do something when a file changes

gulp.tree - Get the tree of tasks

gulp.registry - Get or set the task registry

`gulp.src(globs[, options])` 方法

Emits files matching provided glob or array of globs. Returns a stream of Vinyl files that can be piped to plugins.

读取并输出所有与给定的 glob（文件匹配符）或 glob 数组相匹配的文件。返回一个 Vinyl 文件的流（stream），以便通过管道传送（pipe）给插件处理。

gulp.src('client/templates/*.jade')
  .pipe(jade())
  .pipe(minify())
  .pipe(gulp.dest('build/minified_templates'));

glob refers to node-glob syntax or it can be a direct file path.

glob 可以是 node-glob 语法，或者也可以直接给定一个明确的文件路径。

`globs` 参数

Type: String or Array

类型：字符串（String）或数组（Array）

Glob or array of globs to read.

需要读取的 glob 或 glob 数组。

Note that globs are evaluated in order, which means this is possible:

需要注意的是，多个 glob 会按顺序进行解析，这意味着以下意图是可以实现的：

// exclude every JS file that starts with a b except bad.js
// 排除所有以字母 b 开头的 JS 文件，但不排除 bad.js
gulp.src(['*.js', '!b*.js', 'bad.js'])

Note: glob symlink following behavior is opt-in and you must specify follow: true in the options object that is passed to node-glob.

请注意：glob 的 symlink 追踪行为是可以选择的，你必须在选项参数中指定 follow: true，以便传给 node-glob。

`options` 参数

Type: Object

类型：对象（Object）

Options to pass to node-glob through glob-stream.

通过 glob-stream 传给 node-glob 的选项。

gulp adds some additional options in addition to the options supported by node-glob and glob-stream:

除了 node-glob 和 glob-stream 所支持的选项之外，Gulp 还增加了一些额外的选项：

`options.cwd` 选项

（译注：这个选项其实是 node-glob 的选项，并没有必要列在 Gulp 的 API 文档中。）

The working directory the folder is relative to.

指定匹配文件时以哪个目录作为基准目录。可以是一个相对于当前工作目录的相对路径。

Type: String

类型：字符串（String）

Default: process.cwd()

默认值：process.cwd()

`options.buffer` 选项

Type: Boolean

类型：布尔值（Boolean）

Default: true

默认值：true

Setting this to false will return file.contents as a stream and not buffer files. This is useful when working with large files.

如果此选项被设置为 false，那么将会以 stream 的形式（而不是以 buffer 文件的形式）返回 file.contents。在处理大文件时，这个选项会很有用。

Note: Plugins might not implement support for streams.

请注意：插件可能并没有实现对 stream 的支持。

`options.read` 选项

Type: Boolean

类型：布尔值（Boolean）

Default: true

默认值：true

Setting this to false will return file.contents as null and not read the file at all.

如果此选项被设置为 false，那么 file.contents 将会返回空（null），即完全不会去读取文件。

`options.base` 选项

Type: String

类型：字符串（String）

Default: everything before a glob starts (see glob2base)

默认值：所有出现在 glob 之前的东西（请参见 glob2base）

E.g., consider somefile.js in client/js/somedir:

比如说，假设在 client/js/somedir 路径下的有一个叫 somefile.js 的文件：

// Matches 'client/js/somedir/somefile.js' and resolves `base` to `client/js/`
// 以下代码将匹配 'client/js/somedir/somefile.js'，并将 `base` 解析为 `client/js/`
gulp.src('client/js/**/*.js')
  .pipe(minify())
  .pipe(gulp.dest('build'));  // Writes 'build/somedir/somefile.js'
                              // 将写到 'build/somedir/somefile.js' 文件

gulp.src('client/js/**/*.js', { base: 'client' })
  .pipe(minify())
  .pipe(gulp.dest('build'));  // Writes 'build/js/somedir/somefile.js'
                              // 将写到 'build/js/somedir/somefile.js' 文件

`options.since` 选项

Type: Date or Number

类型：日期（Date）或数字（Number）

Setting this to a Date or a time stamp will discard any file that have not been modified since the time specified.

把这个选择设置为一个日期或时间戳将会丢弃所有在此时间点后没有发生变化的文件。

`options.passthrough` 选项

Type: Boolean

类型：布尔值（Boolean）

Default: false

默认值：false

If true, it will create a duplex stream which passes items through and emits globbed files.

如果设置为 true，将会创建一个读写双向流（duplex stream），这个流将把所有匹配的文件直接传输并输出。（译注：实际上我并不知道这句话在说什么，翻译可能有误。）

`options.allowEmpty` 选项

Type: Boolean

类型：布尔值（Boolean）

Default: false

默认值：false

When true, will allow singular globs to fail to match. Otherwise, globs which are only supposed to match one file (such as ./foo/bar.js) will cause an error to be thrown if they don't match.

如果设置为 true，将允许单文件形式的 glob 匹配失败。否则，那些只能匹配单个文件（比如 ./foo/bar.js）的 glob 一旦匹配不到文件，就会抛出错误。

// Emits an error if app/scripts.js doesn't exist
// 如果 app/scripts.js 文件不存在，则会抛出错误
gulp.src('app/scripts.js')
  .pipe(...);

// Won't emit an error
// 这样就不会抛出错误
gulp.src('app/scripts.js', { allowEmpty: true })
  .pipe(...);

`gulp.dest(path[, options])` 方法

Can be piped to and it will write files. Re-emits all data passed to it so you can pipe to multiple folders. Folders that don't exist will be created.

接收 pipe 来的数据，并写入文件。它会重新输出所有数据，因此你可以将数据 pipe 到多个文件夹。指定的文件夹如果还不存在，将会被自动创建。

gulp.src('./client/templates/*.jade')
  .pipe(jade())
  .pipe(gulp.dest('./build/templates'))
  .pipe(minify())
  .pipe(gulp.dest('./build/minified_templates'));

The write path is calculated by appending the file relative path to the given destination directory. In turn, relative paths are calculated against the file base. See gulp.src above for more info.

写入路径的计算方式是在给定的目标路径后面加上各文件的相对路径。而相对路径是通过文件 base 来得到的。更多信息请参见上面的 gulp.src 方法。

`path` 参数

Type: String or Function

类型：字符串（String）或函数（Function）

The path (output folder) to write files to. Or a function that returns it, the function will be provided a vinyl File instance.

文件的写入路径（输出目录）。也可以是一个可以返回输出目录的函数，这个函数将会被传入一个 vinyl 文件实例。

`options` 参数

Type: Object

类型：对象（Object）

`options.cwd` 选项

Type: String

类型：字符串（String）

Default: process.cwd()

默认值：process.cwd()

cwd for the output folder, only has an effect if provided output folder is relative.

为输出目录指定 cwd。仅当指定的输出目录是相对路径时，这个选项才会生效。

`options.mode` 选项

Type: String or Number

类型：字符串（String）或数字（Number）

Default: the mode of the input file (file.stat.mode) or the process mode if the input file has no mode property.

默认值：输入文件的权限模式（file.stat.mode）。如果输入文件没有模式属性，则取进程的模式。

Octal permission specifying the mode the files should be created with: e.g. "0744", 0744 or 484 (0744 in base 10).

使用八进制的权限标记来指定输出文件将以什么模式来创建：比如 "0744"、0744 或 484（十进制形态的 0744）。

`options.dirMode` 选项

Type: String or Number

类型：字符串（String）或数字（Number）

Default: Default is the process mode.

默认值：进程的模式。

Octal permission specifying the mode the directory should be created with: e.g. "0755", 0755 or 493 (0755 in base 10).

使用八进制的权限标记来指定输出目录将以什么模式来创建：比如 "0744"、0744 或 484（十进制形态的 0744）。

`options.overwrite` 选项

Type: Boolean

类型：布尔值（Boolean）

Default: true

默认值：true

Specify if existing files with the same path should be overwritten or not.

指定在相同路径下已经存在同名文件时是否覆盖。

`gulp.symlink(folder[, options])` 方法

Functions exactly like gulp.dest, but will create symlinks instead of copying a directory.

它的功能和 gulp.dest 与十分相似，但它会创建 symlink，而不是复制目录。

`folder` 参数

Type: String or Function

类型：字符串（String）或函数（Function）

A folder path or a function that receives in a file and returns a folder path.

一个文件夹路径。也可以是一个函数，这个函数可以接受一个文件并返回文件夹路径。

`options` 参数

Type: Object

类型：对象（Object）

`options.cwd` 选项

Type: String

类型：字符串（String）

Default: process.cwd()

默认值：process.cwd()

cwd for the output folder, only has an effect if provided output folder is relative.

为输出目录指定 cwd。仅当指定的输出目录是相对路径时，这个选项才会生效。

`options.dirMode` 选项

Type: String or Number

类型：字符串（String）或数字（Number）

Default: Default is the process mode.

默认值：取进程的模式。

Octal permission specifying the mode the directory should be created with: e.g.
"0755", 0755 or 493 (0755 in base 10).

使用八进制的权限标记来指定输出目录将以什么模式来创建：比如 "0744"、0744 或 484（十进制形态的 0744）。

`gulp.task([name,] fn)` 方法

Define a task exposed to gulp-cli, gulp.series, gulp.parallel and gulp.lastRun; inherited from undertaker.

这个方法可以定义一个任务，以便暴露给 Gulp 命令行工具（gulp-cli）以及 gulp.series、gulp.parallel 和 gulp.lastRun 方法；这个方法继承自 undertaker。

gulp.task(function someTask() {
  // Do stuff
  // 在这里干一些活
});

Or get a task that has been registered.

也可以获取一个已经注册的任务。

// someTask will be the registered task function
// someTask 是一个已经注册的任务函数
var someTask = gulp.task('someTask');

`name` 参数

If the name is not provided, the task will be named after the function name or displayName property. The name argument is required if the name and displayName properties of fn are empty.

如果没有提供这个 name 参数的话，任务将以函数的 name 或 displayName 属性来命名。如果 fn 参数的 name 和 displayName 属性都为空的话，那这个 name 参数就是必选的了。

Since the task can be run from the command line, you should avoid using spaces in task names.

由于任务可以在命令行运行，因此需要避免在任务名中使用空格。

`fn` 参数

The function that performs the task's operations. Generally it takes this form:

完成某个任务的具体操作的函数。通常它的形式是这样的：

function someTask() {
  return gulp.src(['some/glob/**/*.ext']).pipe(someplugin());
}
someTask.description = 'Does something';

gulp.task(someTask)

Gulp tasks are asynchronous and Gulp uses async-done to wait for the task's completion. Tasks are called with a callback parameter to call to signal completion. Alternatively, Task can return a stream, a promise, a child process or a RxJS observable to signal the end of the task.

Gulp 任务都是异步的，Gulp 使用 async-done 来等待任务的完成。任务在调用时会传入一个回调函数作为参数，这个回调函数会在任务完成时被调用。或者换一种方式，任务可以返回一个流、一个 promise、一个子进程，或一个 RxJS 可观察事件流，以便标记任务的结束。

Warning: Sync tasks are not supported and your function will never complete if the one of the above strategies is not used to signal completion. However, thrown errors will be caught by Gulp.

警告：已经不再支持同步任务了，如果任务函数没有采用以上任何一种策略来标记任务的结束，那么任务将永远也无法完成。不过，它抛出的错误会被 Gulp 捕获。

fn properties

`fn` 参数的属性

`fn.name` 属性

gulp.task names the task after the function name property if the optional name parameter of gulp.task is not provided.

如果 gulp.task 方法的可选参数 name 没有指定时，gulp.task 将使用函数的 name 属性来给任务命名。

Note: Function.name is not writable; it cannot be set or edited. If you need to assign a function name or use characters that aren't allowed in function names, use the displayName property. It will be empty for anonymous functions:

请注意：Function.name 属性是不可写的；它无法被写入或修改。如果你需要给一个函数指定函数名，或者想在函数名中使用不允许的字符，可以用 displayName 属性来代替。对于匿名函数来说，这个属性是空的：

function foo() {};
foo.name === 'foo' // true

var bar = function() {};
bar.name === '' // true

bar.name = 'bar'
bar.name === '' // true

`fn.displayName` 属性

gulp.task names the task after the function displayName property if function is anonymous and the optional name parameter of gulp.task is not provided.

如果函数是匿名函数，或者 gulp.task 方法的可选参数 name 没有指定时，gulp.task 将使用函数的 displayName 属性来给任务命名。

`fn.description` 属性

gulp-cli prints this description alongside the task name when listing tasks:

gulp-cli 在列出任务时，会紧随任务名之后打印出这段描述。

var gulp = require('gulp');

function test(done){
  done();
}
test.description = 'I do nothing';

gulp.task(test);

$> gulp --tasks
[12:00:02] Tasks for ~/Documents/some-project/gulpfile.js
[12:00:02] └── test  I do nothing

Async support

异步任务支持

Accept a callback

接受一个回调函数

var del = require('del');

gulp.task('clean', function(done) {
  del(['.build/'], done);
});

The callback accepts an optional Error object. If it receives an error, the task will fail.

这个回调函数接受一个可选的 Error 对象。如果它收到错误，这个任务将失败。

Return a stream

返回一个 stream

gulp.task('somename', function() {
  return gulp.src('client/**/*.js')
    .pipe(minify())
    .pipe(gulp.dest('build'));
});

Return a promise

返回一个 promise

var Promise = require('promise');
var del = require('del');

gulp.task('clean', function() {
  return new Promise(function (resolve, reject) {
    del(['.build/'], function(err) {
      if (err) {
        reject(err);
      } else {
        resolve();
      }
    });
  });
});

or:

或者：

var promisedDel = require('promised-del');

gulp.task('clean', function() {
  return promisedDel(['.build/']);
});

Return a child process

返回一个子进程

gulp.task('clean', function() {
  return spawn('rm', ['-rf', path.join(__dirname, 'build')]);
});

Return a RxJS observable

返回一个 RxJS 可观察事件流

var Observable = require('rx').Observable;

gulp.task('sometask', function() {
  return Observable.return(42);
});

`gulp.lastRun(taskName, [timeResolution])` 方法

Returns the timestamp of the last time the task ran successfully. The time will be the time the task started. Returns undefined if the task has not run yet.

返回指定任务在上一次成功运行时的时间戳。时间是任务开始的时间。如果任务还没有运行过，则返回 undefined。

`taskName` 参数

Type: String

类型：字符串（String）

The name of the registered task or of a function.

已注册的任务的任务名，或任务函数的函数名。

`timeResolution` 参数

Type: Number.

类型：数字（Number）

Default: 1000 on node v0.10, 0 on node v0.12 (and iojs v1.5).

默认值：在 node v0.10 下是 1000，在 node v0.12（和 iojs v1.5）下是 0。

Set the time resolution of the returned timestamps. Assuming the task named "someTask" ran at 1426000004321:

用于设定返回的时间戳的精度。假设有一个叫 "someTask" 的任务在 1426000004321 这个时间运行过：

gulp.lastRun('someTask', 1000) would return 1426000004000.
gulp.lastRun('someTask', 100) would return 1426000004300.

gulp.lastRun('someTask', 1000) 将返回 1426000004000。
gulp.lastRun('someTask', 100) 将返回 1426000004300。

timeResolution allows you to compare a run time to a file mtime stat attribute. This attribute time resolution may vary depending of the node version and the file system used:

timeResolution 允许你把运行时间和文件的 mtime stat 属性进行比较。这个属性的时间精度在不同的 node 版本和文件系统下各有不同：

on node v0.10, a file mtime stat time resolution of any files will be 1s at best;
on node v0.12 and iojs v1.5, 1ms at best;
for files on FAT32, the mtime time resolution is 2s;
on HFS+ and Ext3, 1s;
on NTFS, 1s on node v0.10, 100ms on node 0.12;
on Ext4, 1s on node v0.10, 1ms on node 0.12.

在 node v0.10 下，所有文件的 mtime stat 时间精度最高只有 1s；
在 node v0.12 和 iojs v1.5 下，最高有 1ms；
对于 FAT32 下的文件来说，其 mtime 时间精度最高只有 2s；
对于 HFS+ 和 Ext3 来说，是 1s；
对于 NTFS 来说，在 node v0.10 下是 1s，在 node 0.12 下是 100ms；
对于 Ext4 来说，在 node v0.10 下是 1s，在 node 0.12 下是 1ms。

`gulp.parallel(...tasks)` 方法

Takes a number of task names or functions and returns a function of the composed tasks or functions.

接受多个任务名或任务函数，返回这些任务或函数组合之后形成一个函数。

When using task names, the task should already be registered.

如果使用的是任务名的话，任务必须是已经注册过的。

When the returned function is executed, the tasks or functions will be executed in parallel, all being executed at the same time. If an error occurs, all execution will complete.

当这个组合后的函数被执行时，它包含的各项任务或函数将会并行执行，即它们会同时启动并运行。只要有一个错误发生，所有任务的运行都将结束。

gulp.task('one', function(done) {
  // do stuff
  // 在这里干一些活
  done();
});

gulp.task('two', function(done) {
  // do stuff
  // 在这里干一些活
  done();
});

gulp.task('default', gulp.parallel('one', 'two', function(done) {
  // do more stuff
  // 在这里再多干一些活
  done();
}));

`tasks` 参数

Type: Array, String or Function

类型：数组（Array）、字符串（String）或函数（Function）

A task name, a function or an array of either.

一个任务名、一个函数，或是由这两者所构成的数组。

`gulp.series(...tasks)` 方法

Takes a number of task names or functions and returns a function of the composed tasks or functions.

接受多个任务名或任务函数，返回这些任务或函数组合之后形成一个函数。

When using task names, the task should already be registered.

如果使用的是任务名的话，任务必须是已经注册过的。

When the returned function is executed, the tasks or functions will be executed in series, each waiting for the prior to finish. If an error occurs, execution will stop.

当这个组合后的函数被执行时，它包含的各项任务或函数将会串行执行，即各项任务会等待它前面的任务完成后再运行。只要有一个错误发生，所有任务的运行都将结束。

gulp.task('one', function(done) {
  // do stuff
  // 在这里干一些活
  done();
});

gulp.task('two', function(done) {
  // do stuff
  // 在这里干一些活
  done();
});

gulp.task('default', gulp.series('one', 'two', function(done) {
  // do more stuff
  // 在这里再多干一些活
  done();
}));

`tasks` 参数

Type: Array, String or Function

类型：数组（Array）、字符串（String）或函数（Function）

A task name, a function or an array of either.

一个任务名、一个函数，或是由这两者所构成的数组。

`gulp.watch(globs[, opts], fn)` 方法

Takes a path string, an array of path strings, a glob string or an array of glob strings as globs to watch on the filesystem. Also optionally takes options to configure the watcher and a fn to execute when a file changes.

第一个参数 globs 用于指定文件系统中的哪些文件会被监视；接下来的 options 参数是可选的，用于配置监视器；最后的 fn 参数是当文件变动时调用的任务函数。

Returns an instance of chokidar.

返回一个 chokidar 监视器实例。

gulp.watch('js/**/*.js', gulp.parallel('concat', 'uglify'));

In the example, gulp.watch runs the function returned by gulp.parallel each
time a file with the js extension in js/ is updated.

在上面的例子中，gulp.watch 会监视 js/ 目录下所有扩展名为 js 的文件。每当这些文件改动时，都会调用 gulp.parallel 所返回的函数。

`globs` 参数

Type: String or Array

类型：字符串（String）或数组（Array）

A path string, an array of path strings, a glob string or an array of glob strings that indicate which files to watch for changes.

可以是一个路径字符串，或由多个路径字符串组成的数组；也可以是一个 glob，或由多个 glob 组成的数组。它将指定哪些文件的变动将受到监视。

`opts` 参数

Type: Object

类型：对象（Object）

delay (milliseconds, default: 200). The delay to wait before triggering the fn. Useful for waiting on many changes before doing the work on changed files, e.g. find-and-replace on many files.
queue (boolean, default: true). Whether or not a file change should queue the fn execution if the fn is already running. Useful for a long running fn.
ignoreInitial (boolean, default: true). If set to false the fn is called during chokidar instantiation as it discovers the file paths. Useful if it is desirable to trigger the fn during startup. Passed through to chokidar, but defaulted to true instead of false.

delay（毫秒，默认值为 200）。它表示在触发任务函数（fn）之前等待的延时。在大批量修改文件时（比如对大量文件进查找、替换操作），我们往往需要等一小会儿，此时这个选项就显得非常有用了。
queue（布尔值，默认值为 true）。它决定文件的一连串变更所触发的同一个 fn 是否以队列的方式执行。对于耗时的任务函数来说较为适用。
ignoreInitial （布尔值，默认值为 true）。如果设置为 false，则在 chokidar 的实例化期间如果发现文件变更也会调用 fn。如果你希望在启动期间就能触发 fn，则可以尝试这个选项。这个选项会传给 chokidar，但 Gulp 传给它的默认值是 true 而不是 chokidar 自己的默认值 false。

Options that are passed to chokidar.

需要传给 chokidar 的选项。

Commonly used options:

通常会用到的选项如下：

ignored (anymatch-compatible definition). Defines files/paths to be excluded from being watched.
usePolling (boolean, default: false). When true uses a watch method backed by stat polling. Usually necessary when watching files on a network mount or on a VMs file system.
cwd (path string). The base directory from which watch paths are to be derived. Paths emitted with events will be relative to this.
alwaysStat (boolean, default: false). If relying upon the fs.Stats object that may get passed as a second argument with add, addDir, and change events when available, set this to true to ensure it is provided with every event. May have a slight performance penalty.

ignored（兼容 [anymatch] 的定义）：定义哪些文件或路径需要从监视范围中排除掉。
usePolling（布尔值，默认值为 false）：当此选项为 true 时，将采用基于 stat 轮询的监视方法。如果要在网络挂载磁盘或虚拟机的文件系统上监视文件的话，这个选项通常是有必要的。
cwd（路径字符串）：指定了监视路径在推断时所采用的基准路径。随事件发射的路径都是以此作为基准的相对路径。
alwaysStat（布尔值，默认值为 false）：如果信赖 fs.Stats 对象的话（在可用时，这个对象会在 add、addDir 和 change 事件发生时作为第二个参数传过来），那把这个选项设置为 true 可以确保这个对象会在这些事件发生时提供给下面的 fn 参数。可能存在轻微的性能损耗。

Read about the full set of options in chokidar's README.

完整的选项说明请参阅 chokidar 项目的 README。

`fn` 参数

Type: Function

类型：Function

If the fn is passed, it will be called when the watcher emits a change, add or unlink event. It is automatically debounced with a default delay of 200 milliseconds and subsequent calls will be queued and called upon completion. These defaults can be changed using the options.

如果提供了 fn 这个参数，它就会在监视器触发任何一个 change、add 或 unlink 事件时被调用。它会自动以默认的 200 毫秒周期进行 debounce，后续的调用将排队依次执行。这个默认值可以在 options 中修改。（译注：听起来原文中的 “debounce” 应该是 “throttle”？总之大家明白这个意思就行了。）

The fn is passed a single argument, callback, which is a function that must be called when work in the fn is complete. Instead of calling the callback function, async completion can be signalled by:

（译注：与 gulp.task() 的 fn 参数类似，这里的 fn 也是一个异步函数。）我们需要给这个 fn 函数设置一个 callback 参数，当 fn 内的工作完成时需要调用一下这个 callback 来宣告任务已完成。如果你不想用这种方式来实现 fn 的异步特性，也可以通过以下方式来实现：

Returning a Stream or EventEmitter
Returning a Child Process
Returning a Promise
Returning an Observable

让 fn 返回一个流（Stream）或事件触发器（EventEmitter）
让 fn 返回一个子进程
让 fn 返回一个 Promise
让 fn 返回一个可观察事件流（Observable）

Once async completion is signalled, if another run is queued, it will be executed.

当这个异步函数宣告自己已经运行完成时，如果另一次运行计划已经在队列中了，那么队列会继续往下走。

gulp.watch returns a wrapped chokidar FSWatcher object. Listeners can also be set directly for any of chokidar's events, such as addDir, unlinkDir, and error. You must set listeners directly to get
access to chokidar's callback parameters, such as path.

gulp.watch 会返回一个经过包装的 chokidar FSWatcher 对象。我们也可以把监听函数直接绑定到任何 chokidar 的事件上，比如 addDir、unlinkDir 和 error 等。只有把监听函数直接绑定到这些事件上，我们才能访问到 chokidar 的回调函数的参数，比如 path 等。

var watcher = gulp.watch('js/**/*.js', gulp.parallel('concat', 'uglify'));
watcher.on('change', function(path, stats) {
  console.log('File ' + path + ' was changed');
});

watcher.on('unlink', function(path) {
  console.log('File ' + path + ' was removed');
});

`fn` 的 `path` 参数

Type: String

类型：字符串（String）

Path to the file. If opts.cwd is set, path is relative to it.

发生变动的文件的路径。如果指定了 opts.cwd 的话，path 是相对于它的。

`fn` 的 `stats` 参数

Type: Object

类型：对象（Object）

File stats object when available. Setting the alwaysStat option to true will ensure that a file stat object will be provided.

当可用时，File stats 对象会传进来。将 alwaysStat 选项设置为 true 可以确保一个 file stat 对象会传过来。

watcher methods

监视器的各种方法

`watcher.close()` 方法

Shuts down the file watcher.

关闭这个文件监视器。

`watcher.add(glob)` 方法

Watch additional glob (or array of globs) with an already-running watcher instance.

让一个已经在运行的监视器实例监视额外的 glob（或 glob 数组）。

`watcher.unwatch(glob)` 方法

Stop watching a glob (or array of globs) while leaving the watcher running and emitting events for the remaining paths it is watching.

停止监听一个 glob（或 glob 数组），但仍然保持监视器的运行，只在剩下的监听路径上触发事件。

`gulp.tree(options)` 方法

Returns the tree of tasks. Inherited from undertaker. See the undertaker docs for this function.

返回所有任务的树形结构。这个方法继承自 undertaker。请参见 undertaker 文档中的这个函数。

`options` 参数

Type: Object

类型：对象（Object）

Options to pass to undertaker.

传给 undertaker 的选项。

`options.deep` 选项

Type: Boolean

类型：布尔值（Boolean）

Default: false

默认值：false

If set to true whole tree should be returned.

如果设置为 true，会返回整个树形结构。

Example gulpfile

gulpfile 示例

gulp.task('one', function(done) {
  // do stuff
  // 在这里干一些活
  done();
});

gulp.task('two', function(done) {
  // do stuff
  // 在这里干一些活
  done();
});

gulp.task('three', function(done) {
  // do stuff
  // 在这里干一些活
  done();
});

gulp.task('four', gulp.series('one', 'two'));

gulp.task('five',
  gulp.series('four',
    gulp.parallel('three', function(done) {
      // do more stuff
      // 在这里再多干一些活
      done();
    })
  )
);

Example tree output

树形结构输出示例

gulp.tree()

// output: [ 'one', 'two', 'three', 'four', 'five' ]

gulp.tree({ deep: true })

/*output: [
   {
      "label":"one",
      "type":"task",
      "nodes":[]
   },
   {
      "label":"two",
      "type":"task",
      "nodes":[]
   },
   {
      "label":"three",
      "type":"task",
      "nodes":[]
   },
   {
      "label":"four",
      "type":"task",
      "nodes":[
          {
            "label":"<series>",
            "type":"function",
            "nodes":[
               {
                  "label":"one",
                  "type":"task",
                  "nodes":[]
               },
               {
                  "label":"two",
                  "type":"task",
                  "nodes":[]
               }
            ]
         }
      ]
   },
   {
      "label":"five",
      "type":"task",
      "nodes":[
         {
            "label":"<series>",
            "type":"function",
            "nodes":[
               {
                  "label":"four",
                  "type":"task",
                  "nodes":[
                     {
                        "label":"<series>",
                        "type":"function",
                        "nodes":[
                           {
                              "label":"one",
                              "type":"task",
                              "nodes":[]
                           },
                           {
                              "label":"two",
                              "type":"task",
                              "nodes":[]
                           }
                        ]
                     }
                  ]
               },
               {
                  "label":"<parallel>",
                  "type":"function",
                  "nodes":[
                     {
                        "label":"three",
                        "type":"task",
                        "nodes":[]
                     },
                     {
                        "label":"<anonymous>",
                        "type":"function",
                        "nodes":[]
                     }
                  ]
               }
            ]
         }
      ]
   }
]
*/

`gulp.registry([registry])` 方法

Get or set the underlying task registry. Inherited from undertaker; see the undertaker documention on registries. Using this, you can change registries that enhance gulp in different ways. Utilizing a custom registry has at least three use cases:

获取或设置底层的任务注册表。这个方法继承自 undertaker；请参见 undertaker 文档的注册项部分。这个方法可帮助你修改注册表，进而允许你以各种不同的方式来增强 Gulp。至少在以下三种应用场景下会到自定义注册表：

Sharing tasks
Sharing functionality (e.g. you could override the task prototype to add some additional logging, bind task metadata or include some config settings.)
Handling other behavior that hooks into the registry lifecycle (see gulp-hub for an example)

共享任务
共享功能（比如说，你可以覆盖任务的原型来增加一些额外的日志功能、绑定任务元数据或加入某些配置信息等）
处理其它在注册表的生命周期内的挂钩子的行为（这方面的例子可以参见 gulp-hub）

To build your own custom registry see the undertaker documentation on custom registries.

如果要建立你自己的自定注册表，请参见 undertaker 文档中的自定义注册表部分。

`registry` 参数

A registry instance. When passed in, the tasks from the current registry will be transferred to the new registry and then current registry will be replaced with the new registry.

一个注册表实例。当传入这个参数时，当前注册表中的任务将会被转移到新的注册表中，而且当前注册表会被替换为这个新的注册表。

Example

示例

This example shows how to create and use a simple custom registry to add tasks.

下面这段示例展示了如何创建并使用一个简单的自定义注册表来添加任务。

//gulpfile.js
var gulp = require('gulp');

var companyTasks = require('./myCompanyTasksRegistry.js');

gulp.registry(companyTasks);

gulp.task('one', gulp.parallel('someCompanyTask', function(done) {
  console.log('in task one');
  done();
}));

//myCompanyTasksRegistry.js
var util = require('util');

var DefaultRegistry = require('undertaker-registry');

function MyCompanyTasksRegistry() {
  DefaultRegistry.call(this);
}
util.inherits(MyCompanyTasksRegistry, DefaultRegistry);

MyCompanyTasksRegistry.prototype.init = function(gulp) {
  gulp.task('clean', function(done) {
    done();
  });
  gulp.task('someCompanyTask', function(done) {
    console.log('performing some company task.');
    done();
  });
};

module.exports = new MyCompanyTasksRegistry();

原文版本：2016-05-13 （如果原文已更新，请提醒我。）

The text was updated successfully, but these errors were encountered:

hax · 2015-11-10T09:34:35Z

“polling”是轮询。

cssmagic · 2015-11-10T09:39:55Z

@hax 谢谢指正。

mcattx · 2015-11-10T10:31:17Z

我记得 Gulp 几个月前就说要放 4.0 了，然而等了好久还是没出来。orz

yisibl · 2015-11-11T01:59:42Z

@TitanCat 那估计你还得等好久 😂 😂

yisibl · 2015-11-11T02:01:44Z

@cssmagic 貌似 gulp 在官方文档中除了 Logo 都是小写。

cssmagic · 2015-11-11T02:31:03Z

@yisibl
我也纠结过这个问题。但这篇文档里是大小写混用的，我也无所适从。算了，我干脆统一成首字母大写吧。

hax · 2015-11-11T06:27:57Z

看了下原文，其实只有一段是大写的（来自于一个commit），所以可以认为是笔误吧。全小写或许比较好。

xiaoyu2er · 2016-05-25T03:58:50Z

@cssmagic 可以在 gulp.src(globs, options) 后面补充 options.cwd 的说明, 之前的文档遗漏了, 但是还是很常用. 现在文档已经加上了.

options.cwd

The working directory the folder is relative to.

Type: String

Default: process.cwd()

gulpjs/gulp#1645

cssmagic · 2016-10-29T17:02:23Z

@xiaoyu2er
谢谢提示。但我认为这一段并不需要加进来，因为这个选项本来就是 node-glob 原生支持的选项，并不是 Gulp 新增的选项。文档中已经说了：

除了 node-glob 和 glob-stream 所支持的选项之外，Gulp 还增加了一些额外的选项……

如果 cwd 要加进来，那么 node-glob 的其它选项要不要加进来呢？

（BTW，这个选项在 Gulp 3 的文档中也是没有列出来的。）

xiaoyu2er · 2016-10-30T02:19:07Z

@cssmagic
https://github.com/gulpjs/gulp/blob/master/docs/API.md#optionscwd

其实是有的, 虽然并不需要单列, 不过考虑到很多使用者用到的参数并不是很多, 而且这个参数又很常用....

cssmagic · 2016-10-31T02:07:42Z

@xiaoyu2er
理解你的意思。不过原则还是要有的。 😉

另外，你列出的 gulp.dest() 的 cwd 选项跟 gulp.src() 的 cwd 选项并不是一回事。

xiaoyu2er · 2016-10-31T09:07:40Z

@cssmagic 👍

(不过你看, 这个选项确实有用啊!....)

cssmagic mentioned this issue Nov 10, 2015

Gulp 4 的文档准备翻译吗？ lisposter/gulp-docs-zh-cn#2

Closed

cssmagic added the Gulp label Nov 10, 2015

yutingzhao1991 mentioned this issue Nov 15, 2015

文章更新 [ 2015-11-08 - 2015-11-14 ] yutingzhao1991/github-blogs-weekly#9

Open

cssmagic mentioned this issue Dec 21, 2015

[译] Gulp 4 入门指南 baixing/FE-Blog#7

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[译] Gulp 4.0 API 文档 #55

[译] Gulp 4.0 API 文档 #55

cssmagic commented Nov 10, 2015 •

edited

Loading

索引

hax commented Nov 10, 2015

cssmagic commented Nov 10, 2015

mcattx commented Nov 10, 2015

yisibl commented Nov 11, 2015

yisibl commented Nov 11, 2015

cssmagic commented Nov 11, 2015

hax commented Nov 11, 2015

xiaoyu2er commented May 25, 2016

cssmagic commented Oct 29, 2016 •

edited

Loading

xiaoyu2er commented Oct 30, 2016

cssmagic commented Oct 31, 2016

xiaoyu2er commented Oct 31, 2016

[译] Gulp 4.0 API 文档 #55

[译] Gulp 4.0 API 文档 #55

Comments

cssmagic commented Nov 10, 2015 • edited Loading

[译] Gulp 4.0 API 文档

索引

gulp.src(globs[, options]) 方法

globs 参数

options 参数

options.cwd 选项

options.buffer 选项

options.read 选项

options.base 选项

options.since 选项

options.passthrough 选项

options.allowEmpty 选项

gulp.dest(path[, options]) 方法

path 参数

options 参数

options.cwd 选项

options.mode 选项

options.dirMode 选项

options.overwrite 选项

gulp.symlink(folder[, options]) 方法

folder 参数

options 参数

options.cwd 选项

options.dirMode 选项

gulp.task([name,] fn) 方法

name 参数

fn 参数

fn properties

fn 参数的属性

fn.name 属性

fn.displayName 属性

fn.description 属性

Async support

异步任务支持

Accept a callback

接受一个回调函数

Return a stream

返回一个 stream

Return a promise

返回一个 promise

Return a child process

返回一个子进程

Return a RxJS observable

返回一个 RxJS 可观察事件流

gulp.lastRun(taskName, [timeResolution]) 方法

taskName 参数

timeResolution 参数

gulp.parallel(...tasks) 方法

tasks 参数

gulp.series(...tasks) 方法

tasks 参数

gulp.watch(globs[, opts], fn) 方法

globs 参数

opts 参数

fn 参数

fn 的 path 参数

fn 的 stats 参数

watcher methods

监视器的各种方法

watcher.close() 方法

watcher.add(glob) 方法

watcher.unwatch(glob) 方法

gulp.tree(options) 方法

options 参数

options.deep 选项

Example gulpfile

gulpfile 示例

Example tree output

树形结构输出示例

gulp.registry([registry]) 方法

registry 参数

Example

示例

hax commented Nov 10, 2015

cssmagic commented Nov 10, 2015

mcattx commented Nov 10, 2015

cssmagic commented Nov 10, 2015 •

edited

Loading

`gulp.src(globs[, options])` 方法

`globs` 参数

`options` 参数

`options.cwd` 选项

`options.buffer` 选项

`options.read` 选项

`options.base` 选项

`options.since` 选项

`options.passthrough` 选项

`options.allowEmpty` 选项

`gulp.dest(path[, options])` 方法

`path` 参数

`options` 参数

`options.cwd` 选项

`options.mode` 选项

`options.dirMode` 选项

`options.overwrite` 选项

`gulp.symlink(folder[, options])` 方法

`folder` 参数

`options` 参数

`options.cwd` 选项

`options.dirMode` 选项

`gulp.task([name,] fn)` 方法

`name` 参数

`fn` 参数

`fn` 参数的属性

`fn.name` 属性

`fn.displayName` 属性

`fn.description` 属性

`gulp.lastRun(taskName, [timeResolution])` 方法

`taskName` 参数

`timeResolution` 参数

`gulp.parallel(...tasks)` 方法

`tasks` 参数

`gulp.series(...tasks)` 方法

`tasks` 参数

`gulp.watch(globs[, opts], fn)` 方法

`globs` 参数

`opts` 参数

`fn` 参数

`fn` 的 `path` 参数

`fn` 的 `stats` 参数

`watcher.close()` 方法

`watcher.add(glob)` 方法

`watcher.unwatch(glob)` 方法

`gulp.tree(options)` 方法

`options` 参数

`options.deep` 选项

`gulp.registry([registry])` 方法

`registry` 参数

cssmagic commented Oct 29, 2016 •

edited

Loading