çalışma kutusu önbelleğine alma

Service Worker'ların bir özelliği, hizmet çalışanı yükleme sırasında bir grup dosyayı önbelleğe kaydedebilmesidir. İçeriği hizmet çalışanının kullanımından önce önbelleğe aldığınız için buna genellikle "önbelleğe alma" adı verilir.

Bunu yapmanın ana nedeni, geliştiricilere önbellek üzerinde kontrol olanağı sağlamasıdır. Yani bir dosyanın ne zaman ve ne kadar süre önbellekte tutulacağını belirleyebilir, ayrıca dosyayı ağa gitmeden tarayıcıya sunabilirler. Diğer bir deyişle, dosya çevrimdışı çalışan web uygulamaları oluşturmak için kullanılabilir.

Workbox, API'yi basitleştirerek ve öğelerin verimli bir şekilde indirilmesini sağlayarak önceden önbelleğe alma işleminin zahmetli kısmını üstlenir.

Çalışma kutusu ön belleğe almanın işleyiş şekli

Bir web uygulaması ilk kez yüklendiğinde workbox-precaching indirmek istediğiniz tüm öğeleri inceler, yinelenen öğeleri kaldırır ve öğeleri indirip depolamak için ilgili Service Worker etkinliklerini bağlar. Zaten sürüm oluşturma bilgileri (içerik karması gibi) bulunan URL'ler, başka herhangi bir değişiklik yapılmadan önbellek anahtarı olarak kullanılır. Sürüm oluşturma bilgilerini içermeyen URL'lerin önbellek anahtarlarına eklenen fazladan bir URL sorgu parametresi vardır. Bu parametre, Workbox'ın derleme sırasında oluşturduğu içeriklerinin karmasını temsil eder.

workbox-precaching, bunların tümünü hizmet çalışanının install etkinliği sırasında gerçekleştirir.

Bir kullanıcı daha sonra web uygulamanızı yeniden ziyaret ettiğinde ve önceden önbelleğe alınmış farklı öğelere sahip yeni bir hizmet çalışanınız olduğunda workbox-precaching, yeni listeyi inceleyerek hangi öğelerin tamamen yeni olduğunu, hangilerinin revizyonlarına bağlı olarak mevcut öğelerden hangilerinin güncellenmesi gerektiğini belirler. Yeni öğeler veya güncellenen düzeltmeler, yeni hizmet çalışanının install etkinliği sırasında önbelleğe eklenir.

Bu yeni hizmet çalışanı, activate etkinliği tetiklenene kadar isteklere yanıt vermek için kullanılmaz. workbox-precaching, activate etkinliğinde mevcut URL'lerin listesinde artık bulunmayan önbelleğe alınmış öğeler olup olmadığını kontrol eder ve bunları önbellekten kaldırır.

workbox-precaching, hizmet çalışanınız her yüklendiğinde ve etkinleştirildiğinde bu adımları uygulayarak kullanıcının en yeni öğelere sahip olmasını sağlar ve yalnızca değiştirilen dosyaları indirir.

Önceden Önbelleğe Alınmış Yanıtları Sunma

precacheAndRoute() veya addRoute() çağrıları, önceden önbelleğe alınmış URL istekleriyle eşleşen bir rota oluşturur.

Bu rotada kullanılan yanıt stratejisi önbelleğe öncelik yöntemidir: Önbelleğe alınan yanıt yoksa (beklenmeyen bir hata nedeniyle) önbelleğe alınmış yanıt kullanılır. Böyle bir durumda bunun yerine ağ yanıtı kullanılır.

precacheAndRoute() veya addRoute() çağrılarını hangi sırayla yaptığınız önemlidir. Normalde registerRoute() ile ek rotalar kaydetmeden önce bu parametreyi Service Worker dosyanızda erken bir aşamada çağırmanız gerekir. Önce registerRoute() yöntemini çağırdıysanız ve bu rota gelen bir istekle eşleştiyse yanıt vermek için workbox-precaching tarafından kullanılan önbellek öncelikli strateji yerine söz konusu ek rotada tanımladığınız strateji kullanılır.

