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

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

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

workbox-precaching

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

นักพัฒนาซอฟต์แวร์ที่ใช้การแคชล่วงหน้าผ่าน workbox.precaching.precacheAndRoute() ซึ่งเป็น Use Case ที่พบบ่อยที่สุด ไม่จำเป็นต้องเปลี่ยนแปลงการกำหนดค่า 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() ให้กับ Service Worker ได้โดยตรง หรือตั้งค่าตัวเลือก cleanupOutdatedCaches: true ใหม่หากใช้เครื่องมือบิลด์ในโหมด GenerateSW เนื่องจากตรรกะการล้างแคชจะทำงานตามรูปแบบการตั้งชื่อแคชเพื่อค้นหาแคชที่แคชไว้ล่วงหน้าเก่าๆ และเนื่องจากนักพัฒนาแอปมีตัวเลือกในการลบล้างรูปแบบเหล่านั้น เราจึงเลือกที่จะปลอดภัยไว้ก่อนและไม่ได้เปิดใช้ฟีเจอร์นี้โดยค่าเริ่มต้น

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

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

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

workbox-strategies

การสร้างอินสแตนซ์ของตัวแฮนเดิลใน 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 แต่การใช้ไวยากรณ์ดังกล่าวจะบันทึกคำเตือน และเราขอแนะนำให้นักพัฒนาแอปย้ายข้อมูลก่อนที่จะนำการรองรับออกจากเวอร์ชัน 5 ในอนาคต

Workbox-ซิงค์พื้นหลัง

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

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

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

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

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

ใน v4 ระบบได้นำการเรียกกลับเหล่านี้ออกแล้วแทนที่ด้วยการเรียกกลับ 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 ภายใน) จึงมีการเปลี่ยนแปลงในลักษณะเดียวกัน

workbox-expiration

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

workbox-broadcast-update

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

workbox-core

ใน Workbox v3 คุณสามารถควบคุมระดับการพิมพ์รายละเอียดของบันทึกผ่านเมธอด workbox.core.setLogLevel() ซึ่งคุณจะต้องส่งค่าใดค่าหนึ่งใน workbox.core.LOG_LEVELS enum นอกจากนี้ คุณยังอ่านระดับบันทึกปัจจุบันผ่าน 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" ของชื่อตัวเลือกเหล่านั้นจะยังคงใช้งานได้ในเวอร์ชัน 4 แต่ระบบจะแสดงข้อความเตือน เราขอแนะนำให้นักพัฒนาแอปย้ายข้อมูลล่วงหน้าก่อนที่จะมีการเปิดตัวเวอร์ชัน 5

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

workbox-window

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

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

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

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

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

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