Panduan ini berfokus pada perubahan yang dapat menyebabkan gangguan yang diperkenalkan di Workbox v4, dengan contoh perubahan apa yang perlu Anda buat saat melakukan upgrade dari Workbox v3.
Perubahan yang Dapat Menyebabkan Gangguan
workbox-precaching
Konvensi penamaan untuk entri yang di-cache sebelumnya telah diperbarui. Sekarang, untuk entri yang URL-nya memerlukan informasi revisi (yaitu entri yang berisi kolom revision dalam manifes pra-cache), 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 terpisah dari kunci cache, menggunakan IndexedDB.)
Developer yang memanfaatkan pra-cache 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 Anda 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 pra-cache secara langsung, di luar konteks workbox.precaching.precacheAndRoute(). Misalnya, Anda dapat melakukan pra-cache pada gambar yang akhirnya digunakan sebagai respons "penggantian" saat gambar yang sebenarnya tidak dapat diambil dari jaringan.
Jika menggunakan aset yang di-cache dengan cara ini, mulai Workbox v4, Anda harus melakukan langkah tambahan untuk menerjemahkan URL asli menjadi kunci cache yang sesuai yang dapat digunakan untuk membaca entri yang di-cache. Anda melakukannya dengan memanggil workbox.precaching.getCacheKeyForURL(originURL).
Misalnya, jika Anda tahu bahwa 'fallback.png' dipra-cache:
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 yang Di-cache Sebelumnya
Perubahan yang dilakukan pada pra-cache di Workbox v4 berarti bahwa pra-cache lama, yang dibuat oleh Workbox versi sebelumnya, tidak kompatibel. Secara default, resource tersebut dibiarkan apa adanya, dan jika Anda mengupgrade dari Workbox v3 ke Workbox v4, Anda akan memiliki dua salinan dari semua resource yang di-cache sebelumnya.
Untuk menghindari hal ini, 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 pra-cache yang lebih lama, dan karena developer memiliki opsi untuk mengganti konvensi tersebut, kami melakukan kesalahan pada sisi keamanan dan tidak mengaktifkannya secara default.
Sebaiknya developer yang mengalami masalah saat menggunakan fitur ini—seperti hasil positif palsu terkait penghapusan—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 penggunaan huruf besar secara keseluruhan. ignoreUrlParametersMatching kini menjadi ignoreURLParametersMatching, dan cleanUrls kini menjadi cleanURLs.
strategi-workbox
Ada dua cara yang kira-kira setara untuk membuat instance pengendali di workbox-strategies. Kami tidak lagi menggunakan metode factory, dan lebih memilih untuk memanggil 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 ke dalam log, dan sebaiknya developer melakukan migrasi sebelum menghapus dukungan dalam rilis v5 mendatang.
kotak kerja-sinkronisasi-latar belakang
Class workbox.backgroundSync.Queue telah ditulis ulang untuk menawarkan fleksibilitas dan kontrol yang lebih besar kepada developer atas cara permintaan ditambahkan ke antrean dan diputar ulang.
Di v3, class Queue memiliki satu cara untuk menambahkan permintaan ke antrean (metode addRequest()), tetapi tidak memiliki 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 saat permintaan diputar ulang (requestWillEnqueue, requestWillReplay, queueDidReplay), tetapi sebagian besar developer mendapati bahwa, selain pengamatan, mereka menginginkan kontrol atas cara antrean diputar ulang, termasuk kemampuan untuk mengubah, mengurutkan ulang, atau bahkan membatalkan setiap permintaan secara dinamis.
Di v4, callback ini telah dihapus dan diganti dengan satu callback onSync, yang dipanggil setiap kali upaya pemutaran ulang dilakukan oleh browser. Secara default, callback onSync akan memanggil replayRequests(), tetapi jika Anda memerlukan kontrol lebih besar atas proses pemutaran ulang, Anda dapat menggunakan metode seperti array yang tercantum di atas untuk memutar ulang antrean sesuai keinginan.
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 kotak kerja
Paket npm telah diganti namanya menjadi workbox-expiration, yang cocok dengan konvensi penamaan yang digunakan untuk modul lain. Paket ini secara fungsional setara dengan paket workbox-cache-expiration lama, yang kini tidak digunakan lagi.
workbox-broadcast-update
Paket npm telah diganti namanya menjadi workbox-broadcast-update, yang cocok dengan konvensi penamaan yang digunakan untuk modul lain. Paket ini secara fungsional setara dengan paket workbox-broadcast-cache-update lama, yang kini tidak digunakan lagi.
workbox-core
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 diekspos langsung di namespace workbox (yang sesuai dengan modul workbox-sw) telah dipindahkan ke workbox.core. workbox.skipWaiting() telah menjadi workbox.core.skipWaiting() dan demikian 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" tidak digunakan lagi dan digantikan oleh "URL". Artinya, nama opsi berikut lebih disukai:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
Variasi "Url" dari nama opsi tersebut masih berfungsi di v4, tetapi akan menghasilkan pesan peringatan. Sebaiknya developer bermigrasi sebelum rilis v5.
Fungsi Baru
jendela-kerja
Modul workbox-window baru menyederhanakan proses pendaftaran dan mendeteksi update pekerja layanan, 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 harap developer akan merasa terbantu, 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 nyata dari Workbox v3 ke v4 dapat ditemukan dalam Permintaan Pull ini.
Mendapatkan bantuan
Kami mengantisipasi sebagian besar migrasi akan berjalan mudah. Jika Anda mengalami masalah yang tidak tercakup dalam panduan ini, beri tahu kami dengan membuka masalah di GitHub.