browser.mimeHandler

תיאור

משתמשים ב-API של chrome.mimeHandler כדי לטפל בסטרימינג של סוגי MIME בתוספים של צד שלישי.

זמינות

‫Chrome מגרסה 151 ואילך

מניפסט

כדי להשתמש ב-API הזה, צריך להצהיר על המפתחות הבאים במניפסט.

"mime_types_handler"

מושגים ושימוש

בעבר, תוספי צד שלישי שמטפלים בסוגי מסמכים ספציפיים (כמו כלי צפייה בקובצי PDF) הסתמכו על יירוט של בקשות לאחזור מהרשת כדי לתפוס את הניווטים ולהפנות את המשתמשים לדף של התוסף. רישום כ-MIME handler מונע כמה מגבלות של הגישה הזו:

  • כתובת ה-URL המקורית נשארת בסרגל הכתובות במקום להיות מוחלפת בכתובת URL של chrome-extension://.
  • התוסף מאחזר את התגובה ש-Chrome כבר קיבל, במקום לשלוח בקשה שנייה לאחזור מהרשת. מסמכים שנשלחים באמצעות בקשות POST או מכתובות URL לשימוש חד-פעמי פועלים בצורה תקינה.
  • התוסף יכול לעבד מסמכים שנטענים בתוך רכיבי <embed>,‏ <object> או <iframe>.
  • קבצים מקומיים (כתובות URL מסוג file://) פועלים בלי שהמשתמש צריך להפעיל באופן ידני את האפשרות "התרת גישה לכתובות אתרים של קבצים" בהגדרות התוסף.

רכיבי handler של MIME חלים רק על מסמכים שתופסים מסגרת שלמה: ניווטים ברמה העליונה ומסמכים מוטמעים. הם אף פעם לא חלים על משאבי משנה מוטבעים (למשל, רכיבי <audio>, <img> או <video>).

רישום handler

כדי לרשום את התוסף כ-MIME handler, צריך להצהיר על המפתח "mime_types_handler" במניפסט. כל רשומה ממפה סוג 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>. אם משמיטים את המאפיין, ה-handler מקבל רק ניווטים ברמה העליונה. החל מגרסה 151 של Chrome,‏ application/pdf הוא סוג ה-MIME היחיד שזמין ל-handlers ציבוריים. אם מצהירים על סוג MIME שלא נתמך, מופיעה אזהרה לגבי ההתקנה.

אם יותר מתוסף אחד שהותקן נרשם לאותו סוג MIME, התוסף שהותקן לאחרונה מטפל בו. אם מסירים את התוסף הזה, ה-handler שהותקן קודם הופך שוב לפעיל.

אחזור מידע על מקור הנתונים

כשמשתמש פותח מסמך מסוג MIME רשום, Chrome טוען את דף ה-handler במקום את הכלי המובנה להצגת קבצים. בדף ה-handler, מפעילים את getStreamInfo() כדי לאחזר אובייקט StreamInfo. המידע הזה כולל את originalUrl שאליו המשתמש ניווט, את responseHeaders של ה-HTTP, אם המסמך נטען בהקשר של embedded, ואת streamUrl שאפשר להשתמש בו כדי לאחזר את תוכן המסמך.

אפשר לאחזר את streamUrl פעם אחת בלבד, ורק מהמקור של התוסף. חשוב לקרוא את התשובה במלואה לפני שמעבדים אותה. אחזור שני של אותו streamUrl ייכשל. כדאי להשתמש ב-originalUrl כשמציגים את המיקום או הכותרת של המסמך, ולא כדי לאחזר את התוכן, כי יכול להיות שלא ניתן לחזור על הבקשה המקורית.

חזרה ל-handler המקורי

יכול להיות שה-handler ייתקל במסמכים שהוא לא יכול לעבד, כמו קבצים פגומים או קבצים שמוגנים בסיסמה. קוראים לפונקציה abortAndFallbackToNativeHandler() כדי להפסיק את הטיפול במסמך ולהחזיר אותו לכלי המובנה לצפייה ב-Chrome, במקום להשאיר את המשתמש בדף לא תקין. ‫Chrome פורק את דף ה-handler כחלק מהחזרה למצב קודם. לא פועל קוד אחרי הקריאה הזו.

‫Chrome שומר את התגובה במאגר נתונים זמני בזמן שה-handler פועל. אם התגובה התקבלה במלואה כשאתם קוראים לשיטה הזו, Chrome מציג את ה-viewer המובנה מהעותק שנשמר במאגר הנתונים הזמני בלי בקשה חדשה לאחזור מהרשת. אחרת, Chrome טוען מחדש את המסמך מהרשת, וייתכן שהפעולה תיכשל במסמכים שנשלחו באמצעות POST או מכתובות URL לשימוש חד-פעמי. צריך לאחזר את הסטרימינג במלואו לפני שמחליטים אם אפשר לעבד אותו. אחרי שהאחזור של streamUrl יושלם, ל-Chrome תהיה התגובה המלאה.

טיפול בזמינות של ה-API

בגרסאות של Chrome לפני Chrome 151, תוסף שמצהיר על "mime_types_handler" עדיין מותקן ופועל, אבל הוא לא רשום כ-handler ו-browser.mimeHandler לא מוגדר. תוספים שעוברים מהתכונה "יירוט בקשות לאחזור מהרשת" יכולים לבדוק אם ה-API קיים בזמן ההפעלה, ולהמשיך להשתמש בגישה הקיימת כגיבוי:

service-worker.js:

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

דוגמאות

איך מטפלים בשידור

הדוגמה הבאה פועלת בדף ה-handler שמוצהר במניפסט. הוא מאחזר את תוכן המסמך, ואם העיבוד נכשל, הוא חוזר למציג המובנה של Chrome:

viewer.js:

async function loadDocument() {
  const streamInfo = await browser.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.
    browser.mimeHandler.abortAndFallbackToNativeHandler();
  }
}

