Bu sayfa, Cloud Translation API ile çevrilmiştir.

Workbox v2'den v3'e geçiş

Bu kılavuz, Workbox v3'te kullanıma sunulan değişikliklere odaklanmaktadır ve Workbox v2 kurulumundan yükseltme yaparken yapmanız gereken değişikliklere ilişkin örnekler içerir.

Şu anda eski sw-precache/sw-toolbox kombinasyonunu kullanıyor ve Workbox'a ilk kez geçiş yapmak istiyorsanız size yardımcı olabilecek farklı bir taşıma rehberinden yararlanabilirsiniz.

v3 Arka Planı

Workbox'ın v3 sürümü, mevcut kod tabanında önemli bir yeniden düzenleme yapılmasını temsil ediyor. Kapsayıcı hedefler şunlardır:

Çalışma Kutusu'nun boyutunu en aza indirin. İndirilen ve yürütülen Service Worker çalışma zamanı kodu miktarı azaltıldı. Herkesi monolitik bir pakete dahil etmek yerine çalışma zamanında yalnızca kullandığınız belirli özelliklerin kodu içe aktarılır.
Workbox'ta CDN bulunur. Workbox çalışma zamanı kitaplıklarına erişim için standart seçenek olarak tam desteklenen, Google Cloud Storage tabanlı CDN barındırma hizmeti sunuyoruz. Bu sayede, Workbox'ın çalışmaya başlaması kolaylaşır.
Daha iyi hata ayıklama ve günlük kaydı. Hata ayıklama ve günlük kaydı deneyimi büyük ölçüde iyileştirildi. Bir localhost kaynağından Çalışma Kutusu kullanıldığında ve tüm günlük kaydı ile onaylamalar üretim derlemelerinden kaldırıldığında hata ayıklama günlükleri varsayılan olarak etkinleştirilir.
İyileştirilmiş web paketi eklentisi. workbox-webpack-plugin, web paketi derleme sürecine daha yakın şekilde entegre olarak, derleme ardışık düzenindeki tüm öğeleri önbelleğe almak istediğinizde sıfır yapılandırma kullanım alanına olanak tanır.

Bu hedeflere ulaşmak ve önceki arayüzün tuhaf gelen veya anti kalıplara yol açan bazı yönlerini temizlemek; v3 sürümünde yıkıcı birkaç değişiklik yapılması gerekiyordu.

Zarar Veren Değişiklikler

Derleme Yapılandırması

Aşağıdaki değişiklikler, ortak bir yapılandırma seçeneği grubunu paylaşan tüm derleme araçlarımızın (workbox-build, workbox-cli, workbox-webpack-plugin) davranışını etkiler.

'fastest' işleyici adı daha önce geçerliydi ve runtimeCaching yapılandırılırken 'staleWhileRevalidate' için takma ad olarak değerlendiriliyordu. Artık geçerli değil ve geliştiricilerin doğrudan 'staleWhileRevalidate' kullanmaya başlaması gerekiyor.
Birkaç runtimeCaching.options özellik adı güncellendi. Ayrıca, geçersiz yapılandırma kullanılırsa derlemenin başarısız olmasına yol açacak ek parametre doğrulaması da kullanılıyor. Şu anda desteklenen seçeneklerin listesi için runtimeCaching belgelerine bakın.

workbox-background-sync

maxRetentionTime yapılandırma parametresi artık milisaniye sayısı yerine dakika sayısı olarak yorumlanıyor.
Artık sıra adını temsil eden zorunlu bir dize bulunmaktadır. Bu dize, Eklenti veya bağımsız sınıf oluşturulurken ilk parametre olarak iletilmesi gerekir. (Bu, daha önce seçeneklerin bir özelliği olarak geçiriliyordu.) Güncellenmiş API yüzeyi için belgeleri inceleyin.

workbox-broadcast-cache-update

Artık Eklenti veya bağımsız sınıf oluşturulurken ilk parametre olarak aktarılması gereken, kanal adını temsil eden zorunlu bir dize bulunmaktadır.

Örneğin, v2'de Eklenti sınıfını şu şekilde başlatırsınız:

new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
  channelName: 'cache-updates',
  headersToCheck: ['etag'],
});

v3'te eşdeğer kullanım:

new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});

Güncellenmiş API yüzeyi için belgeleri inceleyin.

workbox-build

