chrome.mimeHandler

ब्यौरा

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

उपलब्धता

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

मेनिफ़ेस्ट

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

"mime_types_handler"

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

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

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

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

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

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

manifest.json:

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

<embed>, <object> या <iframe> एलिमेंट में एम्बेड किए गए दस्तावेज़ों को भी मैनेज करने के लिए, "can_embed" को true पर सेट करें. अगर इसे शामिल नहीं किया जाता है, तो आपका हैंडलर सिर्फ़ टॉप-लेवल नेविगेशन को मैनेज कर पाएगा. Chrome 151 से, application/pdf ही वह एमआईएमई टाइप है जो सार्वजनिक हैंडलर के लिए उपलब्ध है. अगर कोई ऐसा एमआईएमई टाइप शामिल किया जाता है जो काम नहीं करता है, तो इंस्टॉलेशन की चेतावनी दिखती है.

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

स्ट्रीम की जानकारी पाना

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

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

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

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

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

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

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

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

उदाहरण

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

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

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

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

प्रॉपर्टी

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

    बूलियन

    यह जानकारी कि दिया गया हैंडलर, दिए गए एमआईएमई टाइप के लिए चालू है या नहीं.

StreamInfo

प्रॉपर्टी

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

    बूलियन

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

  • mimeType

    स्ट्रिंग

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

  • originalUrl

    स्ट्रिंग

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

  • responseHeaders

    ऑब्जेक्ट

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

  • streamUrl

    स्ट्रिंग

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

  • tabId

    संख्या

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

तरीके

abortAndFallbackToNativeHandler()

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

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

रिटर्न

  • Promise<void>

getMimeHandlerOptions()

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

यह किसी एमआईएमई टाइप के लिए सेव किए गए विकल्पों को पढ़ता है. अगर कोई विकल्प सेव नहीं किया गया है, तो डिफ़ॉल्ट विकल्प (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

    स्ट्रिंग

    वह एमआईएमई टाइप जिसे कॉन्फ़िगर करना है.

  • इस्तेमाल किए जाने वाले नए विकल्प.

रिटर्न

  • Promise<void>

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