Ön Önbellek Listesinin Açıklaması

workbox-precaching, url ve revision özelliklerine sahip bir nesne dizisi bekler. Bu diziye bazen ön önbellek manifesti denir:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([
  {url: '/index.html', revision: '383676'},
  {url: '/styles/app.0c9a31.css', revision: null},
  {url: '/scripts/app.0d5770.js', revision: null},
  // ... other entries ...
]);

Bu liste, her biri kendi "düzeltme" bilgilerine sahip bir dizi URL'yi referans alır.

Yukarıdaki örnekte yer alan ikinci ve üçüncü nesne için revision özelliği null olarak ayarlanmıştır. Bunun nedeni düzeltme bilgilerinin URL'nin kendisinde olmasıdır. Bu, genellikle statik öğeler için en iyi uygulamadır.

İlk nesne (/index.html), dosya içeriğinin otomatik oluşturulan bir karması olan düzeltme özelliğini açıkça ayarlar. JavaScript ve CSS kaynaklarından farklı olarak HTML dosyalarının URL'lerinde düzeltme bilgileri genellikle yer alamaz. Aksi takdirde, web'de bu dosyaların bağlantıları, sayfanın içeriği her değiştiğinde bozulabilir.

Workbox, precacheAndRoute() ürününe bir düzeltme özelliği geçirerek dosyanın ne zaman değiştiğini anlayabilir ve dosyayı buna göre güncelleyebilir.

Workbox, bu listeyi oluşturmanıza yardımcı olacak araçlarla birlikte gelir:

• workbox-build: Bu, bir gulp görevinde veya npm çalıştırma komut dosyası olarak kullanılabilen bir düğüm paketidir.
• workbox-webpack-plugin: web paketi kullanıcıları bu eklentiyi kullanabilir.
• workbox-cli: CLI'mız, öğe listesini oluşturmak ve bunları hizmet çalışanınıza eklemek için de kullanılabilir.

Önbelleğe Alınmış Dosyalar için Gelen İstekler

workbox-precaching ürününün ilk aşamada yapacağı şeylerden biri, gelen ağ isteklerini önceden önbelleğe alınmış dosyaları eşleştirmeyi deneyecek şekilde değiştirmektir. Bu, web'deki yaygın uygulamalara uygundur.

Örneğin, / ile ilgili istek genellikle /index.html adresindeki dosya tarafından karşılanabilir.

Aşağıda, workbox-precaching tarafından varsayılan olarak gerçekleştirilen işlemelerin listesi ve bu davranışı nasıl değiştirebileceğiniz açıklanmıştır.

URL Parametrelerini Yok Say

Arama parametreleri içeren istekler, belirli değerleri veya tüm değerleri kaldırmak için değiştirilebilir.

Varsayılan olarak, utm_ ile başlayan veya fbclid ile tam olarak eşleşen arama parametreleri kaldırılır. Yani /about.html?utm_campaign=abcd için yapılan istek, /about.html için önbelleğe alınmış bir girişle karşılanır.

ignoreURLParametersMatching kullanarak farklı arama parametreleri grubunu yoksayabilirsiniz:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    // Ignore all URL parameters.
    ignoreURLParametersMatching: [/.*/],
  }
);

Dizin Dizini

Varsayılan olarak / ile biten istekler, sonuna index.html eklenmiş girişlerle eşleştirilir. Bu, / için gelen bir isteğin, önbelleğe alınmış /index.html girişiyle otomatik olarak işlenebileceği anlamına gelir.

directoryIndex ayarını yaparak bu ayarı değiştirebilir veya tamamen devre dışı bırakabilirsiniz:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    directoryIndex: null,
  }
);

URL'leri temizle