Varsayılan olarak, glob kalıp eşleştirme artık follow: true seçenekleri (sembol bağlantılardan sonra gelecek) ve strict: true ("olağan dışı" hatalara daha az toleranslı) ile gerçekleştirilecektir. Derleme yapılandırmanızda globFollow: false ve/veya globStrict: false ayarlarını yaparak ikisinden birini devre dışı bırakabilir ve önceki davranışa dönebilirsiniz.
workbox-build içindeki işlevlerin tümü, döndürdükleri yanıtlarda ek bir özellik (warnings) döndürür. v2'de önemli hata olarak değerlendirilen bazı senaryolara artık izin verilmektedir, ancak bunlar bir dize dizisi olan warnings aracılığıyla bildirilmiştir.

v2'de generateSW yöntemini şu şekilde çağırabilirsiniz:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
  .catch((error) => console.error(`Something went wrong: ${error}`));

Aynı kodu v3'te de kullanabilirsiniz, ancak warnings olup olmadığını kontrol etmek ve bunları günlüğe kaydetmek iyi bir fikirdir:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size, warnings}) => {
    for (const warning of warnings) {
      console.warn(warning);
    }
    console.log(`Precached ${count} files, totalling ${size} bytes.`);
  })
  .catch((error) => console.error(`Something went wrong: ${error}`));

v2'de kendi özel ManifestTransform işlevlerini yazan geliştiricilerin, manifest dizisini bir nesne içinde döndürmesi gerekir (yani, return manifestArray; yerine return {manifest: manifestArray}; kullanmanız gerekir).mBu, eklentinizin isteğe bağlı bir warnings özelliği eklemesine olanak tanır. Bu özellik, önemli olmayan uyarı bilgileri içeren bir dize dizisi olmalıdır.

v2'de özel bir ManifestTransform yazdıysanız şuna benzer bir kod yazın:

const cdnTransform = manifestEntries => {
  return manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
};

v3 eşdeğeri şuna sahiptir:

const cdnTransform = manifestEntries => {
  const manifest = manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
  return {manifest, warnings: []};
};

getFileManifestEntries() işlevi getManifest() olarak yeniden adlandırıldı ve döndürülen taahhüt artık önceden önbelleğe alınmış URL'ler hakkında ek bilgiler içeriyor.

Kod, v2'de aşağıdaki gibidir:

const manifestEntries = await workboxBuild.getFileManifestEntries({...});

aşağıdaki gibi yeniden yazılabilir:

const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.

generateFileManifest() işlevi kaldırıldı. Geliştiricilerin bunun yerine getManifest() öğesini çağırmaları ve verileri diske uygun biçimde yazmak için yanıtı kullanmaları önerilir.

workbox-cache-expiration

Eklenti API'si değişmedi. Bu, çoğu geliştiricinin kullanacağı moddur. Bununla birlikte, API'yi bağımsız bir sınıf olarak kullanan geliştiricileri etkileyen önemli API değişiklikleri bulunmaktadır. Güncellenmiş API yüzeyi için belgeleri inceleyin.

workbox-cli

Geliştiriciler, desteklenen eksiksiz bir parametre grubu için KSA'yı --help işaretiyle çalıştırabilir.

İkili program komut dosyası için workbox-cli takma adı desteği kaldırıldı. İkili programa artık yalnızca workbox olarak erişilebilir.
generate:sw ve inject:manifest v2 komutları, sürüm 3'te generateSW ve injectManifest olarak yeniden adlandırıldı.
v2'de, varsayılan yapılandırma dosyasının (açıkça belirtilmediğinde kullanılır) geçerli dizinde workbox-cli-config.js olduğu varsayılıyordu. v3'te bu değer workbox-config.js.

Bu durum, birlikte ele alındığında v2'de şu anlama gelir:

$ workbox inject:manifest

