Hướng dẫn này tập trung vào các thay đổi có thể gây lỗi được giới thiệu trong Workbox phiên bản 4, kèm theo ví dụ về những thay đổi bạn cần thực hiện khi nâng cấp từ Workbox phiên bản 3.
Thay đổi có thể gây lỗi
workbox-precaching
Quy ước đặt tên cho các mục nhập được lưu trước trong bộ nhớ đệm đã được cập nhật. Giờ đây, đối với các mục nhập có URL cần thông tin sửa đổi (ví dụ: những mục nhập chứa trường revision trong tệp kê khai bộ nhớ đệm trước), thông tin phiên bản đó sẽ được lưu trữ như một phần của khoá bộ nhớ đệm, trong một tham số truy vấn URL __WB_REVISION__ đặc biệt được thêm vào URL ban đầu. (Trước đây, thông tin này được lưu trữ riêng biệt với các khoá bộ nhớ đệm bằng IndexedDB.)
Các nhà phát triển tận dụng tính năng lưu vào bộ nhớ đệm qua workbox.precaching.precacheAndRoute() (đây là trường hợp sử dụng phổ biến nhất) không cần thay đổi gì đối với cấu hình trình chạy dịch vụ của mình; khi nâng cấp lên Workbox phiên bản 4, các thành phần đã lưu vào bộ nhớ đệm của người dùng sẽ tự động di chuyển sang định dạng khoá bộ nhớ đệm mới và từ giờ trở đi, các tài nguyên được lưu trước trong bộ nhớ đệm sẽ tiếp tục được phân phát giống như trước đây.
Trực tiếp sử dụng khoá bộ nhớ đệm
Một số nhà phát triển có thể cần trực tiếp truy cập vào các mục trong bộ nhớ đệm trước, bên ngoài bối cảnh của workbox.precaching.precacheAndRoute(). Ví dụ: bạn có thể lưu trước vào bộ nhớ đệm một hình ảnh mà cuối cùng bạn sử dụng làm phản hồi "dự phòng" khi không thể tìm nạp hình ảnh thực tế từ mạng.
Nếu sử dụng các thành phần được lưu vào bộ nhớ đệm trước theo cách này, bắt đầu từ Workbox phiên bản 4, bạn sẽ cần thực hiện thêm một bước để dịch URL ban đầu thành khoá bộ nhớ đệm tương ứng có thể dùng để đọc mục nhập được lưu vào bộ nhớ đệm. Bạn thực hiện việc này bằng cách gọi workbox.precaching.getCacheKeyForURL(originURL).
Ví dụ: nếu bạn biết rằng 'fallback.png' được lưu vào bộ nhớ đệm trước:
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...
}
});
Dọn dẹp dữ liệu cũ được lưu trước trong bộ nhớ đệm
Những thay đổi được thực hiện để lưu trước vào bộ nhớ đệm trong Workbox v4 có nghĩa là các bộ nhớ đệm cũ hơn, được tạo bởi các phiên bản trước của Workbox, không tương thích. Theo mặc định, các tài nguyên này sẽ được giữ nguyên và nếu nâng cấp từ Workbox phiên bản 3 lên Workbox phiên bản 4, bạn sẽ có hai bản sao của tất cả tài nguyên được lưu vào bộ nhớ đệm trước.
Để tránh điều này, bạn có thể thêm lệnh gọi đến workbox.precaching.cleanupOutdatedCaches() vào trình chạy dịch vụ hoặc đặt tuỳ chọn cleanupOutdatedCaches: true mới nếu sử dụng công cụ xây dựng ở chế độ GenerateSW. Vì logic dọn dẹp bộ nhớ đệm hoạt động theo quy ước đặt tên bộ nhớ đệm để tìm các bộ nhớ đệm trước cũ hơn và vì nhà phát triển có thể ghi đè các quy ước đó, nên chúng tôi đã chọn an toàn và không bật tính năng này theo mặc định.
Nếu gặp bất kỳ vấn đề nào khi sử dụng tính năng này (chẳng hạn như kết quả dương tính giả liên quan đến việc xoá), nhà phát triển nên cho chúng tôi biết.
Cách viết hoa tham số
Đổi tên hai tham số không bắt buộc có thể được truyền đến workbox.precaching.precacheAndRoute() và workbox.precaching.addRoute() để chuẩn hoá quy ước viết hoa tổng thể của chúng tôi. ignoreUrlParametersMatching hiện là ignoreURLParametersMatching và cleanUrls hiện là cleanURLs.
workbox-strategies
Có hai cách gần như tương đương để tạo một thực thể của trình xử lý trong workbox-strategies. Chúng tôi sẽ ngừng sử dụng phương thức nhà máy, thay vào đó sẽ gọi rõ ràng hàm khởi tạo của chiến lược.
// 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({...});
Mặc dù cú pháp phương thức ban đầu sẽ tiếp tục hoạt động trong phiên bản 4, nhưng việc sử dụng cú pháp này sẽ ghi lại một cảnh báo. Vì vậy, các nhà phát triển nên di chuyển trước khi chúng tôi xoá tính năng hỗ trợ trong bản phát hành v5 trong tương lai.
workbox-background-sync
Lớp workbox.backgroundSync.Queue được viết lại để giúp nhà phát triển linh hoạt hơn và có nhiều quyền kiểm soát hơn đối với cách các yêu cầu được thêm vào hàng đợi và phát lại.
Trong phiên bản 3, lớp Queue có một cách duy nhất để thêm yêu cầu vào hàng đợi (phương thức addRequest()). Tuy nhiên, lớp này không có cách nào để sửa đổi hàng đợi hoặc xoá yêu cầu.
Trong phiên bản 4, phương thức addRequests() đã bị xoá và các phương thức giống mảng sau đây đã được thêm vào:
pushRequest()popRequest()shiftRequest()unshiftRequest()
Trong phiên bản 3, lớp Queue cũng chấp nhận một số lệnh gọi lại cho phép bạn quan sát thời điểm các yêu cầu đang được phát lại (requestWillEnqueue, requestWillReplay, queueDidReplay), nhưng hầu hết các nhà phát triển nhận thấy rằng ngoài việc quan sát, họ muốn kiểm soát cách phát lại hàng đợi, bao gồm cả khả năng sửa đổi, sắp xếp lại hoặc thậm chí huỷ các yêu cầu riêng lẻ một cách linh động.
Trong phiên bản 4, các lệnh gọi lại này đã bị xoá để thay thế bằng một lệnh gọi lại onSync duy nhất. Lệnh gọi lại này được gọi bất cứ khi nào trình duyệt cố gắng phát lại. Theo mặc định, lệnh gọi lại onSync sẽ gọi replayRequests(), nhưng nếu cần kiểm soát nhiều hơn đối với quá trình phát lại thì bạn có thể sử dụng các phương thức giống mảng được liệt kê ở trên để phát lại hàng đợi theo ý muốn.
Sau đây là ví dụ về logic phát lại tuỳ chỉnh:
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!');
},
});
Tương tự, lớp workbox.backgroundSync.Plugin chấp nhận các đối số giống như lớp Queue (vì lớp này tạo một thực thể Queue nội bộ), vì vậy, lớp này cũng đã thay đổi theo cách tương tự.
workbox-expiration
Gói npm đã được đổi tên thành workbox-expiration, khớp với quy ước đặt tên dùng cho các mô-đun khác. Gói này có chức năng tương đương với gói workbox-cache-expiration cũ (hiện không còn dùng nữa).
cập nhật thông báo cho hộp công việc
Gói npm được đổi tên thành workbox-broadcast-update, phù hợp với quy ước đặt tên dùng cho các mô-đun khác. Gói này có chức năng tương đương với gói workbox-broadcast-cache-update cũ (hiện không còn được dùng nữa).
workbox-core
Trong Workbox v3, bạn có thể kiểm soát độ chi tiết của cấp độ nhật ký thông qua phương thức workbox.core.setLogLevel(). Bạn sẽ chuyển một trong các giá trị trong enum workbox.core.LOG_LEVELS. Bạn cũng có thể đọc cấp độ nhật ký hiện tại thông qua workbox.core.logLevel.
Trong Workbox phiên bản 4, tất cả các tính năng này đã bị xoá vì tất cả các công cụ dành cho nhà phát triển hiện đại đều có khả năng lọc nhật ký phong phú (xem phần lọc đầu ra của bảng điều khiển cho Công cụ dành cho nhà phát triển Chrome).
workbox-sw
Hai phương thức từng hiển thị trực tiếp trên không gian tên workbox (tương ứng với mô-đun workbox-sw) đã được chuyển sang workbox.core. workbox.skipWaiting() đã trở thành workbox.core.skipWaiting() và tương tự, workbox.clientsClaim() đã trở thành workbox.core.clientsClaim().
Cấu hình công cụ tạo bản dựng
Cách đặt tên một số tuỳ chọn có thể được truyền vào workbox-cli, workbox-build hoặc workbox-webpack-plugin đã thay đổi. Bất cứ khi nào "Url" được sử dụng trong tên tuỳ chọn, URL này sẽ không được dùng nữa và thay vào đó là "URL". Điều này có nghĩa là bạn nên sử dụng các tên tuỳ chọn sau:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
Biến thể "Url" của các tên tuỳ chọn đó vẫn hoạt động trong phiên bản 4, nhưng sẽ dẫn đến thông báo cảnh báo. Nhà phát triển nên di chuyển trước khi phát hành phiên bản 5.
Chức năng mới
cửa sổ hộp công việc
Mô-đun workbox-window mới đơn giản hoá quy trình đăng ký worker dịch vụ và phát hiện bản cập nhật, đồng thời cung cấp phương thức giao tiếp tiêu chuẩn giữa mã chạy trong worker dịch vụ và mã chạy trong ngữ cảnh window của ứng dụng web.
Mặc dù không bắt buộc phải sử dụng workbox-window, nhưng chúng tôi hy vọng rằng nhà phát triển sẽ thấy tính năng này hữu ích và cân nhắc việc di chuyển một số logic viết tay để sử dụng khi thích hợp. Bạn có thể tìm hiểu thêm về cách sử dụng workbox-window trong hướng dẫn về mô-đun.
Ví dụ về quá trình di chuyển
Bạn có thể xem ví dụ về quá trình di chuyển thực tế từ Workbox phiên bản 3 sang phiên bản 4 trong Yêu cầu kéo này.
Nhận trợ giúp
Chúng tôi dự kiến hầu hết các quá trình di chuyển sẽ diễn ra suôn sẻ. Nếu bạn gặp phải vấn đề không được đề cập trong hướng dẫn này, vui lòng cho chúng tôi biết bằng cách mở một vấn đề trên GitHub.