chrome.mimeHandler

คำอธิบาย

ใช้ chrome.mimeHandler API เพื่อจัดการสตรีมประเภท MIME ในส่วนขยายของบุคคลที่สาม

ความพร้อมใช้งาน

รอดำเนินการ

ไฟล์ Manifest

ต้องประกาศคีย์ต่อไปนี้ในไฟล์ Manifest เพื่อใช้ API นี้

"mime_types_handler"

แนวคิดและการใช้งาน

ในอดีต ส่วนขยายของบุคคลที่สามที่จัดการเอกสารบางประเภท (เช่น โปรแกรมดู PDF) อาศัยการสกัดกั้นคำขอเครือข่ายเพื่อตรวจหาการนำทางและเปลี่ยนเส้นทางผู้ใช้ไปยังหน้าส่วนขยาย การลงทะเบียนเป็นตัวแฮนเดิล MIME จะช่วยหลีกเลี่ยงข้อจำกัดหลายประการของวิธีการดังกล่าว

  • URL เดิมจะยังคงอยู่ในแถบที่อยู่แทนที่จะถูกแทนที่ด้วย URL ของ chrome-extension://
  • ส่วนขยายจะดึงข้อมูลการตอบกลับที่ Chrome ได้รับแล้วแทนที่จะส่งคำขอเครือข่ายครั้งที่ 2 เอกสารที่ส่งโดยคำขอ POST หรือจาก URL แบบใช้ครั้งเดียวจะทำงานอย่างถูกต้อง
  • ส่วนขยายของคุณสามารถแสดงผลเอกสารที่โหลดภายในองค์ประกอบ <embed>, <object> หรือ <iframe>
  • ไฟล์ในเครื่อง (file:// URL) จะทำงานได้โดยไม่ต้องให้ผู้ใช้เปิดใช้ "อนุญาตให้เข้าถึง URL ของไฟล์" ในการตั้งค่าของส่วนขยายด้วยตนเอง

ตัวแฮนเดิล MIME จะใช้ได้กับเอกสารที่ครอบครองทั้งเฟรมเท่านั้น ได้แก่ การนำทางระดับบนสุดและเอกสารที่ฝัง โดยจะไม่มีผลกับทรัพยากรย่อยแบบอินไลน์ (เช่น องค์ประกอบ <audio>, <img> หรือ <video>)

ลงทะเบียนตัวแฮนเดิล

หากต้องการลงทะเบียนส่วนขยายเป็นตัวแฮนเดิล MIME ให้ประกาศคีย์ "mime_types_handler" ใน manifest แต่ละรายการจะแมปประเภท MIME กับหน้าส่วนขยายที่แสดงผลประเภท MIME นั้น

manifest.json:

{
  "name": "My PDF Viewer",
  ...
  "mime_types_handler": {
    "application/pdf": {
      "handler_url": "viewer.html",
      "can_embed": true
    }
  },
  ...
}

ตั้งค่า "can_embed" เป็น true เพื่อจัดการเอกสารที่ฝังอยู่ในองค์ประกอบ <embed>, <object> หรือ <iframe> ด้วย หากไม่ระบุ ตัวแฮนเดิลจะได้รับการนำทางระดับบนสุดเท่านั้น ตั้งแต่ Chrome 151 เป็นต้นไป application/pdf จะเป็นประเภท MIME เดียวที่พร้อมใช้งานสำหรับตัวแฮนเดิลสาธารณะ การประกาศประเภท MIME ที่ไม่รองรับจะทำให้เกิดคำเตือนการติดตั้ง

หากส่วนขยายที่ติดตั้งมากกว่า 1 รายการลงทะเบียนสำหรับ MIME ประเภทเดียวกัน ส่วนขยายที่ติดตั้งล่าสุดจะเป็นตัวจัดการ หากถอนการติดตั้งส่วนขยายดังกล่าว ตัวแฮนเดิลที่ติดตั้งไว้ก่อนหน้านี้จะกลับมาทำงานอีกครั้ง

ดึงข้อมูลสตรีม

เมื่อผู้ใช้เปิดเอกสารที่มีประเภท MIME ที่ลงทะเบียนไว้ Chrome จะโหลดหน้าตัวแฮนเดิลแทนโปรแกรมดูในตัว จากหน้าตัวแฮนเดิล ให้เรียกใช้ getStreamInfo() เพื่อดึงข้อมูลออบเจ็กต์ StreamInfo ซึ่งรวมถึง originalUrl ที่ผู้ใช้ไปยัง responseHeaders HTTP, ไม่ว่าเอกสารจะโหลดในบริบท embedded หรือไม่ และ streamUrl ที่ใช้ดึงเนื้อหาของเอกสารได้

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

กลับไปใช้ตัวแฮนเดิลเนทีฟ

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

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

จัดการความพร้อมใช้งานของ API

ใน Chrome เวอร์ชันก่อน Chrome 151 ส่วนขยายที่ประกาศ "mime_types_handler" จะยังคงติดตั้งและทำงานได้ แต่จะไม่ได้รับการลงทะเบียนเป็นตัวแฮนเดิลและ chrome.mimeHandler จะไม่ได้รับการกำหนด ส่วนขยายที่ย้ายข้อมูลจากการสกัดกั้นคำขอเครือข่ายสามารถตรวจสอบ API เมื่อเริ่มต้นและใช้วิธีการที่มีอยู่เป็นข้อมูลสำรองได้โดยทำดังนี้

service-worker.js:

if (chrome.mimeHandler) {
  // Chrome routes registered MIME types to the handler page
  // declared in the manifest.
} else {
  // Fall back to network request interception.
}

ตัวอย่าง

จัดการสตรีม

ตัวอย่างต่อไปนี้จะทำงานในหน้าตัวแฮนเดิลที่ประกาศไว้ในไฟล์ Manifest โดยจะดึงเนื้อหาของเอกสารและกลับไปใช้โปรแกรมดูในตัวของ Chrome หากการแสดงผลล้มเหลว

viewer.js:

async function loadDocument() {
  const streamInfo = await chrome.mimeHandler.getStreamInfo();

  // The `embedded` property is true if the document is loaded
  // within an <embed>, <object>, or <iframe> element.
  if (streamInfo.embedded) {
    // Adjust the UI (e.g., hide the top navigation bar).
    document.body.classList.add('embedded-view');
  }

  // Fetch the content using the provided streamUrl. The stream can
  // only be consumed once, so read it fully before continuing.
  const response = await fetch(streamInfo.streamUrl);
  const data = await response.arrayBuffer();

  try {
    // Render the document (e.g., using PDF.js).
    await renderDocument(data);
  } catch (e) {
    // Can't render this document. Fall back to Chrome's built-in
    // viewer; the page unloads and no code runs after this call.
    chrome.mimeHandler.abortAndFallbackToNativeHandler();
  }
}

loadDocument();

อนุญาตให้ผู้ใช้เปิด/ปิดการจัดการ

ระบบจะจัดเก็บตัวเลือกแฮนเดิลเลอร์ตามประเภท MIME ตัวอย่างต่อไปนี้ใช้ getMimeHandlerOptions() และ setMimeHandlerOptions() เพื่อให้ผู้ใช้ปิดการจัดการจากหน้าตัวเลือกได้โดยไม่ต้องถอนการติดตั้งส่วนขยาย ในขณะที่ปิดใช้การจัดการ ระบบจะไม่ส่งเอกสารประเภทดังกล่าวไปยังส่วนขยายของคุณอีกต่อไป

options.js:

const checkbox = document.querySelector('#handle-pdfs');

async function initOptions() {
  const options =
      await chrome.mimeHandler.getMimeHandlerOptions('application/pdf');
  // Handling is enabled unless it has been explicitly disabled.
  checkbox.checked = options.enabled !== false;
}

checkbox.addEventListener('change', async () => {
  await chrome.mimeHandler.setMimeHandlerOptions('application/pdf', {
    enabled: checkbox.checked
  });
});

initOptions();

ประเภท

MimeHandlerOptions

พร็อพเพอร์ตี้

  • เปิดใช้อยู่

    บูลีน

    ตัวแฮนเดิลนี้ใช้งานได้สำหรับประเภท MIME ที่ระบุหรือไม่

StreamInfo

พร็อพเพอร์ตี้

  • ฝัง

    บูลีน

    เป็นจริงหากโหลดในบริบทที่ฝัง (iframe/embed/object)

  • mimeType

    สตริง

    ประเภท MIME ของเนื้อหาที่สกัดกั้น

  • originalUrl

    สตริง

    URL เดิมที่ผู้ใช้ไปยัง

  • responseHeaders

    ออบเจ็กต์

    ส่วนหัวการตอบกลับ HTTP เป็นคู่คีย์-ค่า

  • streamUrl

    สตริง

    URL ที่จะดึงข้อมูลสตรีมจาก

  • tabId

    ตัวเลข

    รหัสแท็บที่มีเอกสาร

เมธอด

abortAndFallbackToNativeHandler()

chrome.mimeHandler.abortAndFallbackToNativeHandler(): Promise<void>

ยกเลิกการจัดการสตรีมปัจจุบันและส่งต่อเนื้อหาไปยังตัวแฮนเดิลเนทีฟของ User Agent หลังจากเรียกใช้ฟังก์ชันนี้แล้ว เฟรมส่วนขยายจะถูกปิด ผู้เรียกใช้ไม่ควรคาดหวังว่าจะมีการดำเนินการเพิ่มเติม

การคืนสินค้า

  • Promise<void>

getMimeHandlerOptions()

chrome.mimeHandler.getMimeHandlerOptions(
  mimeType: string,
): Promise<MimeHandlerOptions>

อ่านตัวเลือกที่บันทึกไว้สำหรับประเภท MIME แสดงค่าเริ่มต้น (enabled=true) หากไม่มีการจัดเก็บค่าใดไว้

พารามิเตอร์

  • mimeType

    สตริง

    ประเภท MIME ที่มีตัวเลือกให้อ่าน

การคืนสินค้า

  • Promise ที่แก้ไขแล้วพร้อมตัวเลือกที่คงอยู่สำหรับประเภท MIME

getStreamInfo()

chrome.mimeHandler.getStreamInfo(): Promise<StreamInfo>

ดึงข้อมูลสตรีมสำหรับบริบทตัวแฮนเดิล MIME ปัจจุบัน ต้องเรียกใช้จากภายในหน้าส่วนขยายตัวแฮนเดิล MIME

การคืนสินค้า

setMimeHandlerOptions()

chrome.mimeHandler.setMimeHandlerOptions(
  mimeType: string,
  options: MimeHandlerOptions,
): Promise<void>

ตั้งค่าตัวเลือกการกำหนดค่าสำหรับประเภท MIME ที่ระบุ

พารามิเตอร์

  • mimeType

    สตริง

    ประเภท MIME ที่จะกำหนดค่า

  • ตัวเลือก

    MimeHandlerOptions

    ตัวเลือกใหม่ในการใช้งาน

การคืนสินค้า

  • Promise<void>

    Promise จะได้รับการแก้ไขเมื่อตั้งค่าการกำหนดค่าแล้ว