"inject manifest"i çalıştırır derleme işlemi (workbox-cli-config.js kaynağından okunan bir yapılandırmayı kullanarak ve v3'te):

$ workbox injectManifest

aynı işlemi gerçekleştirir ancak workbox-config.js üzerinden yapılandırmayı okur.

çalışma kutusu-önbelleğe alma

precache() yöntemi daha önce hem önbellek değişikliklerini yapıyor hem de önbelleğe alınan girişleri sunmak için yönlendirmeyi oluşturuyordu. Artık precache() yalnızca önbellek girişlerini değiştiriyor ve bu önbellekteki yanıtları sunmak için yeni bir yöntem olan addRoute(), bir rota kaydediyor. İkisi bir arada önceki işlevi kullanmak isteyen geliştiriciler precacheAndRoute() numaralı telefonu aramaya geçiş yapabilir.
Daha önce WorkboxSW oluşturucusu aracılığıyla yapılandırılan çeşitli seçenekler, artık workbox.precaching.precacheAndRoute([...], options) öğesine options parametresi olarak aktarılmaktadır. Bu seçenekler için varsayılan ayarlar (yapılandırılmadığında) referans dokümanlarda listelenmiştir.
Varsayılan olarak, dosya uzantısı olmayan URL'ler, .html uzantısı içeren bir önbellek girişiyle eşleşip eşleşmediğini otomatik olarak kontrol eder. Örneğin, /path/to/index için bir istek yapılırsa (önceden önbelleğe alınmamış) ve /path/to/index.html için önbelleğe alınmış bir giriş varsa bu önceden önbelleğe alınmış giriş kullanılır. Geliştiriciler, seçenekleri workbox.precaching.precacheAndRoute() içine iletirken {cleanUrls: false} politikasını ayarlayarak bu yeni davranışı devre dışı bırakabilir.
workbox-broadcast-update, artık önceden önbelleğe alınmış öğelerin önbellek güncellemelerini duyurmak için otomatik olarak yapılandırılmayacak.

v2'de aşağıdaki kod:

const workboxSW = new self.WorkboxSW({
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
  precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);

v3 eşdeğeri şuna sahiptir:

workbox.precaching.addPlugins([
    new workbox.broadcastUpdate.Plugin('precache-updates')
]);

workbox.precaching.precacheAndRoute([...], {
  cleanUrls: false,
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
});

çalışma kutusu yönlendirmesi

Daha önce WorkboxSW nesnesinin workbox.router.* ad alanı aracılığıyla workbox-routing kullanan geliştiricilerin yeni ad alanına (workbox.routing.*) geçmesi gerekiyor.
Rotalar artık ilk kaydedilen kazanma sırasına göre değerlendiriliyor. Bu, v2'de kullanılan Route değerlendirmesinin zıttı sıralamasıdır ve son kaydedilen Route değerine öncelik verilir.
ExpressRoute sınıfı ve "Ekspres-stil" desteği joker karakterler kaldırıldı. Bu, workbox-routing boyutunu önemli ölçüde küçültür. workbox.routing.registerRoute() parametresi için ilk parametre olarak kullanılan dizeler artık tam eşleme olarak değerlendirilecek. Joker karakter veya kısmi eşleşmeler, RegExp tarafından işlenmelidir. İstek URL'sinin bir kısmı veya tamamı ile eşleşen tüm RegExp öğeleri rotayı tetikleyebilir.
Router sınıfının addFetchListener() yardımcı yöntemi kaldırıldı. Geliştiriciler kendi fetch işleyicilerini açıkça ekleyebilir veya workbox.routing tarafından sağlanan arayüzü kullanabilir. Bu durumda, dolaylı olarak bir fetch işleyicisi oluştururlar.
registerRoutes() ve unregisterRoutes() yöntemleri kaldırıldı. Tek bir Route üzerinde çalışan bu yöntemlerin sürümleri değiştirilmedi. Aynı anda birden fazla rota kaydetmesi veya kaydını iptal etmesi gereken geliştiriciler bunun yerine registerRoute() veya unregisterRoute() üzerinde bir dizi çağrı yapmalıdır.

v2'de aşağıdaki kod:

const workboxSW = new self.WorkboxSW();

workboxSW.router.registerRoute(
  '/path/with/.*/wildcard/',
  workboxSW.strategies.staleWhileRevalidate()
);

workboxSW.router.registerRoute(
  new RegExp('^https://example.com/'),
  workboxSW.strategies.networkFirst()
);

v3 eşdeğeri şuna sahiptir:

workbox.routing.registerRoute(
  new RegExp('^https://example.com/'),
  workbox.strategies.networkFirst()
);

workbox.routing.registerRoute(
  new RegExp('^/path/with/.*/wildcard'),
  workbox.strategies.staleWhileRevalidate()
);

çalışma kutusu stratejileri (eski adıyla çalışma kutusu çalışma zamanı önbelleğe alma)

workbox-runtime-caching modülü artık resmi olarak workbox-strategies adını aldı ve yeni adıyla npm ürününde yayınlandı.
Bir stratejide önbellek adı sağlanmadan önbellek son geçerlilik tarihinin kullanılması artık geçerli değildir. 2. sürümde bu mümkündü:

workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

Bu durum, varsayılan önbellekte girişlerin süresinin dolmasına neden olur ve bu beklenmedik bir durumdur. v3'te önbellek adı gereklidir:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});

cacheWillMatch yaşam döngüsü yöntemi cachedResponseWillBeUsed olarak yeniden adlandırıldı. cacheWillMatch uygulamasına tepki veren kendi eklentilerini yazmadıkları sürece geliştiriciler bu değişikliği göremezler.
Bir stratejiyi yapılandırırken eklentileri belirtmek için kullanılan söz dizimi değişti. Her eklentinin, strateji yapılandırmasının plugins özelliğinde açıkça listelenmesi gerekir.

v2'de aşağıdaki kod:

const workboxSW = new self.WorkboxSW();

const networkFirstStrategy = workboxSW.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  cacheExpiration: {
    maxEntries: 50,
  },
  cacheableResponse: {
    statuses: [0, 200],
  },
});

