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

คู่มือนี้มุ่งเน้นที่การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบของ Workbox v4 พร้อมด้วยตัวอย่างการเปลี่ยนแปลงที่คุณจำเป็นต้องทำเมื่ออัปเกรดจาก Workbox v3

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

การแคชพื้นที่ทำงานล่วงหน้า

รูปแบบการตั้งชื่อสำหรับรายการที่แคชไว้ล่วงหน้าได้รับการอัปเดตแล้ว ในตอนนี้ สำหรับรายการที่ URL ต้องมีข้อมูลการแก้ไข (เช่น รายการที่มีฟิลด์ revision ใน ไฟล์ Manifest ล่วงหน้า) ข้อมูลการกำหนดเวอร์ชันจะได้รับการจัดเก็บเป็นส่วนหนึ่งของคีย์แคชในพารามิเตอร์การค้นหา URL พิเศษ __WB_REVISION__ ที่ต่อท้าย URL เดิม (ก่อนหน้านี้ ข้อมูลนี้จะได้รับการจัดเก็บแยกต่างหากจากคีย์แคช โดยใช้ IndexedDB)

นักพัฒนาซอฟต์แวร์ที่ใช้ประโยชน์จากการแคชล่วงหน้าผ่าน workbox.precaching.precacheAndRoute() ซึ่งเป็นกรณีการใช้งานที่พบบ่อยที่สุด ไม่จำเป็นต้องทำการเปลี่ยนแปลงใดๆ กับการกำหนดค่า Service Worker เมื่ออัปเกรดเป็น Workbox v4 เนื้อหาที่แคชไว้ของผู้ใช้จะเปลี่ยนไปใช้รูปแบบคีย์แคชใหม่โดยอัตโนมัติ และจากนี้ไป ทรัพยากรที่แคชล่วงหน้าไว้จะยังคงใช้งานได้เหมือนเดิม

การใช้คีย์แคชโดยตรง

นักพัฒนาแอปบางรายอาจจำเป็นต้องเข้าถึงรายการแคชล่วงหน้าโดยตรงนอกบริบทของ workbox.precaching.precacheAndRoute() ตัวอย่างเช่น คุณอาจแคชรูปภาพล่วงหน้าที่จะใช้เป็นการตอบสนอง "สำรอง" เมื่อดึงข้อมูลรูปภาพจริงจากเครือข่ายไม่ได้

หากคุณใช้เนื้อหาที่แคชล่วงหน้าด้วยวิธีนี้ เริ่มตั้งแต่ Workbox v4 คุณจะต้องดำเนินการขั้นตอนเพิ่มเติมเพื่อแปล URL เดิมเป็นคีย์แคชที่เกี่ยวข้อง ซึ่งสามารถใช้อ่านรายการที่แคชไว้ได้ โดยโทรหา workbox.precaching.getCacheKeyForURL(originURL)

ตัวอย่างเช่น หากคุณทราบว่า 'fallback.png' มีการแคชล่วงหน้าไว้

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...
  }
});

การล้างข้อมูลเก่าที่เก็บไว้ก่อน

การเปลี่ยนแปลงการแคชล่วงหน้าใน Workbox v4 จะทำให้ไม่สามารถใช้แคชล่วงหน้าแบบเก่าซึ่งสร้างโดย Workbox เวอร์ชันก่อนหน้าได้ โดยค่าเริ่มต้น ระบบจะปล่อยทรัพยากรเหล่านั้นไว้อย่างที่เป็นอยู่ และถ้าคุณอัปเกรดจาก Workbox v3 เป็น Workbox v4 จะมีทรัพยากรทั้งหมดที่แคชล่วงหน้าไว้ 2 ชุด

หากไม่ต้องการให้เป็นเช่นนั้น คุณอาจเพิ่มการเรียกใช้ workbox.precaching.cleanupOutdatedCaches() ไปยังโปรแกรมทำงานของบริการโดยตรง หรือตั้งค่าตัวเลือก cleanupOutdatedCaches: true ใหม่หากใช้เครื่องมือบิลด์ในโหมด GenerateSW เนื่องจากตรรกะการล้างแคชจะทำงานตามแบบแผนการตั้งชื่อแคชเพื่อค้นหาแคชล่วงหน้าที่เก่ากว่า และเนื่องจากนักพัฒนาซอฟต์แวร์มีตัวเลือกในการลบล้างแบบแผนเหล่านั้น เราจึงผิดพลาดทางด้านความปลอดภัยและไม่ได้เปิดใช้งานสิ่งนี้โดยค่าเริ่มต้น

