watch()

Позволяет просматривать глобы и запускать задачу при изменении. Задачи обрабатываются одинаково с остальной частью системы задач.

Применение

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

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

// тело опущено

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)".

Опции

наименование	тип	по умолчанию	примечание
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 c path.join(). Эта опция передается напрямую chokidar.
disableGlobbing	boolean	false	Если true, все globs обрабатываются как буквальные имена путей, даже если они содержат специальные символы. Эта опция передается напрямую chokidar.
usePolling	boolean	false	Если установлено значение false, наблюдатель будет использовать fs.watch() (или fsevents на Mac) для просмотра. Если 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() для измененных файлов - замедлит просмотрщик файлов. Объект fs.Stat доступен только в том случае, если вы напрямую используете экземпляр chokidar. Эта опция передается напрямую 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	string array	Дополнительные globs, на которые следует обратить внимание.

watcher.unwatch(globs)

Удаляет наблюдаемые глобсы, в то время как наблюдатель продолжает работу с оставшимися путями.

параметр	тип	примечание
globs	string array	Глобсы, которые нужно удалить.