watch()

优质

小牛编辑

121浏览

2023-12-01

监听 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

详情参见下文返回值

可能出现的错误

当以 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)

参数	类型	描述
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。