Panduan ini berfokus pada perubahan yang dapat menyebabkan gangguan yang diperkenalkan di Workbox v4, dengan contoh perubahan yang perlu Anda buat saat mengupgrade dari Workbox v3.
Perubahan yang Dapat Menyebabkan Gangguan
{i>workbox-precaching<i}
Konvensi penamaan untuk entri yang di-precache telah diperbarui. Sekarang, untuk entri yang URL-nya memerlukan informasi revisi (yaitu entri yang berisi kolom revision dalam manifes precache), informasi pembuatan versi tersebut akan disimpan sebagai bagian dari kunci cache, dalam parameter kueri URL __WB_REVISION__ khusus yang ditambahkan ke URL asli. (Sebelumnya, informasi ini disimpan secara terpisah dari kunci cache, menggunakan IndexedDB.)
Developer yang memanfaatkan precaching melalui workbox.precaching.precacheAndRoute(), yang merupakan kasus penggunaan paling umum, tidak perlu melakukan perubahan apa pun pada konfigurasi pekerja layanan mereka. Setelah mengupgrade ke Workbox v4, aset yang di-cache pengguna akan otomatis dimigrasikan ke format kunci cache baru, dan ke depannya, resource yang di-cache akan terus ditayangkan dengan cara yang sama seperti sebelumnya.
Menggunakan Kunci Cache Secara Langsung
Beberapa developer mungkin perlu mengakses entri precache secara langsung, di luar konteks workbox.precaching.precacheAndRoute(). Misalnya, Anda mungkin melakukan precache gambar yang akhirnya Anda gunakan sebagai respons "fallback" saat gambar sebenarnya tidak dapat diambil dari jaringan.
Jika Anda menggunakan aset yang di-cache dengan cara ini, mulai dari Workbox v4, Anda harus melakukan langkah tambahan untuk menerjemahkan URL asli ke kunci cache yang sesuai, yang dapat digunakan untuk membaca entri yang di-cache. Anda dapat melakukannya dengan memanggil workbox.precaching.getCacheKeyForURL(originURL).
Misalnya, jika Anda tahu bahwa 'fallback.png' telah di-precache:
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...
}
});
Membersihkan Data Lama Pra-cache
Perubahan yang dilakukan pada precache di Workbox v4 berarti bahwa precache lama, yang dibuat oleh Workbox versi sebelumnya, tidak kompatibel. Secara default, file tersebut dibiarkan apa adanya, dan jika Anda meningkatkan dari Workbox v3 ke Workbox v4, Anda akan mendapatkan dua salinan dari semua sumber daya yang telah di-cache.
Untuk menghindarinya, Anda dapat menambahkan panggilan ke workbox.precaching.cleanupOutdatedCaches() ke pekerja layanan secara langsung, atau menetapkan opsi cleanupOutdatedCaches: true baru jika menggunakan alat build dalam mode GenerateSW. Karena logika pembersihan cache beroperasi pada konvensi penamaan cache untuk menemukan precache lama, dan karena developer memiliki opsi untuk mengganti konvensi tersebut, kami melakukan kesalahan di sisi keamanan dan tidak mengaktifkannya secara default.
Sebaiknya developer yang mengalami masalah saat menggunakan fitur ini—seperti positif palsu seputar penghapusan—untuk memberi tahu kami.
Kapitalisasi Parameter
Dua parameter opsional yang dapat diteruskan ke workbox.precaching.precacheAndRoute() dan workbox.precaching.addRoute() telah diganti namanya untuk menstandarkan konvensi kapitalisasi secara keseluruhan. ignoreUrlParametersMatching sekarang menjadi ignoreURLParametersMatching, dan cleanUrls sekarang menjadi cleanURLs.
strategi kotak kerja
Ada dua cara yang kurang lebih setara untuk membuat instance pengendali di workbox-strategies. Kami menghentikan metode factory, mendukung pemanggilan konstruktor strategi secara eksplisit.
// 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({...});
Meskipun sintaksis metode factory akan terus berfungsi di v4, penggunaannya akan mencatat peringatan, dan sebaiknya developer melakukan migrasi sebelum menghapus dukungan di rilis v5 mendatang.
sinkronisasi-latar belakang kerja
Class workbox.backgroundSync.Queue telah ditulis ulang untuk menawarkan fleksibilitas dan kontrol yang lebih besar kepada developer atas cara permintaan ditambahkan ke antrean dan di-replay.
Di v3, class Queue memiliki satu cara untuk menambahkan permintaan ke antrean (metode addRequest()), tetapi tidak ada cara untuk mengubah antrean atau menghapus permintaan.
Di v4, metode addRequests() telah dihapus, dan metode seperti array berikut telah ditambahkan:
pushRequest()popRequest()shiftRequest()unshiftRequest()
Di v3, class Queue juga menerima beberapa callback yang memungkinkan Anda mengamati kapan permintaan direplay (requestWillEnqueue, requestWillReplay, queueDidReplay), tetapi sebagian besar developer menemukan bahwa, selain pengamatan, mereka ingin mengontrol cara antrean di-replay, termasuk kemampuan untuk mengubah, mengurutkan ulang, atau bahkan membatalkan setiap permintaan secara dinamis.
Di v4, callback ini telah dihapus dan diganti dengan callback onSync tunggal, yang dipanggil setiap kali upaya replay dilakukan oleh browser. Secara default, callback onSync akan memanggil replayRequests(), tetapi jika Anda memerlukan kontrol lebih besar atas proses replay, Anda dapat menggunakan metode seperti array yang tercantum di atas untuk memutar ulang antrean sesuka Anda.
Berikut adalah contoh logika replay kustom:
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!');
},
});
Demikian pula, class workbox.backgroundSync.Plugin menerima argumen yang sama dengan class Queue (karena membuat instance Queue secara internal), sehingga telah berubah dengan cara yang sama.
masa berlaku workbox
Paket npm telah diganti namanya menjadi workbox-expiration, sesuai dengan konvensi penamaan yang digunakan untuk modul lain. Paket ini secara fungsional setara dengan paket workbox-cache-expiration lama, yang sekarang tidak digunakan lagi.
workbox-broadcast-update
Paket npm telah diganti namanya menjadi workbox-broadcast-update, sesuai dengan konvensi penamaan yang digunakan untuk modul lain. Paket ini secara fungsional setara dengan paket workbox-broadcast-cache-update lama, yang sekarang tidak digunakan lagi.
inti kerja
Di Workbox v3, panjang level log dapat dikontrol melalui metode workbox.core.setLogLevel(), yang akan Anda teruskan salah satu nilai dalam enum workbox.core.LOG_LEVELS. Anda juga dapat membaca level log saat ini melalui workbox.core.logLevel.
Di Workbox v4, semua ini telah dihapus karena semua alat developer modern kini dilengkapi dengan kemampuan pemfilteran log yang kaya (lihat memfilter output konsol untuk Chrome Dev Tools).
workbox-sw
Dua metode yang sebelumnya ditampilkan langsung di namespace workbox (yang sesuai dengan modul workbox-sw) telah dipindahkan ke workbox.core. workbox.skipWaiting() telah menjadi workbox.core.skipWaiting() dan begitu pula, workbox.clientsClaim() telah menjadi workbox.core.clientsClaim().
Konfigurasi Alat Build
Penamaan beberapa opsi yang dapat diteruskan ke workbox-cli, workbox-build, atau workbox-webpack-plugin telah berubah. Setiap kali "Url" digunakan dalam nama opsi, URL tersebut tidak digunakan lagi dan digantikan dengan "URL". Artinya, nama opsi berikut lebih disukai:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
Variasi "Url" dari nama opsi tersebut masih berfungsi di v4, tetapi akan menghasilkan pesan peringatan. Kami mendorong developer untuk melakukan migrasi sebelum rilis v5.
Fungsi Baru
jendela-workbox
Modul workbox-window baru ini menyederhanakan proses pendaftaran pekerja layanan dan mendeteksi update, serta menyediakan sarana komunikasi standar antara kode yang berjalan di pekerja layanan dan kode yang berjalan dalam konteks window aplikasi web Anda.
Meskipun penggunaan workbox-window bersifat opsional, kami berharap developer akan merasakan manfaatnya, dan mempertimbangkan untuk memigrasikan beberapa logika tulisan tangan mereka untuk menggunakannya jika sesuai. Anda dapat mempelajari lebih lanjut cara menggunakan workbox-window di panduan modul.
Contoh Migrasi
Contoh migrasi dunia nyata dari Workbox v3 ke v4 dapat ditemukan dalam Permintaan Pull ini.
Mendapatkan bantuan
Kami berharap sebagian besar migrasi berjalan mudah. Jika Anda mengalami masalah yang tidak dibahas dalam panduan ini, beri tahu kami dengan membuka masalah di GitHub.