ย้ายข้อมูลจาก Workbox v4 ไปยัง v5

คู่มือนี้มุ่งเน้นที่การเปลี่ยนแปลงที่สำคัญซึ่งเปิดตัวใน Workbox v5 พร้อมตัวอย่างการเปลี่ยนแปลงที่คุณต้องทำเมื่ออัปเกรดจาก Workbox v4

การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ

เปลี่ยนชื่อคลาสปลั๊กอิน

แพ็กเกจ Workbox v4 จำนวนหนึ่งมีคลาสชื่อ Plugin รวมอยู่ด้วย ใน v5 คลาสเหล่านั้นได้เปลี่ยนชื่อให้เป็นไปตามรูปแบบตัวระบุแพ็กเกจ + Plugin ดังนี้

  • BackgroundSyncPlugin
  • BroadcastUpdatePlugin
  • CacheableResponsePlugin
  • ExpirationPlugin
  • RangeRequestsPlugin

การเปลี่ยนชื่อนี้จะมีผลไม่ว่าคุณจะใช้คลาสผ่านการนําเข้าโมดูลหรือผ่านเนมสเปซ workbox.*

จุดเริ่มต้นการแทนที่ไฟล์ Manifest สำหรับการแคชล่วงหน้าเริ่มต้น

ก่อนหน้านี้ เมื่อใช้เครื่องมือสร้างอย่างใดอย่างหนึ่งในโหมด "แทรกไฟล์ Manifest" ระบบจะตรวจสอบไฟล์ Service Worker ต้นทางเพื่อหา precacheAndRoute([]) โดยจะใช้อาร์เรย์ว่าง [] เป็นตัวยึดตําแหน่งสําหรับจุดที่แทรกไฟล์ Manifest แคชล่วงหน้า

ใน Workbox v5 ตรรกะการแทนที่มีการเปลี่ยนแปลง และตอนนี้จะมีการใช้ self.__WB_MANIFEST เป็นจุดแทรกโดยค่าเริ่มต้น

// v4:
precacheAndRoute([]);

// v5:
precacheAndRoute(self.__WB_MANIFEST);

ดังที่ได้กล่าวไว้ในการพูดคุยนี้ เราเชื่อว่าการเปลี่ยนแปลงนี้จะสร้างประสบการณ์การใช้งานที่ง่ายขึ้น ขณะเดียวกันก็ช่วยให้นักพัฒนาซอฟต์แวร์สามารถควบคุมวิธีใช้ไฟล์ Manifest ที่แทรกภายในโค้ดโปรแกรมทำงานของบริการที่กำหนดเองได้มากขึ้น คุณเปลี่ยนสตริงการแทนที่นี้ได้หากจำเป็นผ่านตัวเลือกการกำหนดค่า injectionPoint

ตัวเลือก 2 รายการที่ได้รับการสนับสนุนสำหรับเส้นทางการนำทางก่อนหน้านี้ ได้แก่ blacklist และ whitelist เปลี่ยนชื่อเป็น denylist และ allowlist

ก่อนหน้านี้ workbox-routing รองรับเมธอด registerNavigationRoute() ซึ่งทำงาน 2 อย่างต่อไปนี้

  1. ตรวจพบว่าเหตุการณ์ fetch หนึ่งๆ มี mode ของ 'navigate' หรือไม่
  2. หากใช่ จะตอบสนองคำขอนั้นโดยใช้เนื้อหาของ URL แบบฮาร์ดโค้ดที่แคชไว้ก่อนหน้านี้ โดยไม่คำนึงถึง URL ที่มีการเข้าถึง

รูปแบบนี้เป็นรูปแบบที่ใช้กันโดยทั่วไปเมื่อติดตั้งใช้งานสถาปัตยกรรม App Shell

ขั้นตอนที่ 2 ในการสร้างการตอบกลับด้วยการอ่านจากแคชจะอยู่นอกเหนือความรับผิดชอบของ workbox-routing แต่เรามองว่าเป็นฟังก์ชันที่ควรเป็นส่วนหนึ่งของ workbox-precaching โดยใช้วิธีการใหม่ นั่นคือ createHandlerBoundToURL() วิธีการใหม่นี้ทํางานร่วมกับคลาส NavigationRoute ที่มีอยู่ได้ใน workbox-routing เพื่อให้ได้ตรรกะเดียวกัน

