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

Workbox v2'den v3'e geçiş

Bu kılavuz, Workbox v3'te yapılan değişiklikleri bozmaya odaklanarak, Workbox v2 kurulumundan yükseltme yaparken yapmanız gereken değişikliklerin örneklerine odaklanmaktadır.

Şu anda eski sw-precache/sw-toolbox kombinasyonunu kullanıyorsanız ve Workbox'a ilk kez geçiş yapmak istiyorsanız aşağıdaki farklı taşıma rehberinden yararlanabilirsiniz.

v3 Arka Planı

Workbox'ın v3 sürümü, mevcut kod tabanında önemli ölçüde yeniden düzenleme yapıldığını gösteriyor. Ana 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 pakete dahil etmek yerine yalnızca kullandığınız belirli özelliklerin kodu çalışma zamanında içe aktarılır.
Workbox'ta CDN var. Workbox çalışma zamanı kitaplıklarına erişmek için standart seçenek olarak tam olarak desteklenen, Google Cloud Storage tabanlı bir CDN barındırma hizmeti sunuyoruz. Böylece, Workbox'ı kurup çalıştırmanız daha kolay.
Daha İyi Hata Ayıklama ve Günlükler. Hata ayıklama ve günlük kaydı deneyimi büyük ölçüde iyileştirildi. Workbox bir localhost kaynağından kullanıldığında ve tüm günlük kaydı ve onaylar ü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üreciyle daha yakından entegre olduğundan derleme ardışık düzenindeki tüm öğeleri önceden önbelleğe almak istediğinizde sıfır yapılandırmalı bir kullanım alanı sağlar.

Bu hedeflere ulaşmak ve önceki arayüzün tuhaf görünen ya da karşıt kalıplara yol açan bazı yönlerini temizlemek için v3 sürümünde bazı bozucu değişiklikler 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 kabul ediliyordu. Artık geçerli olmadığından geliştiriciler doğrudan 'staleWhileRevalidate' kullanımına geçmelidir.
Birkaç runtimeCaching.options özellik adı güncellendi ve geçersiz yapılandırma kullanılması durumunda derlemenin başarısız olmasına neden olacak ek parametre doğrulama işlemi uygulanıyor. Şu anda desteklenen seçeneklerin listesi için runtimeCaching dokümanlarına bakın.

çalışma kutusu-arka plan-senkronizasyon

maxRetentionTime yapılandırma parametresi artık milisaniye sayısı yerine dakika sayısı olarak yorumlanıyor.
Artık, Eklenti veya bağımsız sınıf oluştururken ilk parametre olarak aktarılması gereken, sıra adını temsil eden gerekli bir dize mevcuttur. (Daha önce seçeneklerin özelliği olarak aktarılıyordu.) Güncellenen API yüzeyi için belgelere bakın.

workbox-broadcast-cache-update

Artık, Eklenti veya bağımsız sınıf oluştururken ilk parametre olarak iletilmesi gereken, kanal adını temsil eden bir gerekli dize mevcuttur.

Örneğin, v2'de Eklenti sınıfını aşağıdaki gibi 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üncellenen API yüzeyi için belgelere bakın.

çalışma kutusu oluşturma

Varsayılan olarak, glob kalıp eşleştirme artık seçeneklerle follow: true (sembolik bağlantıları izler) ve strict: true ("olağan dışı" hatalara karşı daha az toleranslıdır) ile gerçekleştirilecektir. Derleme yapılandırmanızda globFollow: false ve/veya globStrict: false ayarlarını yaparak her 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 ele alınan bazı senaryolara artık izin veriliyor ancak bir dize dizisi olan warnings aracılığıyla raporlanıyor.

v2'de generateSW şöyle diyebilirsiniz:

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 nesnede döndürmesi gerekir (yani return manifestArray; yerine return {manifest: manifestArray};).mBu, eklentinizin önemli olmayan uyarı bilgileri içeren bir dize dizisi olması gereken isteğe bağlı warnings özelliğini eklemesine olanak tanır.

v2'de özel bir ManifestTransform yazacaksanız şunun gibi 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;
  });
};