v3 eşdeğeri şuna sahiptir:

const networkFirstStrategy = workbox.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
    new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
  ],
});

Daha fazla bilgi için "Eklentileri Kullanma" bölümüne bakın. rehberini inceleyin.

çalışma kutusu-sw

workbox-sw, hafif bir "yükleyici" olarak yeniden yazıldı. yeni bir kodlayıcı içerir. Geliştiriciler, WorkboxSW sınıfının yeni bir örneğini oluşturmak yerine, genel ad alanında otomatik olarak kullanıma sunulan mevcut bir örnekle etkileşim kurar.

Önceki sürüm 2.

importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');

const workbox = new WorkboxSW({
  skipWaiting: true,
  clientsClaim: true,
  // etc.
});

workbox.router.registerRoute(...);

v3'te workbox-sw.js komut dosyasını içe aktarmanız yeterlidir. Kullanıma hazır bir örnek, genel ad alanında otomatik olarak workbox biçiminde olur:

importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);

skipWaiting ve clientsClaim artık WorkboxSW oluşturucuya iletilen seçenek değil. Bunun yerine, workbox.clientsClaim() ve workbox.skipWaiting() yöntemleri olarak değiştirildi.
Daha önce v2 oluşturucuda desteklenen handleFetch seçeneği, v3'te artık desteklenmemektedir. Herhangi bir getirme işleyici çağrılmadan hizmet çalışanını test etmek için benzer bir işleve ihtiyaç duyan geliştiriciler, "Ağı atlama" özelliğini kullanabilirler. Bu seçenek, Chrome'un Geliştirici Araçları'nda mevcuttur.

Chrome Geliştirici Araçları'ndaki Ağı Atla seçeneği

workbox-webpack-plugin

Eklenti önemli ölçüde yeniden yazılmıştır ve çoğu durumda "sıfır yapılandırmada" kullanılabilir yatırım yapmanız önemlidir. Güncellenmiş API yüzeyi için belgeleri inceleyin.

API artık GenerateSW ve InjectManifest olmak üzere iki sınıf sunuyor. Bu, modun swSrc varlığına göre değiştiği v2 davranışı ile modlar arasındaki geçişin açık olmasını sağlar.
Varsayılan olarak, web paketi derleme ardışık düzenindeki öğeler önbellekte tutulur ve globPatterns özelliğinin yapılandırılması artık gerekmez. globPatterns ürününü kullanmaya devam etmenizin tek nedeni, web paketi derlemenize dahil olmayan öğeleri önceden önbelleğe almanız gerekmesidir. Genel olarak, v3 eklentisine geçiş yaparken glob tabanlı önceki yapılandırmaların tümünü kaldırarak başlamalı ve bunları yalnızca özel olarak ihtiyacınız varsa yeniden eklemelisiniz.

Yardım alma

Çoğu taşıma işleminin basit olacağını tahmin ediyoruz. Bu kılavuzda ele alınmayan sorunlarla karşılaşırsanız GitHub'da bir sorun açarak bize bildirin.