watch()#

允许监视 glob，并在发生更改时运行任务。任务与任务系统的其他部分统一处理。

用法#

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

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

签名#

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

参数#

参数	类型	说明
globs (必需)	字符串数组	Globs 在文件系统上监视。
options	对象	在下面的选项中详细说明。
task	函数字符串	由 `series()` 和 `parallel()` 生成的任务函数或复合任务。

返回#

一个 chokidar 实例，用于精细控制监视设置。

错误#

当将非字符串或包含任何非字符串的数组作为 globs 传递时，抛出错误，消息为“提供非字符串作为监视路径”。

当将字符串或数组作为 task 传递时，抛出错误，消息为“监视任务必须是一个函数（可选地通过使用 gulp.parallel 或 gulp.series 生成）”。

选项#

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

watcher.on('add', function(path, stats) {
 console.log(`文件 ${path} 已添加`);
});

watcher.on('unlink', function(path, stats) {
 console.log(`文件 ${path} 已移除`);
});

watcher.close();

watcher.on(eventName, eventHandler)

参数	类型	说明
eventName	字符串	可以监视的事件为 `'add'`、`'addDir'`、`'change'`、`'unlink'`、`'unlinkDir'`、`'ready'`、`'error'` 或 `'all'`。
eventHandler	函数	在指定事件发生时调用的函数。下表中详细说明了参数。

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

watcher.close()

关闭文件监视器。关闭后，将不再发出任何事件。

watcher.add(globs)

向已运行的监视器实例添加其他 glob。

参数	类型	说明
globs	字符串数组	要监视的其他 glob。

watcher.unwatch(globs)

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

参数	类型	说明
globs	字符串数组	要移除的 glob。