aşağıdaki gibi v3 eşdeğerine 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 sözü artık, önceden önbelleğe alınan URL'ler hakkında ek bilgiler içeriyor.

v2'de aşağıdaki gibi bir kod:

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

v3'te şu şekilde 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() yöntemini çağırmaları ve ilgili yanıtı diske uygun biçimde yazmak için yanıt kullanmaları önerilir.

çalışma kutusu-önbelleği-geçerlilik-geçerlilik-geçerlilik

Eklenti API'sı aynı kaldı. Çoğu geliştirici bu modu kullanacak. Ancak API'yi bağımsız bir sınıf olarak kullanan geliştiricileri etkileyen önemli API değişiklikleri vardır. Güncellenen API yüzeyi için belgelere bakın.

workbox-cli

Geliştiriciler, desteklenen parametrelerin tamamı için KSA'yı --help işaretiyle çalıştırabilir.

İkili komut dosyası için workbox-cli takma adı desteği kaldırıldı. İkili dosyaya artık yalnızca workbox olarak erişilebilir.
generate:sw ve inject:manifest v2 komutları, v3'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ıldı. v3'te özelliğin değeri workbox-config.js.

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

$ workbox inject:manifest

workbox-cli-config.js ve v3'ten okunan bir yapılandırma kullanarak "manifest ekleme" derleme işlemini çalıştırır:

$ workbox injectManifest

aynısını yapar ancak yapılandırmayı workbox-config.js öğesinden okur.

çalışma kutusu önbelleğine alma

precache() yöntemi daha önce hem önbellek değişikliklerini gerçekleştiriyor hem de önbelleğe alınan girişleri sunmak için yönlendirmeyi ayarladı. precache() artık yalnızca önbellek girişlerini değiştiriyor. Yeni yöntem olan addRoute(), önbelleğe alınan bu yanıtları sunmak için bir rota kaydetmek üzere kullanıma sunuldu. Önceki ikisi bir arada işlevi isteyen geliştiriciler precacheAndRoute() uygulamasını çağırmaya geçebilirler.
Daha önce WorkboxSW oluşturucu aracılığıyla yapılandırılan çeşitli seçenekler artık workbox.precaching.precacheAndRoute([...], options) içinde options parametresi olarak aktarılıyor. Bu seçenekler için varsayılanlar, yapılandırılmadığında referans dokümanlarında listelenmiştir.
Varsayılan olarak, dosya uzantısı olmayan URL'lerin .html uzantısı içeren bir önbellek girişiyle eşleşip eşleşmediği otomatik olarak kontrol edilir. Örneğin, /path/to/index için istekte bulunulduğunda (önbelleğe alınmayan) /path/to/index.html için önceden önbelleğe alınmış bir giriş varsa bu ön önbelleğe alınmış giriş kullanılır. Geliştiriciler, seçenekleri workbox.precaching.precacheAndRoute() uygulamasına aktarırken {cleanUrls: false} ayarlayarak bu yeni davranışı devre dışı bırakabilirler.
workbox-broadcast-update artık önceden önbelleğe alınmış öğeler için önbellek güncellemelerini duyuracak şekilde otomatik olarak yapılandırılmayacak.

v2'de şu kod:

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

aşağıdaki gibi v3 eşdeğerine sahiptir:

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

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

çalışma kutusu yönlendirme

