Bu kılavuz, Workbox v4'te yapılan değişiklikleri bozma konusuna odaklanarak Workbox v3'ten yükseltme yaparken yapmanız gereken değişikliklere ilişkin örnekler içerir.
Zarar Veren Değişiklikler
çalışma kutusu önbelleğine alma
Önbelleğe alınmış girişler için adlandırma kuralı güncellendi. Artık URL'lerinde düzeltme bilgileri gereken girişler (ör. önbellek manifest'inde revision alanı içeren girişler) söz konusu sürüm oluşturma bilgileri, önbellek anahtarının bir parçası olarak, orijinal URL'nin sonuna eklenen özel bir __WB_REVISION__ URL sorgu parametresinde depolanacak. (Önceden, bu bilgiler IndexedDB kullanılarak önbellek anahtarlarından ayrı olarak depolanıyordu.)
En yaygın kullanım alanı olan workbox.precaching.precacheAndRoute() aracılığıyla önbelleğe alma özelliğinden yararlanan geliştiricilerin, hizmet çalışanı yapılandırmalarında herhangi bir değişiklik yapmaları gerekmez. Workbox v4'e geçtikten sonra kullanıcılarınızın önbelleğe alınan öğeleri otomatik olarak yeni önbellek anahtarı biçimine taşınacak ve önceden önbelleğe alınan kaynaklar, önceden olduğu gibi sunulmaya devam edecektir.
Önbellek Anahtarlarını Doğrudan Kullanma
Bazı geliştiricilerin, ön önbellek girişlerine workbox.precaching.precacheAndRoute() bağlamı dışında doğrudan erişmesi gerekebilir. Örneğin, ağdan gerçek bir resim getirilemediğinde "yedek" yanıt olarak kullanacağınız bir resmi önbelleğe alabilirsiniz.
Önceden önbelleğe alınmış öğeleri bu şekilde kullanırsanız, Workbox v4'ten başlayarak orijinal bir URL'yi önbelleğe alınmış girişi okumak için kullanılabilecek ilgili önbellek anahtarına çevirmek üzere ek bir adım daha gerçekleştirmeniz gerekir. Bunu workbox.precaching.getCacheKeyForURL(originURL) numaralı telefonu arayarak yapabilirsiniz.
Örneğin, 'fallback.png' dosyasının önceden önbelleğe alındığını biliyorsanız:
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...
}
});
Önceden Önbelleğe Alınmış Eski Verileri Temizleme
Workbox v4'te önbelleğe alma işleminde yapılan değişiklikler, Workbox'ın önceki sürümleri tarafından oluşturulan eski önbelleğin uyumlu olmadığı anlamına gelir. Varsayılan olarak olduğu gibi kalırlar. Workbox v3'ten Workbox v4'e yükseltme yaparsanız önceden önbelleğe alınmış tüm kaynaklarınızın iki kopyasına sahip olursunuz.
Bunu önlemek için doğrudan Service Worker'lara workbox.precaching.cleanupOutdatedCaches() çağrısı ekleyebilir veya GenerateSW modunda bir derleme aracı kullanıyorsanız yeni cleanupOutdatedCaches: true seçeneğini ayarlayabilirsiniz. Önbellek temizleme mantığı, eski ön önbellekleri bulmak için önbellek adlandırma kurallarından yararlandığından ve geliştiricilerin bu kuralları geçersiz kılma seçeneğine sahip olduğu için güvenlik açısından hata yaptık ve bunu varsayılan olarak etkinleştirmedik.
Bu yöntemi kullanırken herhangi bir sorunla (ör. silme işlemiyle ilgili yanlış pozitif sonuçlar) karşılaşan geliştiricilerin bize bildirmelerini öneririz.
Parametrelerde Büyük Harf Kullanımı
Genel büyük harf kullanımı kuralımızı standartlaştırmak için workbox.precaching.precacheAndRoute() ve workbox.precaching.addRoute() özelliklerine geçirilebilen iki isteğe bağlı parametre yeniden adlandırıldı. ignoreUrlParametersMatching artık ignoreURLParametersMatching, cleanUrls ise cleanURLs oldu.
çalışma kutusu-stratejileri
workbox-strategies bölgesinde işleyici örneği oluşturmanın kabaca iki farklı yolu vardır. Stratejinin kurucusunu açıkça belirtmek için fabrika yöntemini kullanımdan kaldırıyoruz.
// 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({...});
Fabrika yöntemi söz dizimi v4'te çalışmaya devam etse de, bunu kullandığınızda bir uyarı kaydedilir. Geliştiricilerin, gelecekteki v5 sürümünde desteği kaldırmadan önce geçiş yapmalarını öneririz.
çalışma kutusu-arka plan-senkronizasyon
workbox.backgroundSync.Queue sınıfı, geliştiricilere isteklerin sıraya eklenmesi ve yeniden oynatılması konusunda daha fazla esneklik ve kontrol sunmak için yeniden yazılmıştır.
v3'te, Queue sınıfı istekleri sıraya eklemek için tek bir yönteme sahipti (addRequest() yöntemi) ancak sırayı değiştirmek veya istekleri kaldırmak için herhangi bir yol sağlamıyordu.
v4'te addRequests() yöntemi kaldırıldı ve aşağıdaki dizi benzeri yöntemler eklendi:
pushRequest()popRequest()shiftRequest()unshiftRequest()
v3'te, Queue sınıfı isteklerin ne zaman tekrar oynatıldığını gözlemlemenizi sağlayan birkaç geri çağırmayı da kabul etti (requestWillEnqueue, requestWillReplay, queueDidReplay). Ancak çoğu geliştirici gözlemin yanı sıra, istekleri dinamik olarak değiştirme, yeniden sıralama ve hatta tek tek iptal etme de dahil olmak üzere sıranın nasıl tekrar oynatılacağı üzerinde kontrol sahibi olmak istediklerini belirledi.
v4'te bu geri çağırma işlevleri, tarayıcı tarafından her tekrar oynatma denemesi yapıldığında çağrılan tek bir onSync geri çağırma için kaldırılmıştır. onSync geri çağırma işlevi, varsayılan olarak replayRequests() yöntemini çağırır. Ancak tekrar oynatma işlemi üzerinde daha fazla kontrole ihtiyacınız varsa sırayı istediğiniz gibi yeniden oynatmak için yukarıda listelenen dizi benzeri yöntemleri kullanabilirsiniz.
Özel tekrar oynatma mantığının bir örneği:
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!');
},
});
Benzer şekilde, workbox.backgroundSync.Plugin sınıfı Queue sınıfıyla aynı bağımsız değişkenleri kabul eder (dahili olarak bir Queue örneği oluşturduğundan), aynı şekilde değişmiştir.
çalışma kutusunun geçerlilik süresi dolmak üzere
npm paketinin adı, diğer modüller için kullanılan adlandırma kuralına uyacak şekilde workbox-expiration olarak değiştirildi. Bu paket, işlevsel olarak kullanımdan kaldırılmış olan eski workbox-cache-expiration paketine eşdeğerdir.
workbox-broadcast-güncellemesi
npm paketinin adı, diğer modüller için kullanılan adlandırma kuralına uyacak şekilde workbox-broadcast-update olarak değiştirildi. Bu paket, işlevsel olarak kullanımdan kaldırılmış olan eski workbox-broadcast-cache-update paketine eşdeğerdir.
çalışma kutusu-çekirdek
Workbox v3'te günlük düzeylerinin ayrıntı düzeyi, workbox.core.LOG_LEVELS sıralamasındaki değerlerden birini ilettiğiniz workbox.core.setLogLevel() yöntemiyle kontrol edilebiliyordu. Mevcut günlük düzeyini workbox.core.logLevel aracılığıyla da okuyabilirsiniz.
Tüm modern geliştirici araçları artık zengin günlük filtreleme özelliğiyle birlikte geldiğinden (Chrome Geliştirici Araçları için konsol çıkışını filtreleme sayfasına göz atın) Workbox v4'te bunların hepsi kaldırıldı.
çalışma kutusu-sw
Daha önce doğrudan workbox ad alanında (workbox-sw modülüne karşılık gelir) gösterilen iki yöntem, bunun yerine workbox.core etiketine taşındı. workbox.skipWaiting() workbox.core.skipWaiting() oldu ve benzer şekilde workbox.clientsClaim() de workbox.core.clientsClaim() oldu.
Derleme Aracı Yapılandırması
Workbox-cli, Workbox-build veya workbox-webpack-plugin'e geçirilebilecek bazı seçeneklerin adları değişti. Bir seçenek adında "Url" kullanıldığında, kullanımdan kaldırılmış ve yerini "URL" almıştır. Bu, aşağıdaki seçenek adlarının tercih edildiği anlamına gelir:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
Bu seçenek adlarının "Url" varyasyonu v4'te çalışmaya devam eder ancak bir uyarı mesajı gösterilir. Geliştiricilerin, v5 sürümünden önce geçiş yapmalarını öneririz.
Yeni İşlev
çalışma kutusu-penceresi
Yeni workbox-window modülü, Service Worker kaydı ve güncellemeleri tespit etme sürecini basitleştirir ve Service Worker'da çalışan kod ile web uygulamanızın window bağlamında çalışan kod arasında standart bir iletişim yöntemi sağlar.
workbox-window kullanımı isteğe bağlı olsa da geliştiricilerin bu programı yararlı bulacağınızı umuyoruz ve el yazısı mantığının bir bölümünü uygun olduğunda kullanmak için taşımayı düşünebilirsiniz. Modül kılavuzunda workbox-window ürününü kullanma hakkında daha fazla bilgi edinebilirsiniz.
Örnek Taşıma
Workbox v3'ten v4'e gerçek dünyadan bir taşıma örneği bu Pull İsteği bölümünde bulunabilir.
Yardım alma
Çoğu taşıma işleminin doğrudan olacağını tahmin ediyoruz. Bu kılavuzda ele alınmayan sorunlarla karşılaşırsanız lütfen GitHub'da bir sorun sayfası açarak bize bildirin.