chrome.mimeHandler

תיאור

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

זמינות

בהמתנה

מניפסט

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

"mime_types_handler"

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

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

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

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

רישום handler

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

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

אחזור פרטי שידור

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

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

מעבר לטיפול המקורי

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

‫Chrome מאחסן את התגובה במאגר זמני בזמן שה-handler פועל. אם התגובה התקבלה במלואה כשמפעילים את השיטה הזו, 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.
}

דוגמאות

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

הדוגמה הבאה מופעלת בדף ה-handler שמוגדר במניפסט. הוא מאחזר את תוכן המסמך ועובר למציג המובנה של 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

מאפיינים

  • פעיל

    בוליאני

    האם ה-handler הזה פעיל עבור סוג ה-MIME הנתון.

StreamInfo

מאפיינים

  • מוטמע

    בוליאני

    הערך הוא True אם הטעינה מתבצעת בהקשר מוטמע (iframe/embed/object).

  • mimeType

    מחרוזת

    סוג ה-MIME של התוכן שיירט.

  • originalUrl

    מחרוזת

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

  • responseHeaders

    אובייקט

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

  • streamUrl

    מחרוזת

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

  • tabId

    number

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

Methods

abortAndFallbackToNativeHandler()

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

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

החזרות

  • Promise<void>

getMimeHandlerOptions()

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

קריאת האפשרויות שנשמרו עבור סוג MIME. אם לא נשמרו ערכי ברירת מחדל, הפונקציה מחזירה את ערכי ברירת המחדל (enabled=true).

פרמטרים

  • mimeType

    מחרוזת

    סוג ה-MIME שאפשרויות הקריאה שלו.

החזרות

  • ההבטחה נפתרה עם האפשרויות שנשמרו לסוג ה-MIME.

getStreamInfo()

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

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

החזרות

setMimeHandlerOptions()

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

הגדרת אפשרויות התצורה לסוג MIME ספציפי.

פרמטרים

  • mimeType

    מחרוזת

    סוג ה-MIME שרוצים להגדיר.

  • האפשרויות החדשות לשימוש.

החזרות

  • Promise<void>

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