browser.sidePanel

ब्यौरा

chrome.sidePanel API का इस्तेमाल करके, ब्राउज़र के साइड पैनल में कॉन्टेंट होस्ट करें. यह कॉन्टेंट, वेबपेज के मुख्य कॉन्टेंट के साथ दिखेगा.

अनुमतियां

sidePanel

Side Panel API का इस्तेमाल करने के लिए, एक्सटेंशन की मेनिफ़ेस्ट फ़ाइल में "sidePanel" अनुमति जोड़ें:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

उपलब्धता

Chrome 114+ MV3+

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

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

साइड पैनल का ड्रॉप-डाउन मेन्यू
Chrome ब्राउज़र के साइड पैनल का यूज़र इंटरफ़ेस.

इनमें ये सुविधाएं शामिल हैं:

  • अगर साइड पैनल को खुला रखने का विकल्प चुना गया है, तो टैब के बीच नेविगेट करने पर यह खुला रहता है.
  • यह सुविधा सिर्फ़ कुछ वेबसाइटों पर उपलब्ध हो सकती है.
  • एक्सटेंशन पेज के तौर पर, साइड पैनल के पास सभी Chrome API का ऐक्सेस होता है.
  • Chrome की सेटिंग में जाकर, उपयोगकर्ता यह तय कर सकते हैं कि पैनल किस तरफ़ दिखे.

उपयोग के उदाहरण

यहां दिए गए सेक्शन में, साइड पैनल एपीआई के इस्तेमाल के कुछ सामान्य उदाहरण दिए गए हैं. एक्सटेंशन के पूरे उदाहरणों के लिए, एक्सटेंशन के सैंपल देखें.

हर साइट पर एक ही साइड पैनल दिखाना

साइड पैनल को शुरू में, मेनिफ़ेस्ट की "side_panel" कुंजी में मौजूद "default_path" प्रॉपर्टी से सेट किया जा सकता है, ताकि हर साइट पर एक ही साइड पैनल दिखे. यह एक्सटेंशन डायरेक्ट्री में मौजूद किसी रिलेटिव पाथ की ओर ले जाना चाहिए.

manifest.json:

{
  "name": "My side panel extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

sidepanel.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Sidepanel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

किसी साइट पर साइड पैनल चालू करना

एक्सटेंशन, किसी टैब पर साइड पैनल चालू करने के लिए sidepanel.setOptions() का इस्तेमाल कर सकता है. इस उदाहरण में, टैब में किए गए किसी भी अपडेट को सुनने के लिए browser.tabs.onUpdated() का इस्तेमाल किया गया है. यह कुकी यह जांच करती है कि यूआरएल www.google.com है या नहीं. साथ ही, यह साइड पैनल को चालू करती है. ऐसा न होने पर, यह सुविधा बंद हो जाती है.

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

browser.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the side panel on google.com
  if (url.origin === GOOGLE_ORIGIN) {
    await browser.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await browser.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

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

जब उपयोगकर्ता ऐसी साइट पर जाता है जहां साइड पैनल चालू नहीं है, तो साइड पैनल बंद हो जाएगा. साथ ही, एक्सटेंशन, साइड पैनल के ड्रॉप-डाउन मेन्यू में नहीं दिखेगा.

पूरे उदाहरण के लिए, टैब के हिसाब से साइड पैनल का सैंपल देखें.

टूलबार आइकॉन पर क्लिक करके, साइड पैनल खोलें

डेवलपर, उपयोगकर्ताओं को sidePanel.setPanelBehavior() वाले ऐक्शन टूलबार आइकॉन पर क्लिक करके साइड पैनल खोलने की अनुमति दे सकते हैं. सबसे पहले, मेनिफ़ेस्ट में "action" कुंजी का एलान करें:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "action": {
    "default_title": "Click to open panel"
  },
  ...
}

अब इस कोड को पिछले उदाहरण में जोड़ें:

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

// Allows users to open the side panel by clicking on the action toolbar icon
browser.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

उपयोगकर्ता के इंटरैक्शन पर, साइड पैनल को प्रोग्राम के हिसाब से खोलना

Chrome 116 में sidePanel.open() की सुविधा जोड़ी गई है. इससे एक्सटेंशन, उपयोगकर्ता के जेस्चर (जैसे कि ऐक्शन आइकॉन पर क्लिक करना) के ज़रिए साइड पैनल खोल सकते हैं. इसके अलावा, एक्सटेंशन पेज या कॉन्टेंट स्क्रिप्ट पर उपयोगकर्ता के इंटरैक्शन को भी मेज़र किया जा सकता है. जैसे, किसी बटन पर क्लिक करना. पूरा डेमो देखने के लिए, साइड पैनल खोलें सैंपल एक्सटेंशन देखें.

इस कोड में बताया गया है कि जब उपयोगकर्ता किसी संदर्भ मेन्यू पर क्लिक करता है, तो मौजूदा विंडो पर ग्लोबल साइड पैनल कैसे खोला जाता है. sidePanel.open() का इस्तेमाल करते समय, आपको यह चुनना होगा कि इसे किस कॉन्टेक्स्ट में खोला जाना चाहिए. ग्लोबल साइड पैनल खोलने के लिए, windowId का इस्तेमाल करें. इसके अलावा, tabId को सेट करके, साइड पैनल को सिर्फ़ किसी खास टैब पर खोला जा सकता है.

service-worker.js:

browser.runtime.onInstalled.addListener(() => {
  browser.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open side panel',
    contexts: ['all']
  });
});