หากคุณใช้ตัวเลือก navigateFallback ใน "สร้าง SW" รายการใดรายการหนึ่งของเครื่องมือสร้าง การสลับอุปกรณ์ก็จะเกิดขึ้นโดยอัตโนมัติ หากคุณเคยกําหนดค่าตัวเลือก navigateFallbackBlacklist หรือ navigateFallbackWhitelist ให้เปลี่ยนเป็น navigateFallbackDenylist หรือ navigateFallbackAllowlist ตามลําดับ

หากคุณใช้โหมด "แทรกไฟล์ Manifest" หรือเขียน Service Worker ด้วยตนเอง และ Service Worker ของ Workbox v4 เรียก registerNavigationRoute() โดยตรง คุณจะต้องทําการเปลี่ยนแปลงโค้ดเพื่อให้ได้ลักษณะการทํางานที่เทียบเท่า

// v4:
import {getCacheKeyForURL} from 'workbox-precaching';
import {registerNavigationRoute} from 'workbox-routing';

const appShellCacheKey = getCacheKeyForURL('/app-shell.html');
registerNavigationRoute(appShellCacheKey, {
  whitelist: [...],
  blacklist: [...],
});

// v5:
import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';

const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler, {
  allowlist: [...],
  denylist: [...],
});
registerRoute(navigationRoute);

คุณไม่จำเป็นต้องโทรหา getCacheKeyForURL() อีกต่อไป เนื่องจาก createHandlerBoundToURL() จะจัดการเรื่องนี้ให้คุณ

การนำ makeRequest() ออกจาก workbox-strategies

การโทรออก makeRequest() ส่วนใหญ่จะเทียบเท่ากับการโทรหา handle() ในชั้นเรียน workbox-strategy ความแตกต่างระหว่าง 2 วิธีนี้น้อยมากจนการคงไว้ทั้ง 2 วิธีนั้นไม่สมเหตุสมผล นักพัฒนาแอปที่เรียกใช้ makeRequest() ควรเปลี่ยนไปใช้ handle() ได้โดยไม่ต้องเปลี่ยนแปลงอะไรเพิ่มเติม

// v4:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.makeRequest({event, request});

// v5:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.handle({event, request});

ในเวอร์ชัน 5 handle() จะถือว่า request เป็นพารามิเตอร์ที่จำเป็น และจะไม่กลับไปใช้ event.request โปรดตรวจสอบว่าคุณส่งคำขอที่ถูกต้องเมื่อโทรหา handle()

Workbox-broadcast-update ใช้ postMessage() เสมอ

ในเวอร์ชัน 4 ไลบรารี workbox-broadcast-update จะใช้ Broadcast Channel API ในการส่งข้อความเมื่อมีการรองรับ และกลับไปใช้ postMessage() เฉพาะเมื่อไม่รองรับช่องออกอากาศ

เราตระหนักว่าการต้องคอยฟังแหล่งที่มา 2 แหล่งของข้อความขาเข้าทำให้การเขียนโค้ดฝั่งไคลเอ็นต์ซับซ้อนเกินไป นอกจากนี้ ในบางเบราว์เซอร์ การเรียก postMessage() จาก Service Worker ที่ส่งไปยังหน้าไคลเอ็นต์จะได้รับการบัฟเฟอร์โดยอัตโนมัติจนกว่าจะมีการตั้งค่า Listener เหตุการณ์ message โดย API ช่องสัญญาณออกอากาศจะไม่เกิดการบัฟเฟอร์ และข้อความที่เผยแพร่จะหายไปหากส่งก่อนที่หน้าไคลเอ็นต์จะพร้อมรับ

ด้วยเหตุนี้ เราจึงได้เปลี่ยน workbox-broadcast-update ให้ใช้ postMessage() เสมอใน v5 ระบบจะส่งข้อความทีละรายการไปยังหน้าไคลเอ็นต์ทั้งหมดภายในขอบเขตของ Service Worker ปัจจุบัน

