Gulp watch()

本文目录结构

watch()

监听 globs 并在发生更改时运行任务。任务与任务系统的其余部分被统一处理。

用法

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

watch(['input/*.js', '!input/something.js'], function(cb) {
  // body omitted
  cb();
});

函数原型

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

参数

参数	类型	描述
globs (required)	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)"（ watch 任务必须是一个函数（可以选择使用 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		Defines globs to be ignored. If a function is provided, it will be called twice per path - once with just the path, then with the path and the fs.Stats object of that file. 此选项被直接传递给 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）(或fsevents)进行监听。如果为 true，则使用 fs.watchFile() 轮询代替——这是通过网络或其他非标准情况成功监听文件所必需的。覆盖 useFsEvents 默认值。
此选项被直接传递给 chokidar.
interval	number	100	与 usePolling: true 配套使用。表示文件系统轮询的间隔。 此选项被直接传递给 chokidar.
binaryInterval	number	300	与 usePolling: true 配套使用。表示文件系统轮询二进制文件的间隔。 此选项被直接传递给 chokidar.
useFsEvents	boolean	true	如果为 true 且 fsevents 可用， 则使用 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 时才激活。自动过滤掉一些编辑器从 “atomic writes” 中产生的工件。如果文件在删除后的指定毫秒内重新添加，则会发出一个更改事件（而不是取消链接然后添加）。
此选项被直接传递给 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)

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.close()

关闭文件监听器。一旦关闭，就不会再发出任何事件。

watcher.add(globs)

watcher.add(globs)

向已经运行的监听器实例添加额外的 globs。

参数	类型	描述
globs	string
array	额外的要监听的 globs

watcher.unwatch(globs)

watcher.unwatch(globs)

删除正在被监听的 globs，而监视程序继续使用剩余的路径。

参数	类型	描述
globs	string
array	要删除的 globs。