เราขอแนะนำให้นักพัฒนาแอปที่พบปัญหาการใช้งานฟีเจอร์นี้ เช่น ผลบวกลวงจากการลบ โปรดแจ้งให้เราทราบ

การใช้อักษรตัวพิมพ์ใหญ่ของพารามิเตอร์

มีการเปลี่ยนชื่อพารามิเตอร์ที่ไม่บังคับ 2 รายการที่ส่งไปยัง workbox.precaching.precacheAndRoute() และ workbox.precaching.addRoute() เพื่อให้รูปแบบการใช้อักษรตัวพิมพ์ใหญ่โดยรวมของเราเป็นมาตรฐานเดียวกัน ignoreUrlParametersMatching เปลี่ยนชื่อเป็น ignoreURLParametersMatching และ cleanUrls เปลี่ยนเป็น cleanURLs

กลยุทธ์กล่องงาน

การสร้างอินสแตนซ์ของตัวแฮนเดิลใน workbox-strategies ทำได้ 2 วิธีซึ่งคล้ายๆ กันโดยประมาณ เรากำลังจะเลิกใช้งานวิธีการจากโรงงานเพื่อเรียกใช้ตัวสร้างกลยุทธ์อย่างชัดเจน

// 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({...});

แม้ว่าไวยากรณ์เมธอดเริ่มต้นจะยังคงทํางานต่อไปในเวอร์ชัน 4 แต่การใช้ไวยากรณ์ดังกล่าวจะบันทึกคําเตือน และเราขอแนะนําให้นักพัฒนาแอปย้ายข้อมูลล่วงหน้าสําหรับการยกเลิกการรองรับในรุ่น v5 ที่จะออกในอนาคต

Workbox-background-sync

เราได้เขียนคลาส workbox.backgroundSync.Queue ใหม่เพื่อให้นักพัฒนาแอปมีความยืดหยุ่นและควบคุมวิธีการเพิ่มคำขอในคิวและเล่นซ้ำได้มากขึ้น

ใน v3 คลาส Queue มีวิธีการเดียวในการเพิ่มคำขอลงในคิว (เมธอด addRequest()) แต่ไม่มีวิธีแก้ไขคิวหรือนำคำขอออก

ใน v4 มีการนำเมธอด addRequests() ออก และเพิ่มเมธอดที่คล้ายกับอาร์เรย์ต่อไปนี้

• pushRequest()
• popRequest()
• shiftRequest()
• unshiftRequest()

ในเวอร์ชัน 3 คลาส Queue ยังยอมรับโค้ดเรียกกลับหลายรายการที่ทำให้คุณสังเกตได้เมื่อมีการเล่นคำขอซ้ำ (requestWillEnqueue, requestWillReplay, queueDidReplay) แต่นักพัฒนาแอปส่วนใหญ่พบว่านอกเหนือจากการสังเกตแล้ว พวกเขายังต้องการควบคุมวิธีการเล่นคิวซ้ำ ซึ่งรวมถึงความสามารถในการแก้ไขแบบไดนามิก เรียงลำดับใหม่ หรือแม้แต่ยกเลิกคำขอทีละรายการ

ในเวอร์ชัน 4 ระบบได้นำโค้ดเรียกกลับเหล่านี้ออกแล้วเพื่อเปลี่ยนไปใช้โค้ดเรียกกลับ onSync เดียว ซึ่งจะมีการเรียกใช้ทุกครั้งที่เบราว์เซอร์พยายามเล่นซ้ำ โดยค่าเริ่มต้น โค้ดเรียกกลับ onSync จะเรียกใช้ replayRequests() แต่หากต้องการควบคุมการเล่นซ้ำมากขึ้น คุณสามารถใช้เมธอดที่คล้ายกับอาร์เรย์ในรายการด้านบนเพื่อเล่นคิวซ้ำได้ตามต้องการ

ตัวอย่างตรรกะการเล่นซ้ำที่กำหนดเอง

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!');
  },
});

ในทำนองเดียวกัน คลาส workbox.backgroundSync.Plugin ยอมรับอาร์กิวเมนต์เดียวกับคลาส Queue (เนื่องจากมีการสร้างอินสแตนซ์ Queue เป็นการภายใน) จึงมีการเปลี่ยนแปลงในลักษณะเดียวกัน

