watch()#

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

¥Allows watching globs and running a task when a change occurs. Tasks are handled uniformly with the rest of the task system.

用法#

¥Usage

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

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

签名#

¥Signature

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

参数#

¥Parameters

参数	type	note
全局变量（必填）	字符串数组	通配符在文件系统上监视。
options	object	详细见下文选项。
task	函数字符串	任务功能或组合任务 - 由 `series()` 和 `parallel()` 生成。

返回#

¥Returns

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

¥An instance of chokidar for fine-grained control over your watch setup.

错误#

¥Errors

当非字符串或包含任何非字符串的数组作为 globs 传递时，会引发错误并显示消息 "提供非字符串作为监视路径"。

¥When a non-string or array with any non-strings is passed as globs, throws an error with the message, "Non-string provided as watch path".

当字符串或数组作为 task 传递时，会引发错误并显示消息 "watch 任务必须是一个函数（可以使用 gulp.parallel 或 gulp.series 生成）"。

¥When a string or array is passed as task, throws an error with the message, "watch task has to be a function (optionally generated by using gulp.parallel or gulp.series)".

选项#

¥Options

name	type	default	note
ignoreInitial	boolean	true	如果为 false，则在实例化期间发现文件路径时调用该任务。用于启动时触发任务。注意：此选项传递给 chokidar，但默认为 `true` 而不是 `false`。
delay	number	200	文件更改和任务执行之间的毫秒延迟。允许在执行任务之前等待许多更改，例如对许多文件进行查找和替换。
queue	boolean	true	当为 true 并且任务已在运行时，任何文件更改都会对单个任务执行进行排队。防止长时间运行的任务重叠。
events	字符串数组	[ 'add', 'change', 'unlink' ]	正在监视的事件以触发任务执行。可以是 `'add'`、`'addDir'`、`'change'`、`'unlink'`、`'unlinkDir'`、`'ready'` 和/或 `'error'`。另外 `'all'` 可用，它代表除 `'ready'` 和 `'error'` 之外的所有事件。此选项直接传递给 chokidar。
persistent	boolean	true	如果为 false，观察者将不会保持 Node 进程运行。不建议禁用此选项。此选项直接传递给 chokidar。
ignored	数组字符串 RegExp 函数		定义要忽略的 glob。如果提供了函数，则每个路径将调用该函数两次 - 一次仅使用路径，然后使用路径和该文件的 `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` 为假时才有效。自动过滤掉某些编辑者从 "原子写入" 中出现的工件。如果在删除后指定的毫秒内重新添加文件，则会发生更改事件 - 而不是取消链接然后添加 - 将被触发。此选项直接传递给 chokidar。

Chokidar 实例#

¥Chokidar instance

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

¥The watch() method returns the underlying instance of chokidar, providing fine-grained control over your watch setup. Most commonly used to register individual event handlers that provide the path or stats of the changed files.

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

¥When using the chokidar instance directly, you will not have access to the task system integrations, including async completion, queueing, and delay.

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)

¥Registers eventHandler functions to be called when the specified event occurs.

参数	type	note
eventName	string	可以监视的事件有 `'add'`、`'addDir'`、`'change'`、`'unlink'`、`'unlinkDir'`、`'ready'`、`'error'` 或 `'all'`。
eventHandler	function	当指定事件发生时调用的函数。参数详述如下表。

argument	type	note
path	string	更改的文件的路径。如果设置了 `cwd` 选项，则通过删除 `cwd` 使路径成为相对路径。
stats	object	一个 fs.Stat 对象，但也可能是 `undefined`。如果 `alwaysStat` 选项设置为 `true`，则将始终提供 `stats`。

watcher.close()

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

¥Shuts down the file watcher. Once shut down, no more events will be emitted.

watcher.add(globs)

向已运行的观察程序实例添加额外的 glob。

¥Adds additional globs to an already-running watcher instance.

参数	type	note
globs	字符串数组	需要观察的额外的通配符。

watcher.unwatch(globs)

删除正在监视的 glob，同时观察者继续剩余的路径。

¥Removes globs that are being watched, while the watcher continues with the remaining paths.

参数	type	note
globs	字符串数组	要删除的通配符。