หากต้องการรองรับลักษณะการทำงานแบบใหม่นี้ ให้นำโค้ดที่มีอยู่ในหน้าไคลเอ็นต์ซึ่งสร้างอินสแตนซ์ BroadcastChannel ออก แล้วตั้งค่าโปรแกรมรับฟังเหตุการณ์ message ใน navigator.serviceWorker แทน

// v4:
const updatesChannel = new BroadcastChannel('api-updates');
updatesChannel.addEventListener('message', event => {
  const {cacheName, updatedUrl} = event.data.payload;
  // ... your code here ...
});

// v5:
// This listener should be added as early as possible in your page's lifespan
// to ensure that messages are properly buffered.
navigator.serviceWorker.addEventListener('message', event => {
  // Optional: ensure the message came from workbox-broadcast-update
  if (event.meta === 'workbox-broadcast-update') {
    const {cacheName, updatedUrl} = event.data.payload;
    // ... your code here ...
  }
});

ผู้ใช้ workbox-window ไม่ควรต้องทําการเปลี่ยนแปลงใดๆ เนื่องจากระบบได้อัปเดตตรรกะภายในเพื่อรอการเรียก postMessage() แล้ว

เครื่องมือสร้างต้องใช้ Node.js v8 ขึ้นไป

เราไม่รองรับ Node.js เวอร์ชันก่อน v8 สำหรับ workbox-webpack-plugin, workbox-build หรือ workbox-cli อีกต่อไป หากคุณใช้ Node.js เวอร์ชันก่อนหน้าเวอร์ชัน 8 ให้อัปเดตรันไทม์เป็นเวอร์ชันที่รองรับ

Workbox-webpack-plugin ต้องใช้ Webpack v4 ขึ้นไป

หากคุณใช้ workbox-webpack-plugin ให้อัปเดตการตั้งค่า webpack เพื่อใช้ webpack v4 เป็นอย่างน้อย

การยกเครื่องตัวเลือกของเครื่องมือสร้าง

ระบบไม่รองรับพารามิเตอร์การกำหนดค่า workbox-build, workbox-cli และ workbox-webpack-plugin จำนวนหนึ่งอีกต่อไป ตัวอย่างเช่น generateSW จะสร้างแพ็กเกจรันไทม์ Workbox ในพื้นที่ให้คุณเสมอ ดังนั้นตัวเลือก importWorkboxFrom จึงไม่มีความหมายอีกต่อไป

โปรดดูรายการตัวเลือกที่รองรับจากเอกสารประกอบของเครื่องมือที่เกี่ยวข้อง

นำ generateSWString ออกจาก Workbox-build

ระบบนำโหมด generateSWString ออกจาก workbox-build แล้ว เราคาดว่าผลกระทบนี้จะน้อยมาก เนื่องจาก workbox-webpack-plugin ใช้เป็นการภายในเป็นหลัก

การเปลี่ยนแปลงที่ไม่บังคับ

การใช้การนำเข้าโมดูล

แม้ว่าการเปลี่ยนแปลงนี้จะเป็น ก) ไม่บังคับ และ ข) ในทางเทคนิค ก็เป็นไปได้เมื่อใช้ Workbox v4 แต่การเปลี่ยนแปลงที่ยิ่งใหญ่ที่สุดที่เราคาดว่าจะเปลี่ยนไปใช้ v5 คือโมเดลที่คุณสร้าง Service Worker แบบกลุ่มของคุณเองด้วยการนำเข้าโมดูลของ Workbox แนวทางนี้เป็นทางเลือกในการเรียกใช้ importScripts('/path/to/workbox-sw.js') ที่ด้านบนของ Service Worker และการใช้ Workbox ผ่านเนมสเปซ workbox.*

หากคุณใช้เครื่องมือสร้างอย่างใดอย่างหนึ่ง (workbox-webpack-plugin, workbox-build, workbox-cli) ในโหมด "สร้าง SW" การเปลี่ยนแปลงนี้จะดำเนินการโดยอัตโนมัติ เครื่องมือทั้งหมดนี้จะแสดงผลเป็นแพ็กเกจรันไทม์ Workbox ที่กําหนดเองในเครื่องพร้อมกับโค้ดจริงที่จําเป็นสําหรับการใช้ตรรกะ Service Worker ในสถานการณ์นี้ จะไม่มีการใช้ workbox-sw หรือสําเนา CDN ของ Workbox อีกต่อไป รันไทม์ของ Workbox จะแบ่งออกเป็นไฟล์แยกต่างหากที่ควรทำให้ใช้งานได้ควบคู่กับ Service Worker (เมื่อตั้งค่าเป็น false ซึ่งเป็นค่าเริ่มต้น) หรือรวมในหน้าไปพร้อมกับตรรกะของ Service Worker (เมื่อตั้งค่าเป็น true) ทั้งนี้ขึ้นอยู่กับค่าของการกำหนดค่า inlineWorkboxRuntime