การหมดอายุของกล่องงาน

มีการเปลี่ยนชื่อแพ็กเกจ npm เป็น workbox-expiration ซึ่งตรงกับรูปแบบการตั้งชื่อที่ใช้สำหรับโมดูลอื่นๆ แพ็กเกจนี้มีฟังก์ชันการทำงานเทียบเท่ากับแพ็กเกจ workbox-cache-expiration เก่าที่ตอนนี้เลิกใช้งานแล้ว

อัปเดตเวิร์กบ็อกซ์-บรอดแคสต์

มีการเปลี่ยนชื่อแพ็กเกจ npm เป็น workbox-broadcast-update ซึ่งตรงกับรูปแบบการตั้งชื่อที่ใช้สำหรับโมดูลอื่นๆ แพ็กเกจนี้มีฟังก์ชันการทำงานเทียบเท่ากับแพ็กเกจ workbox-broadcast-cache-update เก่าที่ตอนนี้เลิกใช้งานแล้ว

แกนงาน

ใน Workbox v3 การควบคุมรายละเอียดของระดับการบันทึกจะควบคุมผ่านเมธอด workbox.core.setLogLevel() ซึ่งคุณจะส่งผ่านค่าใดค่าหนึ่งใน enum ของ workbox.core.LOG_LEVELS นอกจากนี้ คุณยังสามารถอ่านระดับการบันทึกปัจจุบันผ่านทาง workbox.core.logLevel ได้

ใน Workbox v4 ระบบได้นำฟีเจอร์ทั้งหมดนี้ออกไปเนื่องจากเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์สมัยใหม่ทั้งหมดมาพร้อมกับความสามารถในการกรองบันทึกที่สมบูรณ์ (ดูการกรองเอาต์พุตของคอนโซลสำหรับเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome)

Workbox-sw

มีการย้าย 2 วิธีที่เคยแสดงโดยตรงในเนมสเปซ workbox (ซึ่งสอดคล้องกับโมดูล workbox-sw) ไปยัง workbox.core แทน workbox.skipWaiting() ได้เปลี่ยนเป็น workbox.core.skipWaiting() และในทำนองเดียวกัน workbox.clientsClaim() ได้กลายเป็น workbox.core.clientsClaim()

การกำหนดค่าเครื่องมือสำหรับบิลด์

มีการเปลี่ยนแปลงการตั้งชื่อตัวเลือกบางอย่างที่สามารถส่งผ่านไปยัง workbox-cli, workbox-build หรือ workbox-webpack-plugin เมื่อใดก็ตามที่มีการใช้ "Url" ในชื่อตัวเลือก ระบบจะเลิกใช้งาน "URL" แทน ซึ่งหมายความว่าเราแนะนำให้ใช้ชื่อตัวเลือกต่อไปนี้

• dontCacheBustURLsMatching
• ignoreURLParametersMatching
• modifyURLPrefix
• templatedURLs

รูปแบบ "Url" ของชื่อตัวเลือกเหล่านั้นยังคงใช้งานได้ใน v4 แต่จะส่งผลให้มีข้อความเตือน เราขอแนะนำให้นักพัฒนาแอปย้ายข้อมูลล่วงหน้าก่อนที่จะเปิดตัว v5

ฟังก์ชันการทำงานใหม่

หน้าต่างกล่องงาน

โมดูล workbox-window ใหม่จะช่วยลดความซับซ้อนของขั้นตอนการลงทะเบียน Service Worker และการตรวจหาอัปเดต และให้วิธีการมาตรฐานในการสื่อสารระหว่างโค้ดที่กำลังทำงานใน Service Worker และโค้ดที่เรียกใช้ในบริบท window ของเว็บแอป

แม้ว่าการใช้ workbox-window จะไม่บังคับ แต่เราก็หวังว่านักพัฒนาแอปจะได้รับประโยชน์ และพิจารณาย้ายตรรกะที่เขียนด้วยลายมือบางส่วนไปใช้ในสถานการณ์ที่เหมาะสม ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ workbox-window ได้ในคู่มือของโมดูล

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

คุณสามารถดูตัวอย่างการย้ายข้อมูลในชีวิตจริงจาก Workbox v3 ไปยัง v4 ได้ในคำขอพุลนี้

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

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