Bir istek ön önbellekle eşleşmezse "temiz" URL'leri (diğer adıyla "güzel" URL'ler) desteklemek için sonuna .html ekleriz. Bu, /about gibi bir isteğin /about.html için önbelleğe alınmış giriş tarafından işleneceği anlamına gelir.

cleanUrls ayarını yaparak bu davranışı devre dışı bırakabilirsiniz:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([{url: '/about.html', revision: 'b79cd4'}], {
  cleanUrls: false,
});

Özel Manipülasyonlar

Gelen isteklerden önceden önbelleğe alınmış öğelere özel eşleşmeler tanımlamak isterseniz urlManipulation seçeneğini kullanabilirsiniz. Bu, olası eşleşmelerden oluşan bir dizi döndüren bir geri çağırma olmalıdır.

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    urlManipulation: ({url}) => {
      // Your logic goes here...
      return [alteredUrlOption1, alteredUrlOption2];
    },
  }
);

Gelişmiş Kullanım

PrecacheController'ı Doğrudan Kullanma

workbox-precaching, varsayılan olarak install ve activate işleyicilerini sizin için ayarlar. Service Worker'lara aşina olan geliştiriciler, daha fazla denetime ihtiyaç duyduğunda bu pek hoş olmayabilir.

Öğeleri önceden önbelleğe almak, bu öğelerin ne zaman yükleneceğini ve temizlemenin ne zaman gerçekleşeceğini belirlemek için varsayılan dışa aktarmayı kullanmak yerine doğrudan PrecacheController kullanabilirsiniz.

import {PrecacheController} from 'workbox-precaching';

const precacheController = new PrecacheController();
precacheController.addToCacheList([
  {url: '/styles/example-1.abcd.css', revision: null},
  {url: '/styles/example-2.1234.css', revision: null},
  {url: '/scripts/example-1.abcd.js', revision: null},
  {url: '/scripts/example-2.1234.js', revision: null},
]);

precacheController.addToCacheList([{
  url: '/index.html',
  revision: 'abcd',
}, {
  url: '/about.html',
  revision: '1234',
}]);

self.addEventListener('install', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.install(event));
});

self.addEventListener('activate', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.activate(event));
});

self.addEventListener('fetch', (event) => {
  const cacheKey = precacheController.getCacheKeyForURL(event.request.url);
  event.respondWith(caches.match(cacheKey).then(...));
});

Önceden Önbelleğe Alınmış Öğeleri Doğrudan Okuma

Önbelleğe alınmış bir öğeyi workbox-precaching tarafından otomatik olarak gerçekleştirilebilecek yönlendirme bağlamının dışında doğrudan okumanız gerekebilir. Örneğin, daha sonra alınması ve tam bir yanıt oluştururken kullanılması gereken kısmi HTML şablonlarını önbelleğe almak isteyebilirsiniz.

Genel olarak, önceden önbelleğe alınmış Response nesnelerini elde etmek için Cache Storage API'yi kullanabilirsiniz, ancak önemli bir nokta vardır: cache.match() çağrılırken kullanılması gereken URL önbellek anahtarı, workbox-precaching tarafından otomatik olarak oluşturulup sürdürülen bir sürüm oluşturma parametresi içerebilir.

Doğru önbellek anahtarını almak için getCacheKeyForURL() yöntemini çağırabilir, orijinal URL'yi iletebilir ve daha sonra, sonucu kullanarak uygun önbellekte cache.match() işlemi gerçekleştirebilirsiniz.

import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cache = await caches.open(cacheNames.precache);
const response = await cache.match(getCacheKeyForURL('/precached-file.html'));

Alternatif olarak, yalnızca önceden önbelleğe alınmış Response nesnesine ihtiyacınız varsa matchPrecache() yöntemini çağırabilirsiniz. Bu işlem otomatik olarak doğru önbellek anahtarını kullanır ve doğru önbellekte arama yapar:

import {matchPrecache} from 'workbox-precaching';