loadDocument();

המשתמשים יכולים להחליף את הטיפול

האפשרויות של ה-handler נשמרות לפי סוג MIME. בדוגמה הבאה נעשה שימוש ב-getMimeHandlerOptions() וב-setMimeHandlerOptions() כדי לאפשר למשתמשים להשבית את הטיפול בדף האפשרויות, בלי להסיר את התוסף. כשהטיפול מושבת, מסמכים מהסוג הזה לא מנותבים יותר לתוסף.

options.js:

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

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

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

initOptions();

סוגים

MimeHandlerOptions

מאפיינים

  • canEmbed

    בוליאני אופציונלי

    ‫Chrome מגרסה 157 ואילך

    האם אפשר להשתמש ב-handler הזה לטעינות מוטמעות (iframe, ‏ embed, ‏ object). ברירת המחדל היא הערך של can_embed ברשומת המניפסט. אין השפעה כשהערך של enabled הוא False.

  • פעיל

    בוליאני אופציונלי

    אם ה-handler הזה מופעל. ברירת המחדל היא הערך של enabled ברשומת המניפסט.

StreamInfo

מאפיינים

  • מוטמע

    בוליאני

    ‫True אם נטען בהקשר מוטמע (iframe/embed/object).

  • mimeType

    מחרוזת

    סוג ה-MIME של התוכן שנקלט.

  • originalUrl

    מחרוזת

    כתובת ה-URL המקורית שהמשתמש נכנס אליה.

  • responseHeaders

    אובייקט

    כותרות של תגובות HTTP כצמדי מפתח/ערך.

  • streamUrl

    מחרוזת

    כתובת ה-URL שממנה מאחזרים את נתוני השידור.

  • tabId

    number

    מזהה הכרטיסייה שמכילה את המסמך.

Methods

abortAndFallbackToNativeHandler()

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

מבטל את הטיפול בסטרימינג הנוכחי ומעביר את התוכן ל-handler המקורי של סוכן המשתמש. אחרי הקריאה הזו, מסגרת התוסף תוסר. המתקשרים לא צריכים לצפות להמשך ביצוע.

החזרות

  • Promise<void>

getMimeHandlerOptions()

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

קורא את האפשרויות של סוג MIME. כל איבר הוא הערך שהתוסף הגדיר, או הערך של הרשומה במניפסט אם התוסף לא הגדיר אותו.

פרמטרים

  • mimeType

    מחרוזת

    סוג ה-MIME שהאפשרויות שלו ייקראו. הוא חייב להיות סוג MIME שהתוסף מטפל בו באמצעות mime_types_handler.

החזרות

  • ה-Promise נפתר עם האפשרויות של סוג ה-MIME.

getStreamInfo()

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

אחזור מידע על הסטרימינג בהקשר הנוכחי של ה-MIME handler. צריך להפעיל את הפונקציה מתוך דף של תוסף לטיפול ב-MIME.

החזרות

setMimeHandlerOptions()

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

הגדרת אפשרויות לסוג MIME מסוים. אם התוסף פועל במצב פרטי מפוצל, האפשרויות שמוגדרות במצב פרטי חלות רק על המצב הפרטי ונמשכות עד לסיום השימוש הפרטי. אפשרויות שלא מוגדרות במצב פרטי פועלות לפי הערכים שמוגדרים מחוץ למצב פרטי.

פרמטרים

  • mimeType

    מחרוזת

    סוג ה-MIME שרוצים להגדיר. הוא חייב להיות סוג MIME שהתוסף מטפל בו באמצעות mime_types_handler.

  • אפשרויות

    MimeHandlerOptions

    האפשרויות לשינוי.

החזרות

  • Promise<void>

    ההבטחה (Promise) מתקיימת כשההגדרה נקבעת.