browser.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    browser.sidePanel.open({ windowId: tab.windowId });
  }
});

किसी दूसरे पैनल पर स्विच करना

एक्सटेंशन, मौजूदा साइड पैनल को वापस पाने के लिए sidepanel.getOptions() का इस्तेमाल कर सकते हैं. यहां दिए गए उदाहरण में, runtime.onInstalled() पर स्वागत वाला साइड पैनल सेट किया गया है. इसके बाद, जब उपयोगकर्ता किसी दूसरे टैब पर जाता है, तो यह उसे मुख्य साइड पैनल से बदल देता है.

service-worker.js:

const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';

browser.runtime.onInstalled.addListener(() => {
  browser.sidePanel.setOptions({ path: welcomePage });
  browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

browser.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await browser.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    browser.sidePanel.setOptions({ path: mainPage });
  }
});

पूरे कोड के लिए, एक से ज़्यादा साइड पैनल का सैंपल देखें.

साइड पैनल में उपयोगकर्ता अनुभव

उपयोगकर्ताओं को सबसे पहले Chrome के साथ पहले से मौजूद साइड पैनल दिखेंगे. हर साइड पैनल में, साइड पैनल मेन्यू में एक्सटेंशन का आइकॉन दिखता है. अगर कोई आइकॉन शामिल नहीं किया गया है, तो एक्सटेंशन के नाम के पहले अक्षर के साथ एक प्लेसहोल्डर आइकॉन दिखेगा.

साइड पैनल खोलें

उपयोगकर्ताओं को साइड पैनल खोलने की अनुमति देने के लिए, sidePanel.setPanelBehavior() के साथ ऐक्शन आइकॉन का इस्तेमाल करें. इसके अलावा, उपयोगकर्ता के इंटरैक्शन के बाद sidePanel.open() को कॉल करें. जैसे:

साइड पैनल को पिन करना

साइड पैनल के यूज़र इंटरफ़ेस (यूआई) में पिन आइकॉन.
साइड पैनल के यूज़र इंटरफ़ेस (यूआई) में पिन किया गया आइकॉन.

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

उदाहरण

Side Panel API एक्सटेंशन के ज़्यादा डेमो देखने के लिए, इनमें से कोई भी एक्सटेंशन आज़माएं:

टाइप

CloseOptions

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

