Workbox v5'ten v6'ya geçiş

Bu kılavuz, Workbox v6'da kullanıma sunulan değişiklikleri bozmaya odaklanarak, Workbox v5'ten yükseltme yaparken yapmanız gereken değişikliklere ilişkin örnekler içermektedir.

Zarar Veren Değişiklikler

çalışma kutusu-çekirdek

workbox-core içindeki skipWaiting() yöntemi artık bir install işleyici eklemeyecek ve yalnızca self.skipWaiting() çağırmaya eşdeğerdir.

Bundan böyle Workbox v7'de skipWaiting() kaldırılacağından bunun yerine self.skipWaiting() kullanın.

çalışma kutusu önbelleğine alma

  • HTTP yönlendirmesine karşılık gelen URL'lerin kaynaklar arası HTML dokümanları artık workbox-precaching ile gezinme isteğini karşılamak için kullanılamaz. Bu senaryo genelde yaygın değildir.
  • Belirli bir istek için önceden önbelleğe alınmış bir yanıt ararken fbclid URL sorgu parametresi artık workbox-precaching tarafından yoksayılıyor.
  • PrecacheController oluşturucu artık bir dize yerine, parametresi olarak belirli özelliklere sahip bir nesneyi alır. Bu nesne şu özellikleri destekler: cacheName (v5'te oluşturucuya iletilen dizeyle aynı amaca hizmet eder), plugins (v5'teki addPlugins() yönteminin yerine geçer) ve fallbackToNetwork (v5'te createHandler() ve `createHandlerBoundToURL() işlevine geçirilen benzer seçeneğin yerini alır).
  • PrecacheController için install() ve activate() yöntemleri artık tam olarak bir parametre alır. Bu parametre, sırasıyla karşılık gelen InstallEvent veya ActivateEvent değerine ayarlanmalıdır.
  • addRoute() yöntemi, PrecacheController öğesinden kaldırıldı. Bunun yerine, yeni PrecacheRoute sınıfını kullanarak daha sonra kaydedebileceğiniz bir rota oluşturabilirsiniz.
  • precacheAndRoute() yöntemi, PrecacheController öğesinden kaldırıldı. (workbox-precaching modülü tarafından dışa aktarılan statik bir yardımcı yöntem olarak hâlâ mevcuttur.) Bunun yerine PrecacheRoute kullanılabildiği için etiket kaldırıldı.
  • createMatchCalback() yöntemi, PrecacheController öğesinden kaldırıldı. Bunun yerine yeni PrecacheRoute kullanılabilir.
  • createHandler() yöntemi, PrecacheController öğesinden kaldırıldı. Bunun yerine, istekleri işlemek için PrecacheController nesnesinin strategy özelliği kullanılabilir.
  • createHandler() statik dışa aktarma dosyası workbox-precaching modülünden zaten kaldırılmış. Geliştiriciler bunun yerine bir PrecacheController örneği oluşturmalı ve strategy mülkünü kullanmalıdır.
  • precacheAndRoute() tarafından kaydedilen rota, artık workbox-routing Router sınıfını kullanan "gerçek" bir rotadır. registerRoute() ve precacheAndRoute() çağrılarına araya yer verirseniz rotalarınız için değerlendirme sırası farklı olabilir.

çalışma kutusu yönlendirme

setDefaultHandler() yöntemi artık, geçerli olduğu HTTP yöntemine karşılık gelen isteğe bağlı ikinci bir parametreyi alır ve varsayılan olarak 'GET' değerini alır.

  • setDefaultHandler() kullanıyorsanız ve tüm istekleriniz GET ise herhangi bir değişiklik yapmanız gerekmez.
  • GET (POST, PUT vb.) olmayan istekleriniz varsa setDefaultHandler() artık bu isteklerin eşleşmesine neden olmayacak.

Derleme Yapılandırması

workbox-build ve workbox-cli sürümlerinde getManifest ve injectManifest modları için mode seçeneği desteklenmediği için kaldırıldı. Bu durum, InjectManifest eklentisinde mode özelliğini destekleyen workbox-webpack-plugin için geçerli değildir.

Derleme Araçları için Node.js v10 veya Daha Yüksek Sürüm Gerekli

v10'dan önceki Node.js sürümleri artık workbox-webpack-plugin, workbox-build veya workbox-cli için desteklenmemektedir. Node.js'nin v8'den eski bir sürümünü çalıştırıyorsanız çalışma zamanınızı desteklenen bir sürüme güncelleyin.

Yeni İyileştirmeler

çalışma kutusu-stratejileri

Workbox v6, üçüncü taraf geliştiricilerin kendi Workbox stratejilerini tanımlamaları için yeni bir yöntem sunar. Bu sayede üçüncü taraf geliştiriciler, Workbox'ı ihtiyaçlarını tam olarak karşılayacak şekilde genişletme olanağına sahip olur.

Yeni Strateji temel sınıfı

v6'da, tüm Çalışma Kutusu strateji sınıfları yeni Strategy temel sınıfının kapsamını genişletmelidir. Tüm yerleşik stratejiler bunu destekleyecek şekilde yeniden yazılmıştır.

Strategy temel sınıfı iki temel şeyden sorumludur:

  • Tüm strateji işleyiciler (ör. başlatma, yanıt verme ve sona erme zamanı) için ortak olarak kullanılan eklenti yaşam döngüsü geri çağırmalarını çağırma.
  • Bir stratejinin işlediği her isteğin durumunu yönetebilen bir "işleyici" örneği oluşturma.

Yeni "işleyici" sınıfı

Daha önce, fetchWrapper ve cacheWrapper adlı dahili modüllerimiz vardı. Bu modüller, adlarından da anlaşılacağı gibi çeşitli getirme ve önbellek API'lerini kancalarla yaşam döngülerine dahil ediyordu. Bu mekanizma şu anda eklentilerin çalışmasına izin verir, ancak geliştiriciler tarafından görülmez.

Yeni "işleyici" sınıfı (StrategyHandler), özel stratejilerin fetch() veya cacheMatch() yöntemini çağırabilmesi ve strateji örneğine eklenen eklentilerin otomatik olarak çağrılabilmesi için bu yöntemleri gösterir.

Bu sınıf, geliştiricilerin stratejilerine özgü olabilecek kendi özel, yaşam döngüsü geri çağırmalarını eklemelerine de olanak tanır ve mevcut eklenti arayüzüyle "sorunsuz çalışır".

Yeni eklentinin yaşam döngüsü durumu

Workbox v5'te eklentiler durum bilgisizdir. Diğer bir deyişle, bir /index.html isteği hem requestWillFetch hem de cachedResponseWillBeUsed geri çağırmalarını tetiklerse bu iki geri arama işlevi birbiriyle hiçbir şekilde iletişim kuramaz, hatta aynı istek tarafından tetiklendikleri bilebilir.

v6'da, tüm eklenti geri çağırmaları da yeni bir state nesnesi iletilecektir. Bu durum nesnesi, söz konusu eklenti nesnesine ve bu strateji çağrısına (yani handle() çağrısına) özel olacaktır. Bu, geliştiricilerin, bir geri çağırmanın aynı eklentideki başka bir geri çağırma işlevine bağlı olarak koşullu olarak bir şey yapabileceği eklentiler yazmasına olanak tanır (ör. requestWillFetch ile fetchDidSucceed veya fetchDidFail çalıştırma arasındaki zaman deltasını hesaplama).

Yeni eklenti yaşam döngüsü geri çağırmaları

Geliştiricilerin eklentinin yaşam döngüsü durumundan tam olarak yararlanmasını sağlamak için yeni eklenti yaşam döngüsü geri çağırmaları eklendi:

  • handlerWillStart: Herhangi bir işleyici mantığı çalışmaya başlamadan önce çağrılır. Bu geri çağırma, ilk işleyici durumunu ayarlamak (ör. başlangıç zamanını kaydetmek) için kullanılabilir.
  • handlerWillRespond: Stratejiler handle() yöntemi yanıt döndürmeden önce çağrıldı. Bu geri çağırma, yanıtı bir rota işleyiciye veya başka bir özel mantığa döndürmeden önce söz konusu yanıtı değiştirmek için kullanılabilir.
  • handlerDidRespond: Stratejinin handle() yöntemi yanıt döndürdükten sonra çağrılır. Bu geri çağırma işlevi, nihai yanıt ayrıntılarını (ör. diğer eklentiler tarafından yapılan değişikliklerden sonra) kaydetmek için kullanılabilir.
  • handlerDidComplete: Bu stratejinin çağrılmasından sonra etkinliğe eklenen tüm ömür boyu uzatılan taahhütler sağlandıktan sonra çağrıldı. Bu geri çağırma, hesaplama işleminin yapılması için işleyicinin tamamlanması gereken tüm verileri (ör. önbellek isabeti durumu, önbellek gecikmesi, ağ gecikmesi) raporlamak için kullanılabilir.
  • handlerDidError: İşleyici herhangi bir kaynaktan geçerli bir yanıt sağlayamadıysa çağrılır. Bu geri çağırma, ağ hatasına alternatif olarak "yedek" içerik sağlamak için kullanılabilir.

Kendi özel stratejilerini uygulayan geliştiricilerin bu geri çağırmaları kendi kendilerine başlatma konusunda endişe duymaları gerekmez. Tüm bu işlemler, yeni bir Strategy temel sınıfı tarafından gerçekleştirilir.

İşleyiciler için daha doğru TypeScript türleri

Çeşitli geri çağırma yöntemleri için TypeScript tanımları normalleştirildi. Bu durum, TypeScript kullanan ve işleyicileri uygulamak veya çağırmak için kendi kodlarını yazan geliştiriciler için daha iyi bir deneyim sağlayacaktır.

çalışma kutusu-penceresi

Yeni mesajJumpPendinging() yöntemi

"Bekleyen" hizmet çalışanının etkinleştirilmesini bildirme sürecini basitleştirmek için workbox-window modülüne yeni bir yöntem (messageSkipWaiting()) eklendi. Bu, bazı iyileştirmeler sağlar:

  • Workbox tarafından oluşturulan bir hizmet çalışanının skipWaiting() tetiklemek için kontrol ettiği fiili standart mesaj gövdesiyle ({type: 'SKIP_WAITING'}) postMessage() çağırır.
  • workbox-window ile aynı hizmet çalışanı olmasa bile bu mesajı yayınlamak için doğru "bekliyor" hizmet çalışanını seçer.

isExternal mülkü adına "harici" etkinliklerin kaldırılması

workbox-window kapsamındaki tüm "external" etkinlikleri, isExternal mülkü true olarak ayarlanmış "normal" etkinliklerin yerine kaldırıldı. Böylece, bu ayrımı önemseyen geliştiriciler de bunu algılayabilir ve bilmesi gerekmeyen geliştiriciler mülkü yoksayabilir.

Temizleyici "Kullanıcılara sayfayı yeniden yükleme imkanı ver" tarifi

Yukarıdaki değişikliklerin her ikisi de sayesinde, "Kullanıcılar için sayfayı yeniden yükleme seçeneği sun" tarifi basitleştirilebilir:

MULTI_LINE_CODE_PLACEHOLDER_0

çalışma kutusu yönlendirme

workbox-routing içinde kullanılan matchCallback işlevine yeni bir boole parametresi (sameOrigin) iletilir. İstek aynı kaynak URL'sine yönelikse true olarak, aksi takdirde yanlış olarak ayarlanır.

Bu yöntem, yaygın kullanılan bazı ortak metinleri basitleştirir:

MULTI_LINE_CODE_PLACEHOLDER_1

Çalışma kutusu geçerlilik süresindeki matchOptions

Artık workbox-expiration içinde matchOptions ayarlayabilirsiniz. Bu ayar daha sonra temel cache.delete() çağrısına CacheQueryOptions olarak aktarılır. (Çoğu geliştiricinin bunu yapması gerekmez.)

çalışma kutusu önbelleğine alma

Çalışma kutusu stratejilerini kullanır

workbox-precaching, workbox-strategies sitesini temel almak üzere yeniden yazıldı. Bu durum, herhangi bir zarara yol açmamalı ve iki modülün ağa ve önbelleğe erişme şeklinde uzun vadeli tutarlılık sağlayacaktır.

Önbelleğe alma özelliği artık girişleri toplu olarak değil tek tek işler.

workbox-precaching güncellendi. Bu güncelleme sayesinde, önbelleğin önbelleğinde tek seferde yalnızca bir giriş istenip önbelleğe alınmaya çalışıldı. Her giriş için aynı anda istekte bulunma ve önbelleğe alma işlemi gerçekleştirilmeye çalışılıyor (kısıtlamanın nasıl yapılacağını anlamak için sayfayı tarayıcıya bırakıyoruz).

Bu, önbelleğe alma sırasında net::ERR_INSUFFICIENT_RESOURCES hatalarının görülme olasılığını azaltırken web uygulaması tarafından önbelleğe alma ve aynı anda yapılan istekler arasındaki bant genişliği anlaşmazlığını da azaltacaktır.

PrecacheFallbackEklentiler, çevrimdışı yedekleri kolaylaştırır

workbox-precaching artık v6'ya eklenen yeni handlerDidError yaşam döngüsü yöntemini uygulayan bir PrecacheFallbackPlugin içeriyor.

Bu, önceden önbelleğe alınmış bir URL'nin, başka şekilde kullanılabilir bir yanıt olmadığında belirli bir strateji için"yedek" olarak belirtmeyi kolaylaştırır. Eklenti, gerekli tüm düzeltme parametreleri de dahil olmak üzere önceden önbelleğe alınan URL için doğru önbellek anahtarının düzgün şekilde oluşturulmasını sağlar.

Aşağıda, NetworkOnly stratejisi gezinme isteği (diğer bir deyişle özel bir çevrimdışı HTML sayfası) için yanıt oluşturamadığında önceden önbelleğe alınmış /offline.html ile yanıt vermek için bu biçimin nasıl kullanılacağına dair bir örneği aşağıda bulabilirsiniz:

MULTI_LINE_CODE_PLACEHOLDER_2

Çalışma zamanı önbelleğe almada precacheFallback

Servis çalışanınızı elle yazmak yerine sizin yerinize hizmet çalışanı oluşturmak için generateSW kullanıyorsanız runtimeCaching içerisindeki yeni precacheFallback yapılandırma seçeneğini kullanarak da aynı işlemi elde edebilirsiniz:

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

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 lütfen GitHub'da bir sorun açarak durumu bize bildirin.