Di chuyển từ Workbox phiên bản 5 sang phiên bản 6

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 URL fbclid 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ức addPlugins() từ phiên bản 5) và fallbackToNetwork (thay thế tuỳ chọn tương tự đã được chuyển đến createHandler() và `createHandlerBoundToURL() trong phiên bản 5).
  • Phương thức install() và activate() của PrecacheController hiện lấy chính xác một tham số, phải được đặt thành InstallEvent hoặc ActivateEvent tương ứng tương ứng.
  • Phương thức addRoute() đã bị xoá khỏi PrecacheController. Thay vào đó, bạn có thể sử dụng lớp PrecacheRoute mới để tạo một tuyến mà sau đó có thể đăng ký.
  • Phương thức precacheAndRoute() đã bị xoá khỏi PrecacheController. (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ô-đun workbox-precaching xuất.) Thuộc tính này đã bị xoá vì có thể sử dụng PrecacheRoute thay thế.
  • Phương thức createMatchCalback() đã bị xoá khỏi PrecacheController. Bạn có thể sử dụng PrecacheRoute mới.
  • Phương thức createHandler() đã bị xoá khỏi PrecacheController. Bạn có thể sử dụng thuộc tính strategy của đối tượng PrecacheController để 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ô-đun workbox-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ính strategy của thực thể đó.
  • Tuyến đã đăng ký với precacheAndRoute() hiện là tuyến "thực" sử dụng lớp Router của workbox-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 đến registerRoute() 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ức handle() 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ức handle() 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ạt skipWaiting().
  • 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.