browser.mimeHandler

ब्यौरा

तीसरे पक्ष के एक्सटेंशन में एमआईएमई टाइप की स्ट्रीम को मैनेज करने के लिए, chrome.mimeHandler एपीआई का इस्तेमाल करें.

उपलब्धता

Chrome 151 या इसके बाद का वर्शन

मेनिफ़ेस्ट

इस एपीआई का इस्तेमाल करने के लिए, मेनिफ़ेस्ट में इन कुंजियों का एलान करना ज़रूरी है.

"mime_types_handler"

कॉन्सेप्ट और इस्तेमाल

पहले, खास तरह के दस्तावेज़ों (जैसे, PDF व्यूअर) को मैनेज करने वाले तीसरे पक्ष के एक्सटेंशन, नेविगेशन को पकड़ने और उपयोगकर्ताओं को एक्सटेंशन पेज पर रीडायरेक्ट करने के लिए, नेटवर्क के अनुरोध को इंटरसेप्ट करने पर निर्भर थे. एमआईएमई हैंडलर के तौर पर रजिस्टर करने से, उस तरीके की कई सीमाओं से बचा जा सकता है:

• पता बार में ऑरिजिन यूआरएल ही रहता है. इसे chrome-extension:// यूआरएल से नहीं बदला जाता.
• आपका एक्सटेंशन, Chrome को पहले से मिले जवाब को फ़ेच करता है. इसके लिए, वह नेटवर्क का दूसरा अनुरोध नहीं करता. पोस्ट अनुरोधों या एक बार इस्तेमाल होने वाले यूआरएल से डिलीवर किए गए दस्तावेज़ सही तरीके से काम करते हैं.
• आपका एक्सटेंशन, <embed>, <object> या <iframe> एलिमेंट में लोड किए गए दस्तावेज़ों को रेंडर कर सकता है.
• लोकल फ़ाइलें (file:// यूआरएल) तब भी काम करती हैं, जब उपयोगकर्ता एक्सटेंशन की सेटिंग में जाकर, "फ़ाइल के यूआरएल तक ऐक्सेस दें" को मैन्युअल तरीके से चालू नहीं करता.

एमआईएमई हैंडलर सिर्फ़ उन दस्तावेज़ों पर लागू होते हैं जो पूरे फ़्रेम में दिखते हैं: टॉप-लेवल नेविगेशन और एम्बेड किए गए दस्तावेज़. ये इनलाइन सब-रिसोर्स पर कभी लागू नहीं होते. जैसे, <audio>, <img> या <video> एलिमेंट.

हैंडलर को रजिस्टर करना

अपने एक्सटेंशन को एमआईएमई हैंडलर के तौर पर रजिस्टर करने के लिए, मेनिफ़ेस्ट में "mime_types_handler" कुंजी का एलान करें. हर एंट्री, एमआईएमई टाइप को एक्सटेंशन पेज पर मैप करती है, जो उसे रेंडर करता है:

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 एमआईएमई टाइप उपलब्ध है. अगर कोई ऐसा एमआईएमई टाइप इस्तेमाल किया जाता है जो काम नहीं करता, तो इंस्टॉल करने से जुड़ी चेतावनी दिखती है.

अगर इंस्टॉल किए गए एक से ज़्यादा एक्सटेंशन, एक ही एमआईएमई टाइप के लिए रजिस्टर होते हैं, तो हाल ही में इंस्टॉल किया गया एक्सटेंशन उसे मैनेज करता है. अगर उस एक्सटेंशन को अनइंस्टॉल कर दिया जाता है, तो पहले से इंस्टॉल किया गया हैंडलर फिर से चालू हो जाता है.

स्ट्रीम की जानकारी फिर से पाना

जब कोई उपयोगकर्ता, रजिस्टर किए गए एमआईएमई टाइप का दस्तावेज़ खोलता है, तो Chrome अपने पहले से मौजूद व्यूअर के बजाय, आपके हैंडलर पेज को लोड करता है. हैंडलर पेज से, StreamInfo ऑब्जेक्ट को वापस पाने के लिए, getStreamInfo() को कॉल करें. इसमें वह originalUrl शामिल है जिस पर उपयोगकर्ता ने नेविगेट किया है, एचटीटीपी responseHeaders, दस्तावेज़ को embedded कॉन्टेक्स्ट में लोड किया गया है या नहीं, और एक streamUrl जिसका इस्तेमाल दस्तावेज़ का कॉन्टेंट फ़ेच करने के लिए किया जा सकता है.

streamUrl को सिर्फ़ एक बार फ़ेच किया जा सकता है. साथ ही, इसे सिर्फ़ आपके एक्सटेंशन के ऑरिजिन से फ़ेच किया जा सकता है. जवाब को प्रोसेस करने से पहले, उसे पूरी तरह से पढ़ें. एक ही streamUrl को दूसरी बार फ़ेच करने पर गड़बड़ी होती है. दस्तावेज़ का टाइटल या जगह की जानकारी दिखाने के लिए, originalUrl का इस्तेमाल करें. इसका इस्तेमाल कॉन्टेंट फ़ेच करने के लिए न करें, क्योंकि हो सकता है कि मूल अनुरोध को दोहराया न जा सके.

ध्यान दें: getStreamInfo() सिर्फ़ उस हैंडलर पेज पर काम करता है जिसे Chrome ने किसी दस्तावेज़ के लिए लोड किया है. इसे किसी अन्य एक्सटेंशन कॉन्टेक्स्ट से कॉल करने पर, यह काम नहीं करता. जैसे, सर्विस वर्कर या विकल्पों वाला पेज. ऐसा इसलिए होता है, क्योंकि इससे कोई स्ट्रीम नहीं जुड़ी होती.

नेटिव हैंडलर पर वापस जाएं

आपके हैंडलर को ऐसे दस्तावेज़ मिल सकते हैं जिन्हें वह रेंडर नहीं कर सकता. जैसे, खराब या पासवर्ड से सुरक्षित की गई फ़ाइलें. दस्तावेज़ को हैंडल करना बंद करने और उसे Chrome के बिल्ट-इन व्यूअर को वापस देने के लिए, abortAndFallbackToNativeHandler() को कॉल करें. इससे उपयोगकर्ता को काम न करने वाले पेज पर नहीं छोड़ा जाएगा. Chrome, फ़ॉलबैक के तौर पर आपके हैंडलर पेज को अनलोड कर देता है. इस कॉल के बाद कोई कोड नहीं चलता.

जब आपका हैंडलर चलता है, तब Chrome जवाब को बफ़र करता है. अगर इस तरीके को कॉल करने पर पूरा रिस्पॉन्स मिल जाता है, तो Chrome बिना किसी नए नेटवर्क का अनुरोध के, बफ़र की गई कॉपी से पहले से मौजूद व्यूअर को दिखाता है. ऐसा न करने पर, Chrome नेटवर्क से दस्तावेज़ को फिर से लोड करता है. हालांकि, POST या एक बार इस्तेमाल होने वाले यूआरएल से डिलीवर किए गए दस्तावेज़ों के लिए, यह प्रोसेस पूरी नहीं हो पाती. स्ट्रीम को रेंडर करने से पहले, उसे पूरी तरह से फ़ेच करें. streamUrl को फ़ेच करने की प्रोसेस पूरी होने के बाद, Chrome के पास पूरा रिस्पॉन्स होता है.

एपीआई की उपलब्धता मैनेज करना

Chrome 151 से पहले के वर्शन में, "mime_types_handler" का एलान करने वाला एक्सटेंशन अब भी इंस्टॉल होता है और काम करता है. हालांकि, वह हैंडलर के तौर पर रजिस्टर नहीं होता और browser.mimeHandler के बारे में जानकारी नहीं दी जाती. नेटवर्क अनुरोध को इंटरसेप्ट करने की सुविधा से माइग्रेट करने वाले एक्सटेंशन, स्टार्टअप के समय एपीआई की जांच कर सकते हैं. साथ ही, फ़ॉलबैक के तौर पर अपने मौजूदा तरीके को बनाए रख सकते हैं:

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

उदाहरण

स्ट्रीम को मैनेज करना

यहां दिया गया उदाहरण, मेनिफ़ेस्ट में बताए गए हैंडलर पेज पर चलता है. यह दस्तावेज़ का कॉन्टेंट फ़ेच करता है. अगर रेंडरिंग नहीं हो पाती है, तो यह 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();

उपयोगकर्ताओं को हैंडलिंग टॉगल करने की अनुमति दें

हैंडलर के विकल्प, एमआईएमई टाइप के हिसाब से सेव किए जाते हैं. यहां दिए गए उदाहरण में, 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 या इसके बाद का वर्शन

  क्या इस हैंडलर का इस्तेमाल, एम्बेड किए गए लोड (iframe, एम्बेड, ऑब्जेक्ट) के लिए किया जा सकता है. डिफ़ॉल्ट रूप से, मेनिफ़ेस्ट एंट्री की can_embed वैल्यू पर सेट होता है. enabled के 'गलत है' पर सेट होने पर, इसका कोई असर नहीं होता.

• चालू किया गया

  बूलियन ज़रूरी नहीं

  यह हैंडलर चालू है या नहीं. डिफ़ॉल्ट रूप से, मेनिफ़ेस्ट एंट्री की enabled वैल्यू पर सेट होता है.

StreamInfo

प्रॉपर्टी

• एम्बेड किया गया

  बूलियन

  अगर एम्बेड किए गए कॉन्टेक्स्ट (iframe/embed/object) में लोड किया गया है, तो वैल्यू true होगी.

• mimeType

  स्ट्रिंग

  इंटरसेप्ट किए गए कॉन्टेंट का एमआईएमई टाइप.

• originalUrl

  स्ट्रिंग

  वह ओरिजनल यूआरएल जिस पर उपयोगकर्ता ने नेविगेट किया.

• responseHeaders

  ऑब्जेक्ट

  की-वैल्यू पेयर के तौर पर एचटीटीपी रिस्पॉन्स हेडर.

• streamUrl

  स्ट्रिंग

  स्ट्रीम का डेटा फ़ेच करने के लिए यूआरएल.

• tabId

  संख्या

  दस्तावेज़ वाले टैब का आईडी.

तरीके

abortAndFallbackToNativeHandler()

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

यह मौजूदा स्ट्रीम हैंडलिंग को रद्द कर देता है और कॉन्टेंट को उपयोगकर्ता एजेंट के नेटिव हैंडलर को सौंप देता है. इस कॉल के बाद, एक्सटेंशन फ़्रेम को हटा दिया जाएगा. कॉलर को आगे की प्रोसेस की उम्मीद नहीं करनी चाहिए.

रिटर्न

• वादा<शून्य>

getMimeHandlerOptions()

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

किसी एमआईएमई टाइप के विकल्पों को पढ़ता है. हर सदस्य, एक्सटेंशन सेट की वैल्यू होती है. अगर एक्सटेंशन ने इसे सेट नहीं किया है, तो मेनिफ़ेस्ट एंट्री की वैल्यू होती है.

पैरामीटर

• mimeType

  स्ट्रिंग

  वह एमआईएमई टाइप जिसके विकल्प पढ़ने हैं. यह एक ऐसा एमआईएमई टाइप होना चाहिए जिसे एक्सटेंशन, mime_types_handler की मदद से मैनेज करता हो.

रिटर्न

• Promise<MimeHandlerOptions>

  एमआईएमई टाइप के विकल्पों के साथ प्रॉमिस रिज़ॉल्व किया गया.

getStreamInfo()

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

मौजूदा एमआईएमई हैंडलर कॉन्टेक्स्ट के लिए, स्ट्रीम की जानकारी हासिल करता है. इसे एमआईएमई हैंडलर एक्सटेंशन पेज से कॉल किया जाना चाहिए.

रिटर्न

• वादा<StreamInfo>

setMimeHandlerOptions()

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

किसी खास एमआईएमई टाइप के लिए, कॉन्फ़िगरेशन के विकल्प सेट करता है. अगर एक्सटेंशन, स्प्लिट गुप्त मोड में चलता है, तो गुप्त मोड से सेट किए गए विकल्प सिर्फ़ गुप्त मोड पर लागू होते हैं. साथ ही, ये विकल्प गुप्त मोड वाला सेशन खत्म होने तक ही लागू रहते हैं. गुप्त मोड में सेट नहीं किए गए विकल्प, गुप्त मोड से बाहर सेट की गई वैल्यू के मुताबिक काम करते हैं.

पैरामीटर

• mimeType

  स्ट्रिंग

  कॉन्फ़िगर करने के लिए एमआईएमई टाइप. यह एक ऐसा एमआईएमई टाइप होना चाहिए जिसे एक्सटेंशन, mime_types_handler की मदद से मैनेज करता हो.

• विकल्प

  MimeHandlerOptions

  बदलाव करने के विकल्प.

रिटर्न

• वादा<शून्य>

  कॉन्फ़िगरेशन सेट होने पर, प्रॉमिस रिज़ॉल्व हो जाता है.