Это руководство посвящено критическим изменениям, внесенным в Workbox v4, и содержит примеры того, какие изменения необходимо внести при обновлении с Workbox v3.
Критические изменения
предварительное кэширование рабочего ящика
Соглашение об именах для предварительно кэшированных записей было обновлено. Теперь для записей, URL-адресам которых требуется информация о версии (т. е. тех записей, которые содержат поле revision в манифесте предварительного кэширования ), эта информация о версии будет храниться как часть ключа кэша в специальном параметре URL-запроса __WB_REVISION__ , добавленном к исходному URL-адресу. (Раньше эта информация хранилась отдельно от ключей кэша с помощью IndexedDB .)
Разработчикам, которые используют преимущества предварительного кэширования через workbox.precaching.precacheAndRoute() , что является наиболее распространенным вариантом использования, не нужно вносить какие-либо изменения в конфигурацию своего сервис-воркера; после обновления до Workbox v4 кэшированные ресурсы ваших пользователей будут автоматически перенесены в новый формат ключа кэша, и в дальнейшем предварительно кэшированные ресурсы будут продолжать обслуживаться так же, как и раньше.
Использование ключей кэша напрямую
Некоторым разработчикам может потребоваться прямой доступ к записям precache, вне контекста workbox.precaching.precacheAndRoute() . Например, вы можете предварительно кэшировать изображение, которое в конечном итоге будет использоваться в качестве «резервного» ответа, когда фактическое изображение невозможно получить из сети.
Если вы используете предварительно кэшированные ресурсы таким образом, начиная с Workbox v4, вам потребуется выполнить дополнительный шаг, чтобы преобразовать исходный URL-адрес в соответствующий ключ кэша, который можно использовать для чтения кэшированной записи. Это можно сделать, вызвав workbox.precaching.getCacheKeyForURL(originURL) .
Например, если вы знаете, что 'fallback.png' предварительно кэшируется:
const imageFallbackCacheKey =
workbox.precaching.getCacheKeyForURL('fallback.png');
workbox.routing.setCatchHandler(({event}) => {
switch (event.request.destination) {
case 'image':
return caches.match(imageFallbackCacheKey);
break;
// ...other fallback logic goes here...
}
});
Очистка старых предварительно кэшированных данных
Изменения, внесенные в предварительное кэширование в Workbox v4, означают, что старые прекеши, созданные в предыдущих версиях Workbox, несовместимы. По умолчанию они остаются как есть, и если вы обновите Workbox v3 до Workbox v4, вы получите две копии всех предварительно кэшированных ресурсов.
Чтобы избежать этого, вы можете добавить вызов workbox.precaching.cleanupOutdatedCaches() напрямую к сервис-воркерам или установить новый параметр cleanupOutdatedCaches: true при использовании инструмента сборки в режиме GenerateSW . Поскольку логика очистки кэша использует соглашения об именовании кэша для поиска старых прекешей, а у разработчиков есть возможность переопределить эти соглашения, мы допустили ошибку в плане безопасности и не включили эту функцию по умолчанию.
Мы призываем разработчиков, которые сталкиваются с какими-либо проблемами при использовании этого метода (например, с ложными срабатываниями при удалении), сообщать нам об этом .
Использование заглавных букв параметра
Два необязательных параметра , которые можно передать в workbox.precaching.precacheAndRoute() и workbox.precaching.addRoute() были переименованы, чтобы стандартизировать наше общее соглашение о использовании заглавных букв. ignoreUrlParametersMatching теперь называется ignoreURLParametersMatching , а cleanUrls теперь называется cleanURLs .
стратегии рабочего ящика
Существует два примерно эквивалентных способа создания экземпляра обработчика в workbox-strategies . Мы отказываемся от фабричного метода в пользу явного вызова конструктора стратегии.
// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});
// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});
Хотя синтаксис фабричного метода продолжит работать в версии 4, при его использовании будет регистрироваться предупреждение, и мы рекомендуем разработчикам выполнить миграцию, прежде чем прекращать поддержку в будущем выпуске версии 5.
синхронизация фона рабочей области
Класс workbox.backgroundSync.Queue был переписан, чтобы предоставить разработчикам больше гибкости и контроля над тем, как запросы добавляются в очередь и воспроизводятся.
В версии 3 класс Queue имел единственный способ добавления запросов в очередь (метод addRequest() ), но не имел возможности изменять очередь или удалять запросы.
В версии 4 метод addRequests() был удален и добавлены следующие методы, подобные массивам:
-
pushRequest() -
popRequest() -
shiftRequest() -
unshiftRequest()
В версии 3 класс Queue также принимал несколько обратных вызовов, которые позволяли наблюдать, когда запросы воспроизводятся ( requestWillEnqueue , requestWillReplay , queueDidReplay ), но большинство разработчиков обнаружили, что помимо наблюдения им нужен контроль над тем, как воспроизводится очередь, в том числе возможность динамически изменять, переупорядочивать или даже отменять отдельные запросы.
В версии 4 эти обратные вызовы были удалены в пользу одного обратного вызова onSync , который вызывается каждый раз, когда браузер предпринимает попытку воспроизведения. По умолчанию обратный вызов onSync вызывает replayRequests() , но если вам нужен больший контроль над процессом воспроизведения, вы можете использовать методы, подобные массиву, перечисленные выше, чтобы воспроизвести очередь так, как вам нравится.
Вот пример пользовательской логики воспроизведения:
const queue = new workbox.backgroundSync.Queue('my-queue-name', {
onSync: async ({queue}) => {
let entry;
while ((entry = await this.shiftRequest())) {
try {
await fetch(entry.request);
} catch (error) {
console.error('Replay failed for request', entry.request, error);
await this.unshiftRequest(entry);
return;
}
}
console.log('Replay complete!');
},
});
Аналогично, класс workbox.backgroundSync.Plugin принимает те же аргументы, что и класс Queue (поскольку он создает экземпляр Queue внутри себя), поэтому он изменился таким же образом.
срок действия рабочего ящика
Пакет npm был переименован в workbox-expiration в соответствии с соглашением об именах, используемым для других модулей. Этот пакет функционально эквивалентен более старому пакету workbox-cache-expiration , который сейчас устарел.
обновление рабочего ящика-трансляции
Пакет npm был переименован в workbox-broadcast-update в соответствии с соглашением об именах, используемым для других модулей. Этот пакет функционально эквивалентен более старому пакету workbox-broadcast-cache-update , который сейчас устарел.
ядро рабочего ящика
В Workbox v3 степень детализации уровней журнала можно контролировать с помощью метода workbox.core.setLogLevel() , которому нужно передать одно из значений в перечислении workbox.core.LOG_LEVELS . Вы также можете прочитать текущий уровень журнала через workbox.core.logLevel .
В Workbox v4 все это было удалено, поскольку все современные инструменты разработчика теперь поставляются с широкими возможностями фильтрации журналов (см. фильтрацию вывода консоли для Chrome Dev Tools).
рабочий ящик-программное обеспечение
Два метода, которые ранее были доступны непосредственно в пространстве имен workbox (которое соответствует модулю workbox-sw ), вместо этого были перемещены в workbox.core . workbox.skipWaiting() стал workbox.core.skipWaiting() , а workbox.clientsClaim() стал workbox.core.clientsClaim() .
Конфигурация инструмента сборки
Изменилось наименование некоторых параметров, которые можно передать в workbox-cli, workbox-build или workbox-webpack-plugin. Всякий раз, когда в имени параметра использовалось «URL», оно устарело в пользу «URL». Это означает, что предпочтительны следующие имена опций:
-
dontCacheBustURLsMatching -
ignoreURLParametersMatching -
modifyURLPrefix -
templatedURLs
Вариант имен этих параметров «URL» по-прежнему работает в версии 4, но приведет к появлению предупреждающего сообщения. Мы рекомендуем разработчикам выполнить миграцию до выпуска версии 5.
Новая функциональность
окно рабочего ящика
Новый модуль workbox-window упрощает процесс регистрации сервис-воркера и обнаружения обновлений, а также предоставляет стандартные средства связи между кодом, выполняющимся в сервис-воркере, и кодом, выполняющимся в контексте window вашего веб-приложения.
Хотя использование workbox-window не является обязательным, мы надеемся, что разработчики найдут его полезным, и рассмотрят возможность переноса части своей рукописной логики, чтобы использовать его при необходимости. Подробнее об использовании workbox-window вы можете узнать в руководстве по модулю .
Пример миграции
Пример реальной миграции с Workbox v3 на v4 можно найти в этом запросе на включение .
Получение помощи
Мы ожидаем, что большинство миграций будут простыми. Если у вас возникнут проблемы, не описанные в этом руководстве, сообщите нам об этом, открыв проблему на GitHub.