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 v4, 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 v3.
Thay đổi có thể gây lỗi
lưu trước hộp công việc
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. Hiện tại, đối với các mục nhập có URL cần thông tin sửa đổi (tức là các 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 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 khả năng lưu trước vào bộ nhớ đệm thông qua workbox.precaching.precacheAndRoute() (trường hợp sử dụng phổ biến nhất) không cần thay đổi cấu hình trình chạy dịch vụ. Khi nâng cấp lên Workbox phiên bản 4, nội dung đã lưu vào bộ nhớ đệm của người dùng sẽ tự động chuyển sang định dạng khoá bộ nhớ đệm mới. Từ nay về sau, các tài nguyên được lưu trước vào bộ nhớ đệm sẽ tiếp tục được phân phát theo cách tương tự 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 phải truy cập trực tiếp vào các mục nhập trước trong bộ nhớ đệm, bên ngoài bối cảnh của workbox.precaching.precacheAndRoute(). Ví dụ: bạn có thể lưu trước một hình ảnh vào bộ nhớ đệm mà cuối cùng bạn sẽ 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 nội dung được lưu trước vào bộ nhớ đệm theo cách này, kể 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 sang khoá bộ nhớ đệm tương ứng để đọc mục nhập đã 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 trước vào bộ nhớ đệm:
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 đối với tính năng lưu trước vào bộ nhớ đệm trong Workbox v4 có nghĩa là bộ nhớ đệm trước cũ hơn, được tạo bởi các phiên bản Workbox trước, 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 bạn nâng cấp từ Workbox v3 lên Workbox v4, bạn sẽ nhận được hai bản sao của tất cả các tài nguyên được lưu trước vào bộ nhớ đệm.
Để tránh trường hợp này, bạn có thể trực tiếp thêm lệnh gọi đến workbox.precaching.cleanupOutdatedCaches() cho một 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 xoá bộ nhớ đệm hoạt động trên các quy ước đặt tên bộ nhớ đệm để tìm các bộ nhớ đệm cũ cũng như do các nhà phát triển có lựa chọn ghi đè các quy ước đó nên chúng tôi đã sai sót về mặt an toàn và không bật tính năng này theo mặc định.
Các nhà phát triển gặp phải vấn đề liên quan đến việc xoá tài khoản (chẳng hạn như đánh giá sai về việc xoá) nên cho chúng tôi biết.
Viết hoa thông số
Chúng tôi đã đổi tên hai thông 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.
chiến lược hộp làm việc
Có 2 cách 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 gốc, thay vào đó là 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 gốc 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. Các nhà phát triển nên di chuyển trước việc ngừng hỗ trợ trong bản phát hành phiên bản 5 sau này.
đồng bộ hoá nền hộp công việc
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 thêm yêu cầu 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()), nhưng 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 như mảng sau đã đượ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 được phát lại (requestWillEnqueue, requestWillReplay, queueDidReplay). Tuy nhiên, hầu hết các nhà phát triển đều nhận thấy rằng ngoài việc quan sát, họ còn muốn kiểm soát cách hàng đợi được phát lại, bao gồm cả khả năng tự động sửa đổi, sắp xếp lại hoặc thậm chí huỷ từng yêu cầu.
Trong phiên bản 4, các lệnh gọi lại này đã bị loại bỏ và thay vào đó là 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 thực hiện lệnh gọi lại. Theo mặc định, lệnh gọi lại onSync sẽ gọi replayRequests(), nhưng nếu cần có thêm quyền kiểm soát đối với quá trình phát lại, bạn có thể sử dụng các phương thức giống như mảng được liệt kê ở trên để phát lại hàng đợi theo cách bạn muốn.
Dưới đâ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ố tương tự như lớp Queue (vì lớp này tạo ra một thực thể Queue nội bộ), vì vậy lớp này đã thay đổi theo cách tương tự.
hộp-công-việc-hết-hạn
Gói npm được đổi tên thành workbox-expiration, 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-cache-expiration cũ, hiện không dùng nữa.
cập nhật 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 dùng nữa.
lõi hộp công việc
Trong Workbox v3, bạn có thể kiểm soát độ chi tiết của các cấp độ nhật ký thông qua phương thức workbox.core.setLogLevel(). Phương thức này sẽ truyền một trong các giá trị thuộc 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ả những tính năng này đã bị loại bỏ vì tất cả các công cụ hiện đại dành cho nhà phát triển hiện đều đi kèm với khả năng lọc nhật ký phong phú (xem phần lọc đầu ra từ bảng điều khiển cho Công cụ dành cho nhà phát triển Chrome).
hộp-công-việc-sw
2 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ụ xây dựng
Đã thay đổi tên của một số tuỳ chọn có thể truyền vào workbox-cli, workbox-build hoặc workbox-webpack-plugin. Bất cứ khi nào "Url" được sử dụng trong tên tùy chọn, từ này sẽ không được dùng nữa và được thay thế bằng "URL". Điều này có nghĩa là các tên tuỳ chọn sau sẽ được ưu tiên hơn:
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. Các nhà phát triển nên di chuyển trước bản phát hành v5.
Chức năng mới
cửa sổ hộp làm việc
Mô-đun workbox-window mới đơn giản hoá quy trình đăng ký trình chạy dịch vụ và phát hiện các bản cập nhật, đồng thời cung cấp một phương thức giao tiếp tiêu chuẩn giữa mã chạy trong trình chạy dịch vụ và mã chạy trong ngữ cảnh window của ứng dụng web.
Mặc dù việc sử dụng workbox-window là không bắt buộc, nhưng chúng tôi hy vọng rằng các nhà phát triển sẽ thấy tính năng này hữu ích. Hãy cân nhắc việc di chuyển một số logic viết tay của họ để 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 của mô-đun.
Ví dụ về quá trình di chuyển
Bạn có thể tìm thấy ví dụ về quá trình di chuyển thực tế từ Workbox v3 sang v4 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 quá trình di chuyển sẽ đơn giản. Nếu bạn gặp các 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.