Daha önce WorkboxSW nesnesinin workbox.router.* ad alanı üzerinden workbox-routing kullanan geliştiricilerin yeni ad alanına (workbox.routing.*) geçmesi gerekir.
Rotalar artık ilk kaydedilenler sırasına göre değerlendiriliyor. Bu, v2'de kullanılan Route değerlendirmesinin karşıt sırasıdır. Burada son kaydedilen Route'e öncelik verilir.
ExpressRoute sınıfı ve "Ekspres stil" joker karakterleri desteği kaldırılmıştır. Bu, workbox-routing öğesinin boyutunu önemli ölçüde küçültür. workbox.routing.registerRoute() için ilk parametre olarak kullanılan dizeler artık tam eşleşme olarak değerlendirilecek. Joker karakter veya kısmi eşleşmeler RegExp tarafından işlenmelidir. İstek URL'sinin bir kısmı veya tamamıyla eşleşen herhangi bir RegExp kullanılması bir rotayı tetikleyebilir.
Router sınıfının addFetchListener() yardımcı yöntemi kaldırıldı. Geliştiriciler kendi fetch işleyicilerini açık bir şekilde ekleyebilir veya workbox.routing tarafından sağlanan arayüzü kullanarak dolaylı yoldan bir fetch işleyici oluşturabilirler.
registerRoutes() ve unregisterRoutes() yöntemleri kaldırıldı. Bu yöntemlerin, tek bir Route üzerinde çalışan sürümleri değiştirilmedi. Aynı anda birden fazla rotayı kaydetmesi veya kaydını iptal etmesi gereken geliştiriciler, bunun yerine registerRoute() veya unregisterRoute() için bir dizi çağrı yapmalıdır.

v2'de şu 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()
);

aşağıdaki gibi v3 eşdeğerine 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ıyla biliniyor ve npm ürününde yeni adıyla yayınlanmıştır.
Önbellek adı da sağlamadan bir stratejide önbellek geçerlilik sonu kullanımı artık geçerli değildir. v2'de bu mümkündü:

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

Bu durum, varsayılan önbellekteki girişlerin süresinin dolmasına yol açar. Bu beklenmedik bir durumdur. v3'te bir önbellek adı gerekir:

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 yönergesine tepki veren kendi eklentilerini yazmadıkları sürece bu değişiklik, geliştiriciler için görünür bir değişiklik olmamalıdır.
Bir strateji yapılandırırken eklentileri belirtmek için kullanılan söz dizimi değişti. Her bir eklentinin, strateji yapılandırmasının plugins özelliğinde açıkça listelenmesi gerekir.

v2'de şu kod:

const workboxSW = new self.WorkboxSW();

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

aşağıdaki gibi v3 eşdeğerine 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]}),
  ],
});

"Eklenti Kullanma" kılavuzundan daha fazla bilgi edinebilirsiniz.

çalışma kutusu-sw

workbox-sw, temel bir yapılandırma gerektiren ve çalışma zamanında gerekli olan diğer modülleri çekmekten sorumlu olan, hafif bir "yükleyici" arayüzü olacak şekilde yeniden yazılmıştır. Geliştiriciler, WorkboxSW sınıfının yeni bir örneğini oluşturmak yerine, genel ad alanında otomatik olarak sunulan mevcut bir örnekle etkileşime geçer.

v2'de öncekiler:

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. Global ad alanında workbox olarak, kullanıma hazır bir örnek otomatik olarak sunulur:

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çenekler 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 artık v3'te desteklenmemektedir. Herhangi bir getirme işleyici kullanılmadan hizmet çalışanlarını test etmek için benzer işlevlere ihtiyaç duyan geliştiriciler, Chrome'un Geliştirici Araçları'nda bulunan "Ağ için atla" seçeneğini kullanabilir.

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

çalışma-kutusu-web-paketi-eklentisi

Eklenti önemli ölçüde yeniden yazılmıştır ve birçok durumda "sıfır yapılandırma" modunda kullanılabilir. Güncellenen API yüzeyi için belgelere bakın.

API artık GenerateSW ve InjectManifest olmak üzere iki sınıfı kullanıma sunar. Bu, davranışın swSrc varlığına göre değiştiği v2 davranışına kıyasla açık modlar arasında geçiş yapılmasını sağlar.
Varsayılan olarak, web paketi derleme ardışık düzenindeki öğeler önbelleğe alınır ve artık globPatterns öğesinin yapılandırılması gerekmez. globPatterns ürününü kullanmaya devam etmenizin tek nedeni, web paketi derlemenize dahil olmayan öğeleri önbelleğe almanız gerekmesidir. Genel olarak, v3 eklentisine geçiş yaparken glob tabanlı tüm yapılandırmalarınızı kaldırarak başlamanız ve yalnızca özellikle ihtiyacınız varsa yeniden eklemeniz gerekir.

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 sorun açarak bize bildirin.