chrome.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 API के इस्तेमाल के कुछ सामान्य उदाहरण दिए गए हैं. एक्सटेंशन के पूरे उदाहरणों के लिए, एक्सटेंशन के सैंपल देखें.

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

साइड पैनल को शुरू में, मेनिफ़ेस्ट की "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() का इस्तेमाल कर सकता है. इस उदाहरण में, टैब में किए गए किसी भी अपडेट को सुनने के लिए chrome.tabs.onUpdated() का इस्तेमाल किया गया है. यह कुकी यह जांच करती है कि यूआरएल www.google.com है या नहीं. साथ ही, यह साइड पैनल को चालू करती है. ऐसा न होने पर, यह सुविधा बंद हो जाती है.

service-worker.js:

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

chrome.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 chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await chrome.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
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

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

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

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

service-worker.js:

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

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

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

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

service-worker.js:

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

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

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

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

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

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

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

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

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

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

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

उदाहरण

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

टाइप

CloseOptions

मंज़ूरी मिलना बाकी है

प्रॉपर्टी

  • tabId

    number ज़रूरी नहीं

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

  • windowId

    number ज़रूरी नहीं

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

GetPanelOptions

प्रॉपर्टी

  • tabId

    number ज़रूरी नहीं

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

OpenOptions

Chrome 116+

प्रॉपर्टी

  • tabId

    number ज़रूरी नहीं

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

  • windowId

    number ज़रूरी नहीं

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

PanelBehavior

प्रॉपर्टी

  • openPanelOnActionClick

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

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

PanelLayout

Chrome 140+

प्रॉपर्टी

PanelOpenedInfo

मंज़ूरी मिलना बाकी है

प्रॉपर्टी

  • पाथ

    स्ट्रिंग

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

  • tabId

    number ज़रूरी नहीं

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

  • windowId

    संख्या

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

PanelOptions

प्रॉपर्टी

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

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

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

  • पाथ

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

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

  • tabId

    number ज़रूरी नहीं

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

Side

Chrome 140+

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

Enum

"left"

"right"

SidePanel

प्रॉपर्टी

  • default_path

    स्ट्रिंग

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

तरीके

getLayout()

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

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

रिटर्न

getOptions()

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

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

पैरामीटर

  • विकल्प

    GetPanelOptions

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

रिटर्न

getPanelBehavior()

chrome.sidePanel.getPanelBehavior(): 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>

इवेंट

onOpened

मंज़ूरी मिलना बाकी है
chrome.sidePanel.onOpened.addListener(
  callback: function,
)

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

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

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

    (info: PanelOpenedInfo) => void