browser.mimeHandler

ब्यौरा

तीसरे पक्ष के एक्सटेंशन में एमआईएमई टाइप स्ट्रीम को मैनेज करने के लिए, 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
    }
  },
  ...
}

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

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

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

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

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

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

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

आपके हैंडलर को ऐसे दस्तावेज़ मिल सकते हैं जिन्हें वह रेंडर नहीं कर सकता. जैसे, खराब हो चुकी या पासवर्ड से सुरक्षित फ़ाइलें. दस्तावेज़ को हैंडल करना बंद करने के लिए, abortAndFallbackToNativeHandler() को कॉल करें. साथ ही, उपयोगकर्ता को खराब पेज पर ले जाने के बजाय, उसे Chrome के बिल्ट-इन व्यूअर पर वापस भेजें. फ़ॉलबैक के तौर पर, 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

प्रॉपर्टी

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

  बूलियन

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

StreamInfo

प्रॉपर्टी

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

  बूलियन

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

• mimeType

  स्ट्रिंग

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

• originalUrl

  स्ट्रिंग

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

• responseHeaders

  ऑब्जेक्ट

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

• streamUrl

  स्ट्रिंग

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

• tabId

  संख्या

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

तरीके

abortAndFallbackToNativeHandler()

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

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

रिटर्न

• Promise<void>

getMimeHandlerOptions()

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

यह कुकी, किसी एमआईएमई टाइप के लिए सेव किए गए विकल्पों को पढ़ती है. अगर कोई भी सेटिंग सेव नहीं की गई है, तो यह डिफ़ॉल्ट सेटिंग (enabled=true) दिखाता है.

पैरामीटर

• mimeType

  स्ट्रिंग

  वह एमआईएमई टाइप जिसके विकल्पों को पढ़ना है.

रिटर्न

• Promise<MimeHandlerOptions>

  MIME टाइप के लिए सेव किए गए विकल्पों के साथ प्रॉमिस पूरा हुआ.

getStreamInfo()

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

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

रिटर्न

• Promise<StreamInfo>

setMimeHandlerOptions()

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

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

पैरामीटर

• mimeType

  स्ट्रिंग

  कॉन्फ़िगर करने के लिए एमआईएमई टाइप.

• विकल्प

  MimeHandlerOptions

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

रिटर्न

• Promise<void>

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