प्रॉपर्टी

  • tabId

    number optional

    वह टैब जिसमें साइड पैनल को बंद करना है. अगर किसी टैब में टैब से जुड़ा साइड पैनल खुला है, तो वह उस टैब के लिए बंद हो जाएगा. अगर सिर्फ़ ग्लोबल साइड पैनल खुला है, तो close() को कॉल करने पर मिला प्रॉमिस, गड़बड़ी के साथ अस्वीकार कर दिया जाएगा. Chrome 145 में इस व्यवहार को बदल दिया गया था. इससे पहले के वर्शन में, ग्लोबल पैनल बंद हो जाता था. इस या windowId में से कम से कम एक वैल्यू देना ज़रूरी है.

  • windowId

    number optional

    वह विंडो जिसमें साइड पैनल को बंद करना है. अगर किसी विंडो में ग्लोबल साइड पैनल खुला है, तो उसे उस विंडो के उन सभी टैब के लिए बंद कर दिया जाएगा जहां टैब के हिसाब से कोई पैनल चालू नहीं है. इस या tabId में से कम से कम एक वैल्यू देना ज़रूरी है.

GetPanelOptions

प्रॉपर्टी

  • tabId

    number optional

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

OpenOptions

Chrome 116 और इसके बाद के वर्शन

प्रॉपर्टी

  • tabId

    number optional

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

  • windowId

    number optional

    वह विंडो जिसमें साइड पैनल खोलना है. यह सिर्फ़ तब लागू होता है, जब एक्सटेंशन में ग्लोबल (टैब के हिसाब से नहीं) साइड पैनल हो या tabId भी तय किया गया हो. इससे, उपयोगकर्ता के पास उस विंडो में फ़िलहाल खुले हुए किसी भी ग्लोबल साइड पैनल को बदलने का विकल्प होगा. इस या tabId में से कम से कम एक वैल्यू देना ज़रूरी है.

PanelBehavior

प्रॉपर्टी

  • openPanelOnActionClick

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

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

PanelClosedInfo

Chrome 142 और इसके बाद के वर्शन

प्रॉपर्टी

  • पाथ

    स्ट्रिंग

    एक्सटेंशन पैकेज में मौजूद स्थानीय संसाधन का पाथ, जिसका कॉन्टेंट पैनल में दिखाया जाता है.

  • tabId

    number optional

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

  • windowId

    संख्या

    उस विंडो का आईडी जहां साइड पैनल बंद किया गया था. यह सुविधा, ग्लोबल और टैब के हिसाब से बनाए गए पैनल, दोनों के लिए उपलब्ध है.

PanelLayout

Chrome 140+

प्रॉपर्टी

PanelOpenedInfo

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

प्रॉपर्टी

  • पाथ

    स्ट्रिंग

    एक्सटेंशन पैकेज में मौजूद स्थानीय संसाधन का पाथ, जिसका कॉन्टेंट पैनल में दिखाया जाता है.

  • tabId

    number optional

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

  • windowId

    संख्या

    उस विंडो का आईडी जहां साइड पैनल खोला गया है. यह सुविधा, ग्लोबल और टैब के हिसाब से बनाए गए पैनल, दोनों के लिए उपलब्ध है.

PanelOptions

प्रॉपर्टी

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

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

    साइड पैनल चालू होना चाहिए या नहीं. हालांकि, ऐसा करना ज़रूरी नहीं है. डिफ़ॉल्ट वैल्यू, सही है.

  • पाथ

    string ज़रूरी नहीं है

    इस्तेमाल की जाने वाली साइड पैनल की एचटीएमएल फ़ाइल का पाथ. यह एक्सटेंशन पैकेज में मौजूद कोई स्थानीय संसाधन होना चाहिए.

  • tabId

    number optional

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

Side

Chrome 140+

इससे ब्राउज़र के यूज़र इंटरफ़ेस (यूआई) में साइड पैनल के अलाइनमेंट के बारे में पता चलता है.

Enum

"left"

"right"

SidePanel

प्रॉपर्टी

  • default_path

    स्ट्रिंग

    डेवलपर ने साइड पैनल को दिखाने के लिए यह पाथ तय किया है.

तरीके

close()

Chrome 141 या इसके बाद के वर्शन 
chrome.sidePanel.close(
  options: CloseOptions,
): Promise<void>

इससे एक्सटेंशन का साइड पैनल बंद हो जाता है. अगर पैनल पहले से बंद है, तो यह विकल्प काम नहीं करता.