const response = await matchPrecache('/precached-file.html');

Eski Ön Önbelleği Temizleme

Workbox'ın çoğu sürümü, önceden önbelleğe alınmış verileri depolamak için aynı biçimi kullanır ve Workbox'ın eski sürümleri tarafından oluşturulan ön önbellekler, normalde yeni sürümler tarafından olduğu gibi kullanılabilir. Bununla birlikte, nadiren de olsa, depolama alanının önceden önbelleğe alınmasında, mevcut kullanıcıların her şeyi yeniden indirmesini gerektiren ve daha önce önbelleğe alınmış verileri geçersiz kılacak zarar veren bir değişiklik olur. (Workbox v3 ve v4 sürümleri arasında böyle bir değişiklik yaşandı.)

Bu eski veriler normal işlemleri etkilemez ancak genel depolama alanı kotanıza da katkıda bulunur ve verilerin açıkça silinmesi kullanıcılarınıza daha dostça olabilir. Bunu, cleanupOutdatedCaches() aracını hizmet çalışanınıza ekleyerek veya hizmet çalışanınızı oluşturmak için Workbox'ın derleme araçlarından birini kullanıyorsanız cleanupOutdatedCaches: true özelliğini ayarlayarak yapabilirsiniz.

Alt Kaynak Bütünlüğünü Kullanma

Bazı geliştiriciler, önceden önbelleğe alınmış URL'leri ağdan alırken alt kaynak bütünlüğünün uygulanmasıyla sunulan ek garantileri görmek isteyebilir.

İsteğe bağlı olarak integrity adlı ek bir özellik, ön önbellek manifestindeki herhangi bir girişe eklenebilir. Bu değer sağlanırsa önbelleği doldurmak için kullanılan Request oluşturulurken integrity değeri olarak kullanılır. Bir uyuşmazlık varsa önbelleğe alma işlemi başarısız olur.

Hangi ön önbellek manifest girişlerinin integrity özelliklerine sahip olması gerektiğini belirleme ve kullanılacak uygun değerleri belirlemek, Workbox'ın derleme araçlarının kapsamı dışındadır. Bunun yerine, bu işlevi etkinleştirmek isteyen geliştiricilerin, uygun bilgileri eklemek için Workbox'ın oluşturduğu ön önbellek manifestini değiştirmesi gerekir. Workbox'ın oluşturma araçları yapılandırmasındaki manifestTransform seçeneği şu konularda yardımcı olabilir:

const ssri = require('ssri');

const integrityManifestTransform = (originalManifest, compilation) => {
  const warnings = [];
  const manifest = originalManifest.map(entry => {
    // If some criteria match:
    if (entry.url.startsWith('...')) {
      // This has to be a synchronous function call, for example:
      // compilation will be set when using workbox-webpack-plugin.
      // When using workbox-build directly, you can read the file's
      // contents from disk using, e.g., the fs module.
      const asset = compilation.getAsset(entry.url);
      entry.integrity = ssri.fromData(asset.source.source()).toString();

      // Push a message to warnings if needed.
    }
    return entry;
  });

  return {warnings, manifest};
};

// Then add manifestTransform: [integrityManifestTransform]
// to your Workbox build configuration.

workbox-precaching.urlManipulation(
  { url }: object,
)

workbox-precaching.addPlugins(
  plugins: WorkboxPlugin[],
)

workbox-precaching.addRoute(
  options?: PrecacheRouteOptions,
)

workbox-precaching.cleanupOutdatedCaches()

workbox-precaching.createHandlerBoundToURL(
  url: string,
)

workbox-precaching.getCacheKeyForURL(
  url: string,
)

workbox-precaching.matchPrecache(
  request: string | Request,
)

workbox-precaching.precache(
  entries: (string | PrecacheEntry)[],
)

workbox-precaching.precacheAndRoute(
  entries: (string | PrecacheEntry)[],
  options?: PrecacheRouteOptions,
)