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 v6, với các 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-box-core
Phương thức skipWaiting()
trong workbox-core
sẽ không còn thêm vào trình xử lý install
và tương đương với việc chỉ gọi self.skipWaiting()
.
Từ giờ trở đi, hãy dùng self.skipWaiting()
thay vào đó, vì skipWaiting()
có thể sẽ bị xoá trong Workbox phiên bản 7.
đóng hộp làm việc
- Bạn không thể sử dụng tài liệu HTML trên nhiều nguồn gốc cho các 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-precaching
nữa. Trường hợp này thường không phổ biến. workbox-precaching
hiện sẽ bỏ qua tham số truy vấn URLfbclid
khi tra cứu một phản hồi được lưu trước vào bộ nhớ đệm cho một yêu cầu nhất định.- Hàm khởi tạo
PrecacheController
hiện 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
(có cùng mục đích với 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 chuyển đếncreateHandler()
và `createHandlerBoundToURL() trong phiên bản 5). - Phương thức
install()
vàactivate()
củaPrecacheController
hiện lấy chính xác một tham số, phải được đặt thànhInstallEvent
hoặcActivateEvent
tương ứng tương ứng. - Phương thức
addRoute()
đã bị xoá khỏiPrecacheController
. Thay vào đó, bạn có thể sử dụng lớpPrecacheRoute
mới để tạo một tuyến mà sau đó 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-precaching
xuất.) Thuộc tính này đã bị xoá vì có thể sử dụngPrecacheRoute
thay thế. - Phương thức
createMatchCalback()
đã bị xoá khỏiPrecacheController
. Bạn có thể sử dụngPrecacheRoute
mới. - Phương thức
createHandler()
đã bị xoá khỏiPrecacheController
. Bạn có thể sử dụng thuộc tínhstrategy
của đối tượngPrecacheController
để xử lý các yêu cầu. - Tính năng xuất dữ liệu tĩnh
createHandler()
đã bị xoá khỏi mô-đunworkbox-precaching
. Tại đó, nhà phát triển nên tạo một thực thểPrecacheController
và sử dụng thuộc tínhstrategy
của thực thể đó. - Tuyến đã đăng ký với
precacheAndRoute()
hiện là tuyến "thực" sử dụng lớpRouter
củaworkbox-routing
nâng cao. Điều này có thể dẫn đến thứ tự đánh giá các tuyến khác nếu bạn xen kẽ các lệnh gọi đếnregisterRoute()
vàprecacheAndRoute()
.
định tuyến hộp công việc
Phương thức setDefaultHandler()
hiện sẽ lấy một tham số thứ hai (không bắt buộc) tương ứng với phương thức HTTP được áp dụng, đặt mặc định là 'GET'
.
- Nếu bạn sử dụng
setDefaultHandler()
và tất cả yêu cầu của bạn đều làGET
, thì bạn không cần thay đổi gì cả. - Nếu bạn có yêu cầu không phải là
GET
(POST
,PUT
, v.v.),setDefaultHandler()
sẽ không còn làm cho các yêu cầu đó khớp với nhau 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ợ và đã bị xoá. Điều này không áp dụng cho workbox-webpack-plugin
, vì trình bổ trợ này 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 một phiên bản được hỗ trợ.
Điểm cải tiến mới
chiến lược hộp công việc
Workbox v6 giới thiệu một cách mới để các nhà phát triển bên thứ ba xác định chiến lược Workbox của riêng họ. Điều này đảm bảo rằng 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ở Chiến lược mới
Trong phiên bản 6, tất 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 đã được viết lại để hỗ trợ điều này.
Lớp cơ sở Strategy
chịu trách nhiệm cho hai nội dung chính:
- Gọi các phương thức gọi lại trong vòng đời trình bổ trợ phổ biến cho tất cả các trình xử lý chiến lược (ví dụ: khi chúng bắt đầu, phản hồi và kết thúc).
- Tạo một thực thể "trình xử lý", 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 fetchWrapper
và cacheWrapper
, đúng như tên gọi của chúng) gói nhiều API tìm nạp và bộ nhớ đệm bằng hook 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 nhà phát triển không nhìn thấy cơ chế này.
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()
, đồng thời 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 giúp các nhà phát triển có thể thêm các phương thức gọi lại tuỳ chỉnh, trong vòng đời của riêng họ, dành riêng cho các chiến lược của họ. Các phương thức này sẽ "hoạt động" với giao diện trình bổ trợ hiện có.
Trạng thái vòng đời mới của trình bổ trợ
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 đó sẽ 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ả cá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 đối với đố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 trình bổ trợ mà trong đó một lệnh gọi lại có thể thực hiện một cách có điều kiện dựa trên hoạt động của một lệnh gọi lại khác trong cùng một trình bổ trợ (ví dụ: tính toán thời gian delta giữa thời gian chạy requestWillFetch
và fetchDidSucceed
hoặc fetchDidFail
).
Phương thức gọi lại trong vòng đời của trình bổ trợ mới
Thêm các phương thức gọi lại mới trong vòng đời của trình bổ trợ để cho phép nhà phát triển tận dụng hoàn toàn trạng thái vòng đời của trình bổ trợ:
handlerWillStart
: được gọi trước khi bất kỳ logic nào của trình xử lý bắt đầu chạy. Bạn có thể sử dụng lệnh gọi lại này để đặt trạng thái của 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ề một trình xử lý định 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ề phản hồi. Bạn có thể 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ụ như sau các thay đổi do các trình bổ trợ khác thực hiện.handlerDidComplete
: được gọi sau khi tất cả lời hứa hẹn kéo dài thời gian hoạt động được thêm vào sự kiện từ khi gọi chiến lược này đã được giải quyết. Bạn có thể sử dụng lệnh gọi lại này để báo cáo về mọi dữ liệu cần phải đợi cho đến khi trình xử lý hoàn tất để tính toán (ví dụ: trạng thái nhấn vào bộ nhớ đệm, độ trễ bộ nhớ đệm, độ trễ 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 "dự phòng" như một giải pháp thay thế cho lỗi mạng.
Các nhà phát triển 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; việc này sẽ do một lớp cơ sở Strategy
mới xử lý.
Các loại TypeScript chính xác hơn dành 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 những nhà phát triển sử dụng TypeScript và viết mã của riêng họ để triển khai hoặc gọi trình xử lý.
cửa sổ hộp làm việc
Phương thức ignoreWait() 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 trình chạy dịch vụ"chờ" kích hoạt. Điều này sẽ 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 thông báo chuẩn trên thực tế là{type: 'SKIP_WAITING'}
mà một trình chạy dịch vụ do Workbox tạo sẽ kiểm tra để kích hoạtskipWaiting()
. - Phương thức này chọn đúng trình chạy dịch vụ "đang chờ" để đă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
được đăng ký.
Xoá các sự kiện "bên ngoài" và thay bằng tài sản isExternal
Tất cả sự kiện "external" trong workbox-window
đã bị xoá thay cho sự kiện "bình thường" có tài sản isExternal
được đặt thành true
. Nhờ đó, những nhà phát triển quan tâm đến sự khác biệt vẫn có thể phát hiện được tài sản đó, còn những nhà phát triển không cần biết có thể bỏ qua tài sản đó.
Công thức dọn dẹp "Cung cấp một trang tải lại cho người dùng"
Nhờ cả hai thay đổi ở trên, bạn có thể đơn giản hóa công thức "Cung cấp một trang tải lại cho người dùng":
MULTI_LINE_CODE_PLACEHOLDER_0
định tuyến hộp công việc
Một tham số boolean mới, sameOrigin
, được truyền đến hàm matchCallback
được dùng trong workbox-routing
. Giá trị này được đặt thành true
nếu yêu cầu cho cùng một URL có nguồn gốc và giá trị là false nếu không yêu cầu.
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 trạng thái hết hạn của hộp công việc
Bây giờ, bạn có thể thiết lập matchOptions
trong workbox-expiration
. Sau đó, giá trị này sẽ được truyền dưới dạng CacheQueryOptions
đến 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 thực hiện việc này.)
đóng hộp làm việc
Sử dụng chiến lược hộp công việc
workbox-precaching
đã được viết lại để dùng workbox-strategies
làm cơ sở. Điều này sẽ không dẫn đến bất kỳ thay đổi có thể gây lỗi nào và sẽ giúp cải thiện tính nhất quán lâu dài về cách hai mô-đun truy cập mạng và bộ nhớ đệm.
Tính năng lưu trước vào bộ nhớ đệm hiện xử lý từng mục một, chứ không xử lý hàng loạt
workbox-precaching
đã được cập nhật để chỉ một mục trong tệp kê khai bộ nhớ đệm được yêu cầu và lưu vào bộ nhớ đệm tại một thời điểm, thay vì cố gắng yêu cầu và lưu tất cả các mục vào bộ nhớ đệm cùng một lúc (để trình duyệt tìm cách điều tiết).
Điều này sẽ làm giảm khả năng net::ERR_INSUFFICIENT_RESOURCES
xảy ra lỗi khi lưu trước vào bộ nhớ đệm, đồng thời giảm tranh chấp băng thông giữa việc lưu trước vào bộ nhớ đệm và các yêu cầu đồng thời do ứng dụng web đưa ra.
PrecacheFallbackPlugin cho phép dự phòng ngoại tuyến dễ dàng hơn
workbox-precaching
hiện 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 trước trong bộ nhớ đệm làm "dự phòng" cho một chiến lược nhất định khi không có phản hồi. Trình bổ trợ này sẽ đảm nhiệm việc xây dựng đúng khoá bộ nhớ đệm chính xác cho URL được lưu trước vào bộ nhớ đệm, bao gồm cả mọi tham số sửa đổi cần thiết.
Dưới đây là ví dụ về cách sử dụng nó để phản hồi bằng /offline.html
được lưu trước vào bộ nhớ đệm khi chiến lược NetworkOnly
không thể tạo phản hồi cho một yêu cầu điều hướng, nói cách khác là hiển thị trang HTML ngoại tuyến tuỳ chỉnh:
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback
trong bộ nhớ đệm thời gian chạy
Nếu đang sử dụng generateSW
để tạo trình chạy dịch vụ cho bạn 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 điều tương tự:
{
// ... 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 cho rằng hầu hết quá trình di chuyển sẽ đơn giản. Nếu bạn gặp phải các vấn đề không có trong hướng dẫn này, vui lòng cho chúng tôi biết bằng cách mở vấn đề trên GitHub.