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 6, 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 5.
Thay đổi có thể gây lỗi
lõi máy tính
Phương thức skipWaiting() trong workbox-core sẽ không còn thêm trình xử lý install và tương đương với việc chỉ gọi self.skipWaiting().
Từ giờ, hãy sử dụng self.skipWaiting() vì skipWaiting() có thể sẽ bị xoá trong Workbox phiên bản 7.
workbox-precaching
- Bạn không thể sử dụng tài liệu HTML trên nhiều nguồn gốc cho những URL tương ứng với lệnh chuyển hướng HTTP để đáp ứng yêu cầu điều hướng bằng
workbox-precachingnữa. Trường hợp này thường không phổ biến. - Tham số truy vấn URL
fbclidhiện bịworkbox-precachingbỏ qua khi tra cứu phản hồi được lưu vào bộ nhớ đệm trước cho một yêu cầu nhất định. - Hàm khởi tạo
PrecacheControllerhiện sẽ lấy một đối tượng có các thuộc tính cụ thể làm tham số, thay vì một chuỗi. Đối tượng này hỗ trợ các thuộc tính sau:cacheName(cung cấp cùng một mục đích như chuỗi được truyền vào hàm khởi tạo trong phiên bản 5),plugins(thay thế phương thứcaddPlugins()từ phiên bản 5) vàfallbackToNetwork(thay thế tuỳ chọn tương tự được truyền đếncreateHandler()và "createHandlerBoundToURL() trong phiên bản 5). - Các phương thức
install()vàactivate()củaPrecacheControllerhiện sẽ nhận đúng một tham số, tham số này phải được đặt thànhInstallEventhoặcActivateEventtương ứng. - Phương thức
addRoute()đã bị xoá khỏiPrecacheController. Tại vị trí đó, bạn có thể dùng lớpPrecacheRoutemới để tạo một tuyến mà sau đó bạn có thể đăng ký. - Phương thức
precacheAndRoute()đã bị xoá khỏiPrecacheController. (Phương thức này vẫn tồn tại dưới dạng một phương thức trợ giúp tĩnh do mô-đunworkbox-precachingxuất.) Phương thức này đã bị xoá vì bạn có thể sử dụngPrecacheRoute. - Phương thức
createMatchCalback()đã bị xoá khỏiPrecacheController. Thay vào đó, bạn có thể sử dụngPrecacheRoutemới. - Phương thức
createHandler()đã bị xoá khỏiPrecacheController. Thay vào đó, bạn có thể sử dụng thuộc tínhstrategycủa đối tượngPrecacheControllerđể xử lý các yêu cầu. - Tính năng xuất tĩnh
createHandler()đã bị xoá khỏi mô-đunworkbox-precaching. Thay vào đó, nhà phát triển nên tạo một thực thểPrecacheControllervà sử dụng thuộc tínhstrategycủa thực thể đó. - Tuyến được đăng ký bằng
precacheAndRoute()hiện là một tuyến "thực" sử dụng lớpRoutercủaworkbox-routing. Điều này có thể dẫn đến thứ tự đánh giá khác của các tuyến nếu bạn xen kẽ các lệnh gọi đếnregisterRoute()vàprecacheAndRoute().
workbox-routing
Phương thức setDefaultHandler() hiện sử dụng một tham số thứ hai không bắt buộc tương ứng với phương thức HTTP mà phương thức này áp dụng, mặc định là 'GET'.
- Nếu sử dụng
setDefaultHandler()và tất cả yêu cầu của bạn làGET, thì bạn không cần thực hiện thay đổi nào. - Nếu bạn có bất kỳ yêu cầu nào không phải là
GET(POST,PUT, v.v.),setDefaultHandler()sẽ không còn khiến các yêu cầu đó khớp nữa.
Cấu hình bản dựng
Tuỳ chọn mode cho các chế độ getManifest và injectManifest trong workbox-build và workbox-cli không được hỗ trợ nên đã bị xoá. Điều này không áp dụng cho workbox-webpack-plugin, vì workbox-webpack-plugin hỗ trợ mode trong trình bổ trợ InjectManifest.
Công cụ xây dựng yêu cầu Node.js phiên bản 10 trở lên
Các phiên bản Node.js trước phiên bản 10 không còn được hỗ trợ cho workbox-webpack-plugin, workbox-build hoặc workbox-cli. Nếu bạn đang chạy phiên bản Node.js cũ hơn phiên bản 8, hãy cập nhật thời gian chạy lên phiên bản được hỗ trợ.
Các điểm cải tiến mới
workbox-strategies
Workbox phiên bản 6 giới thiệu một cách mới để nhà phát triển bên thứ ba xác định các chiến lược Workbox của riêng họ. Điều này đảm bảo các nhà phát triển bên thứ ba có thể mở rộng Workbox theo những cách đáp ứng đầy đủ nhu cầu của họ.
Lớp cơ sở về Chiến lược mới
Trong phiên bản 6, tất cả các lớp chiến lược Workbox phải mở rộng lớp cơ sở Strategy mới. Tất cả các chiến lược tích hợp sẵn đều được viết lại để hỗ trợ việc này.
Lớp cơ sở Strategy chịu trách nhiệm về 2 việc chính:
- Gọi lệnh gọi lại trong vòng đời của trình bổ trợ phổ biến cho tất cả trình xử lý chiến lược (ví dụ: khi bắt đầu, phản hồi và kết thúc).
- Tạo một thực thể "handler" có thể quản lý trạng thái cho từng yêu cầu riêng lẻ mà chiến lược đang xử lý.
Lớp "trình xử lý" mới
Trước đây, chúng tôi có các mô-đun nội bộ gọi là fetchWrapper và cacheWrapper. Các mô-đun này (như tên gọi của chúng) gói nhiều API tìm nạp và lưu vào bộ nhớ đệm bằng các trình bổ trợ vào vòng đời của chúng. Đây là cơ chế hiện cho phép các trình bổ trợ hoạt động, nhưng không được hiển thị cho nhà phát triển.
Lớp "trình xử lý" mới, StrategyHandler, sẽ hiển thị các phương thức này để các chiến lược tuỳ chỉnh có thể gọi fetch() hoặc cacheMatch() và tự động gọi mọi trình bổ trợ đã thêm vào thực thể chiến lược.
Lớp này cũng cho phép nhà phát triển thêm các lệnh gọi lại tuỳ chỉnh, vòng đời riêng có thể dành riêng cho các chiến lược của họ và các lệnh gọi lại này sẽ "chỉ hoạt động" với giao diện trình bổ trợ hiện có.
Trạng thái vòng đời trình bổ trợ mới
Trong Workbox phiên bản 5, các trình bổ trợ không có trạng thái. Điều đó có nghĩa là nếu một yêu cầu cho /index.html kích hoạt cả lệnh gọi lại requestWillFetch và cachedResponseWillBeUsed, thì hai lệnh gọi lại đó không có cách nào để giao tiếp với nhau hoặc thậm chí không biết rằng chúng được kích hoạt bởi cùng một yêu cầu.
Trong phiên bản 6, tất cả lệnh gọi lại trình bổ trợ cũng sẽ được truyền một đối tượng state mới. Đối tượng trạng thái này sẽ là duy nhất cho đối tượng trình bổ trợ cụ thể này và lệnh gọi chiến lược cụ thể này (tức là lệnh gọi đến handle()). Đối tượng này cho phép nhà phát triển viết các trình bổ trợ mà một lệnh gọi lại có thể thực hiện có điều kiện dựa trên những gì một lệnh gọi lại khác trong cùng một trình bổ trợ đã thực hiện (ví dụ: tính toán delta thời gian giữa việc chạy requestWillFetch và fetchDidSucceed hoặc fetchDidFail).
Phương thức gọi lại mới trong vòng đời của trình bổ trợ
Chúng tôi đã thêm các lệnh gọi lại vòng đời trình bổ trợ mới để cho phép nhà phát triển khai thác tối đa trạng thái vòng đời trình bổ trợ:
handlerWillStart: được gọi trước khi bất kỳ logic trình xử lý nào bắt đầu chạy. Bạn có thể dùng lệnh gọi lại này để đặt trạng thái trình xử lý ban đầu (ví dụ: ghi lại thời gian bắt đầu).handlerWillRespond: được gọi trước khi phương thứchandle()của chiến lược trả về phản hồi. Bạn có thể dùng lệnh gọi lại này để sửa đổi phản hồi đó trước khi trả về cho trình xử lý tuyến hoặc logic tuỳ chỉnh khác.handlerDidRespond: được gọi sau khi phương thứchandle()của chiến lược trả về một phản hồi. Bạn có thể sử dụng lệnh gọi lại này để ghi lại mọi thông tin chi tiết về phản hồi cuối cùng, ví dụ: sau khi các trình bổ trợ khác thực hiện thay đổi.handlerDidComplete: được gọi sau khi tất cả lời hứa kéo dài thời gian hoạt động được thêm vào sự kiện từ lệnh gọi của chiến lược này đã được giải quyết. Bạn có thể dùng lệnh gọi lại này để báo cáo về mọi dữ liệu cần chờ cho đến khi trình xử lý hoàn tất để tính toán (ví dụ: trạng thái truy cập vào bộ nhớ đệm, độ trễ của bộ nhớ đệm, độ trễ của mạng).handlerDidError: được gọi nếu trình xử lý không thể cung cấp phản hồi hợp lệ từ bất kỳ nguồn nào. Bạn có thể sử dụng lệnh gọi lại này để cung cấp nội dung "phòng ngừa" thay cho lỗi mạng.
Các nhà phát triển đang triển khai các chiến lược tuỳ chỉnh của riêng mình không phải lo lắng về việc tự gọi các lệnh gọi lại này; tất cả đều do một lớp cơ sở Strategy mới xử lý.
Các loại TypeScript chính xác hơn cho trình xử lý
Các định nghĩa TypeScript cho nhiều phương thức gọi lại đã được chuẩn hoá. Điều này sẽ mang lại trải nghiệm tốt hơn cho các nhà phát triển sử dụng TypeScript và tự viết mã để triển khai hoặc gọi trình xử lý.
workbox-window
Phương thức messageSkipWaiting() mới
Một phương thức mới, messageSkipWaiting(), đã được thêm vào mô-đun workbox-window để đơn giản hoá quá trình yêu cầu worker dịch vụ"đang chờ" kích hoạt. Điều này mang lại một số điểm cải tiến:
- Phương thức này gọi
postMessage()bằng nội dung tin nhắn chuẩn thực tế,{type: 'SKIP_WAITING'}, mà một worker dịch vụ do Workbox tạo ra sẽ kiểm tra để kích hoạtskipWaiting(). - Phương thức này chọn trình chạy dịch vụ "đang chờ" chính xác để đăng thông báo này, ngay cả khi đó không phải là trình chạy dịch vụ mà
workbox-windowđã đăng ký.
Xoá các sự kiện "bên ngoài" và thay bằng một Thuộc tính bên ngoài
Tất cả sự kiện "bên ngoài" trong workbox-window đã bị xoá thay cho sự kiện "bình thường" có thuộc tính isExternal được đặt thành true. Điều này cho phép các nhà phát triển quan tâm đến sự khác biệt vẫn có thể phát hiện sự khác biệt đó, còn những nhà phát triển không cần biết thì có thể bỏ qua thuộc tính này.
Công thức "Đề xuất tải lại trang cho người dùng" gọn gàng hơn
Nhờ cả hai thay đổi nêu trên, bạn có thể đơn giản hoá công thức "Đề xuất tải lại trang cho người dùng":
MULTI_LINE_CODE_PLACEHOLDER_0
định tuyến hộp làm việc
Tham số boolean mới sameOrigin được truyền đến hàm matchCallback dùng trong workbox-routing. Giá trị này được đặt thành true nếu yêu cầu là cho một URL cùng nguồn gốc và false nếu không.
Việc này giúp đơn giản hoá một số mã nguyên mẫu phổ biến:
MULTI_LINE_CODE_PLACEHOLDER_1
matchOptions trong workbox-expiration
Giờ đây, bạn có thể đặt matchOptions trong workbox-expiration, sau đó sẽ được truyền dưới dạng CacheQueryOptions sang lệnh gọi cache.delete() cơ bản. (Hầu hết các nhà phát triển sẽ không cần làm việc này.)
workbox-precaching
Sử dụng workbox-strategies
workbox-precaching đã được viết lại để sử dụng workbox-strategies làm cơ sở. Việc này sẽ không dẫn đến bất kỳ thay đổi nào có thể gây lỗi và sẽ giúp tăng tính nhất quán về lâu dài trong cách hai mô-đun truy cập vào mạng và bộ nhớ đệm.
Tính năng lưu vào bộ nhớ đệm trước hiện xử lý từng mục nhập, chứ không phải hàng loạt
Cập nhật workbox-precaching để mỗi lần chỉ yêu cầu một mục trong tệp kê khai bộ nhớ đệm trước và lưu vào bộ nhớ đệm, thay vì cố gắng yêu cầu và lưu vào bộ nhớ đệm tất cả mục cùng lúc (giao cho trình duyệt tìm ra cách điều tiết).
Điều này sẽ làm giảm khả năng xảy ra lỗi net::ERR_INSUFFICIENT_RESOURCES trong khi lưu vào bộ nhớ đệm trước, đồng thời giảm tình trạng tranh chấp băng thông giữa việc lưu vào bộ nhớ đệm trước và các yêu cầu đồng thời do ứng dụng web thực hiện.
PrecacheFallbackPlugin giúp việc dự phòng ngoại tuyến dễ dàng hơn
workbox-precaching nay bao gồm một PrecacheFallbackPlugin, giúp triển khai phương thức vòng đời handlerDidError mới được thêm vào phiên bản 6.
Điều này giúp bạn dễ dàng chỉ định một URL được lưu vào bộ nhớ đệm trước làm "phương án dự phòng" cho một chiến lược nhất định khi không có phản hồi nào. Trình bổ trợ sẽ giúp bạn tạo đúng khoá bộ nhớ đệm cho URL được lưu vào bộ nhớ đệm trước, bao gồm mọi tham số sửa đổi cần thiết.
Sau đây là ví dụ về cách sử dụng phương thức này để phản hồi bằng /offline.html được lưu vào bộ nhớ đệm trước khi chiến lược NetworkOnly không thể tạo phản hồi cho yêu cầu điều hướng – nói cách khác, hiển thị trang HTML ngoại tuyến tuỳ chỉnh:
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback trong bộ nhớ đệm trong thời gian chạy
Nếu đang sử dụng generateSW để tạo trình chạy dịch vụ thay vì viết trình chạy dịch vụ theo cách thủ công, bạn có thể sử dụng tuỳ chọn cấu hình precacheFallback mới trong runtimeCaching để thực hiện cùng một việc:
{
// ... other generateSW config options...
runtimeCaching: [{
urlPattern: ({request}) => request.mode === 'navigate',
handler: 'NetworkOnly',
options: {
precacheFallback: {
// This URL needs to be included in your precache manifest.
fallbackURL: '/offline.html',
},
},
}],
}
Nhận Trợ giúp
Chúng tôi dự đoán rằng hầu hết các quá trình di chuyển sẽ đơn giản. Nếu bạn gặp những 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.