watch()

允许监视 globs 并在发生变化时运行任务。任务的处理方式与任务系统的其余部分一致。

使用方法

const { watch } = require('gulp');

watch(['input/*.js', '!input/something.js'], function(cb) {
  // 内容省略
  cb();
});

签名

watch(globs, [options], [task])

参数

参数	类型	说明
globs (必填)	string array	在文件系统上监视的 Globs。
options	object	详细信息请参见下方的选项。
task	function string	任务函数或由 series() 和 parallel() 生成的组合任务。

返回值

chokidar 的实例，用于对监视设置进行精细控制。

错误

当传递非字符串或包含任何非字符串的数组作为 globs 时，抛出错误，错误信息为"Non-string provided as watch path"（提供了非字符串作为监视路径）。

当传递字符串或数组作为 task 时，抛出错误，错误信息为"watch task has to be a function (optionally generated by using gulp.parallel or gulp.series)"（监视任务必须是函数（可选地由 gulp.parallel 或 gulp.series 生成））。

选项

名称	类型	默认值	说明
ignoreInitial	boolean	true	如果为 false，则在实例化过程中发现文件路径时调用任务。用于在启动期间触发任务。 注意： 此选项传递给 chokidar，但默认值为 true，而不是 false。
delay	number	200	文件更改和任务执行之间的毫秒延迟。允许在执行任务之前等待多个更改，例如对多个文件进行查找和替换。
queue	boolean	true	当为 true 且任务已在运行时，任何文件更改都将排队等待单个任务执行。防止长时间运行的任务重叠。
events	string array	[ 'add', 'change', 'unlink' ]	被监视以触发任务执行的事件。可以是 'add'、'addDir'、'change'、'unlink'、'unlinkDir'、'ready' 和/或 'error'。此外，还可以使用 'all'，表示除 'ready' 和 'error' 之外的所有事件。 此选项直接传递给 chokidar。
persistent	boolean	true	如果为 false，观察器将不会保持 Node 进程运行。不建议禁用此选项。 此选项直接传递给 chokidar。
ignored	array string RegExp function		定义要忽略的 globs。如果提供函数，它将对每个路径调用两次 - 一次只有路径，然后是路径和该文件的 fs.Stats 对象。 此选项直接传递给 chokidar。
followSymlinks	boolean	true	当为 true 时，符号链接和链接文件的更改都会触发事件。如果为 false，则只有符号链接的更改才会触发事件。 此选项直接传递给 chokidar。
cwd	string		将与任何相对路径组合形成绝对路径的目录。对于绝对路径会被忽略。用于避免将 globs 与 path.join() 组合。 此选项直接传递给 chokidar。
disableGlobbing	boolean	false	如果为 true，所有 globs 都被视为字面路径名，即使它们有特殊字符。 此选项直接传递给 chokidar。
usePolling	boolean	false	当为 false 时，观察器将使用 fs.watch()（或在 Mac 上使用 fsevents）进行监视。如果为 true，则使用 fs.watchFile() 轮询 - 在网络或其他非标准情况下成功监视文件所需。覆盖 useFsEvents 默认值。 此选项直接传递给 chokidar。
interval	number	100	与 usePolling: true 组合使用。文件系统轮询的间隔。 此选项直接传递给 chokidar。
binaryInterval	number	300	与 usePolling: true 组合使用。二进制文件的文件系统轮询间隔。 此选项直接传递给 chokidar。
useFsEvents	boolean	true	当为 true 时，如果可用，则使用 fsevents 进行监视。如果明确设置为 true，则取代 usePolling 选项。如果设置为 false，则自动将 usePolling 设置为 true。 此选项直接传递给 chokidar。
alwaysStat	boolean	false	如果为 true，始终在更改的文件上调用 fs.stat() - 将减慢文件监视器速度。仅当直接使用 chokidar 实例时，fs.Stat 对象才可用。 此选项直接传递给 chokidar。
depth	number		指示将监视多少级嵌套目录。 此选项直接传递给 chokidar。
awaitWriteFinish	boolean	false	不要使用此选项，请使用 delay 代替。 此选项直接传递给 chokidar。
ignorePermissionErrors	boolean	false	设置为 true 以监视没有读取权限的文件。然后，如果由于 EPERM 或 EACCES 错误而导致监视失败，将静默跳过这些文件。 此选项直接传递给 chokidar。
atomic	number	100	仅当 useFsEvents 和 usePolling 为 false 时激活。自动过滤掉由某些编辑器的"原子写入"产生的工件。如果文件在被删除后的指定毫秒内重新添加，将发出更改事件 - 而不是先取消链接然后添加。 此选项直接传递给 chokidar。

Chokidar 实例

watch() 方法返回 chokidar 的底层实例，提供对监视设置的精细控制。最常用于注册提供已更改文件的 path 或 stats 的单独事件处理程序。

当直接使用 chokidar 实例时，您将无法访问任务系统集成，包括异步完成、排队和延迟。

const { watch } = require('gulp');

const watcher = watch(['input/*.js']);

watcher.on('change', function(path, stats) {
  console.log(`File ${path} was changed`);
});

watcher.on('add', function(path, stats) {
  console.log(`File ${path} was added`);
});

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

watcher.close();

watcher.on(eventName, eventHandler)

注册在指定事件发生时要调用的 eventHandler 函数。

参数	类型	说明
eventName	string	可以监视的事件有 'add'、'addDir'、'change'、'unlink'、'unlinkDir'、'ready'、'error' 或 'all'。
eventHandler	function	指定事件发生时要调用的函数。参数详见下表。

参数	类型	说明
path	string	已更改文件的路径。如果设置了 cwd 选项，将通过删除 cwd 使路径变为相对路径。
stats	object	一个 fs.Stat 对象，但可能是 undefined。如果 alwaysStat 选项设置为 true，则始终提供 stats。

watcher.close()

关闭文件观察器。一旦关闭，将不再发出任何事件。

watcher.add(globs)

向已运行的观察器实例添加额外的 globs。

参数	类型	说明
globs	string array	要监视的额外 globs。

watcher.unwatch(globs)

移除正在监视的 globs，同时观察器继续监视剩余路径。

参数	类型	说明
globs	string array	要删除的 globs。