पैरामीटर

  • विकल्प

    CloseOptions

    इससे उस कॉन्टेक्स्ट के बारे में पता चलता है जिसमें साइड पैनल को बंद करना है.

रिटर्न

  • Promise<void>

    यह एक प्रॉमिस दिखाता है. जब साइड पैनल बंद हो जाता है, तब यह प्रॉमिस रिज़ॉल्व हो जाता है.

getLayout()

Chrome 140+ 
chrome.sidePanel.getLayout(): Promise<PanelLayout>

यह साइड पैनल के मौजूदा लेआउट की जानकारी देता है.

रिटर्न

  • Promise<PanelLayout>

    यह एक प्रॉमिस दिखाता है, जो PanelLayout के साथ रिज़ॉल्व होता है.

getOptions()

chrome.sidePanel.getOptions(
  options: GetPanelOptions,
): Promise<PanelOptions>

यह चालू पैनल कॉन्फ़िगरेशन दिखाता है.

पैरामीटर

  • विकल्प

    GetPanelOptions

    इससे उस कॉन्टेक्स्ट के बारे में पता चलता है जिसके लिए कॉन्फ़िगरेशन वापस लाना है.

रिटर्न

  • Promise<PanelOptions>

    यह एक प्रॉमिस दिखाता है, जो चालू पैनल कॉन्फ़िगरेशन के साथ रिज़ॉल्व होता है.

getPanelBehavior()

chrome.sidePanel.getPanelBehavior(): Promise<PanelBehavior>

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

रिटर्न

  • Promise<PanelBehavior>

    यह एक प्रॉमिस दिखाता है, जो एक्सटेंशन के साइड पैनल के व्यवहार के साथ रिज़ॉल्व होता है.

open()

Chrome 116 और इसके बाद के वर्शन 
chrome.sidePanel.open(
  options: OpenOptions,
): Promise<void>

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

पैरामीटर

  • विकल्प

    OpenOptions

    इससे यह तय होता है कि साइड पैनल किस कॉन्टेक्स्ट में खुलेगा.

रिटर्न

  • Promise<void>

    यह एक प्रॉमिस दिखाता है. साइड पैनल खुलने पर, यह प्रॉमिस रिज़ॉल्व हो जाता है.

setOptions()

chrome.sidePanel.setOptions(
  options: PanelOptions,
): Promise<void>

यह कुकी, साइड पैनल को कॉन्फ़िगर करती है.

पैरामीटर

  • विकल्प

    PanelOptions

    पैनल पर लागू करने के लिए कॉन्फ़िगरेशन के विकल्प.

रिटर्न

  • Promise<void>

    यह एक प्रॉमिस दिखाता है. जब विकल्प सेट हो जाते हैं, तब यह प्रॉमिस रिज़ॉल्व हो जाता है.

setPanelBehavior()

chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
): Promise<void>

यह कुकी, एक्सटेंशन के साइड पैनल के व्यवहार को कॉन्फ़िगर करती है. यह एक अपसर्ट ऑपरेशन है.

पैरामीटर

  • उपभोक्ता के व्यवहार

    PanelBehavior

    सेट किया जाने वाला नया व्यवहार.

रिटर्न

  • Promise<void>

    यह एक प्रॉमिस दिखाता है. नया व्यवहार सेट होने पर, यह प्रॉमिस रिज़ॉल्व हो जाता है.

इवेंट

onClosed

Chrome 142 और इसके बाद के वर्शन 
chrome.sidePanel.onClosed.addListener(
  callback: function,
)

यह इवेंट तब ट्रिगर होता है, जब एक्सटेंशन का साइड पैनल बंद होता है.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर ऐसा दिखता है: 

    (info: PanelClosedInfo) => void

onOpened

Chrome 141 या इसके बाद के वर्शन 
chrome.sidePanel.onOpened.addListener(
  callback: function,
)

यह इवेंट तब ट्रिगर होता है, जब एक्सटेंशन का साइड पैनल खोला जाता है.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर ऐसा दिखता है: 

    (info: PanelOpenedInfo) => void