หากคุณใช้เครื่องมือสร้างใน "แทรกไฟล์ Manifest" หรือหากคุณไม่ได้ใช้เครื่องมือสร้างของ Workbox เลย คุณสามารถดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างแพ็กเกจรันไทม์ของ Workbox ของคุณเองได้ในคู่มือการใช้ Bundlers (webpack/Rollup) กับ Workbox ที่มีอยู่

เอกสารประกอบและตัวอย่างสำหรับ v5 เขียนขึ้นโดยสมมติว่าไวยากรณ์การนำเข้าโมดูล แต่จะยังรองรับเนมสเปซ workbox.* ใน Workbox v5 ต่อไป

การอ่านการตอบกลับที่แคชล่วงหน้า

นักพัฒนาซอฟต์แวร์บางรายต้องอ่านการตอบกลับที่แคชไว้ล่วงหน้าจากแคชโดยตรง แทนการใช้การตอบกลับผ่านเมธอด precacheAndRoute() โดยปริยาย รูปแบบทั่วไปใน v4 คือรับคีย์แคชเฉพาะสำหรับทรัพยากรที่แคชไว้ล่วงหน้าเวอร์ชันปัจจุบันก่อน จากนั้นส่งคีย์นั้นพร้อมกับชื่อแคชของแคชไว้ล่วงหน้าไปยัง caches.match() เพื่อรับ Response

เพื่อให้กระบวนการนี้ง่ายขึ้น workbox-precaching ใน v5 สนับสนุนเมธอดใหม่ที่เทียบเท่ากันคือ matchPrecache():

// v4:
import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cachedResponse = await caches.match(
  getCacheKeyForURL(`/somethingPrecached`),
  {
    cacheName: cacheNames.precache,
  }
);

// v5:
import {matchPrecache} from 'workbox-precaching';

const cachedResponse = await matchPrecache(`/somethingPrecached`);

การนำ TypeScript มาใช้

ในเวอร์ชัน 5 ไลบรารีรันไทม์ของ Workbox จะเขียนด้วย TypeScript แม้ว่าเราจะยังคงเผยแพร่โมดูลและแพ็กเกจ JavaScript ที่เปลี่ยนรูปแบบแล้วต่อไปเพื่อรองรับนักพัฒนาซอฟต์แวร์ที่ยังไม่ได้นำ TypeScript มาใช้งาน แต่หากคุณใช้ TypeScript คุณควรได้รับข้อมูลประเภทที่ถูกต้องและเป็นปัจจุบันโดยตรงจากโปรเจ็กต์ Workbox

ตัวอย่างการย้ายข้อมูล

การคอมมิตนี้แสดงให้เห็นการย้ายข้อมูลที่มีความซับซ้อนพอสมควร โดยมีการแสดงความคิดเห็นในบทสนทนา โดยใช้รายงานเพื่อรวม รันไทม์ของ Workbox ที่กำหนดเองในโปรแกรมทำงานของบริการสุดท้ายแทนการโหลดรันไทม์จาก CDN

แม้ว่าจะไม่ได้ครอบคลุมการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นทั้งหมด แต่นี่คือก่อนและหลังของการอัปเกรดไฟล์ Service Worker 1 ไฟล์จาก v4 เป็น v5 รวมถึงเปลี่ยนเป็น TypeScript

ขอความช่วยเหลือ

เราคาดว่าการย้ายข้อมูลส่วนใหญ่จะเป็นไปอย่างง่ายดาย หากคุณพบปัญหาที่ไม่ครอบคลุมอยู่ในคู่มือนี้ โปรดแจ้งให้เราทราบโดยการเปิดปัญหาบน GitHub