browser.sidePanel

ब्यौरा

chrome.sidePanel एपीआई का इस्तेमाल करके, वेबपेज के मुख्य कॉन्टेंट के साथ-साथ ब्राउज़र के साइड पैनल में कॉन्टेंट होस्ट करें.

अनुमतियां

sidePanel

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

manifest.json:

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

उपलब्धता

Chrome 114+ browser.* Chrome 148 से MV3+

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

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

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

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

• टैब के बीच नेविगेट करने पर, साइड पैनल खुला रहता है. हालांकि, ऐसा तब होता है, जब इसे खुला रखने के लिए सेट किया गया हो.
• यह सिर्फ़ कुछ वेबसाइटों पर उपलब्ध हो सकता है.
• एक्सटेंशन पेज के तौर पर, साइड पैनल के पास सभी Chrome एपीआई का ऐक्सेस होता है.
• 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() को कॉल करें. जैसे:

• ऐक्शन क्लिक
• कीबोर्ड शॉर्टकट
• कॉन्टेक्स्ट मेन्यू
• एक्सटेंशन पेज या कॉन्टेंट स्क्रिप्ट पर उपयोगकर्ता का जेस्चर.

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

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

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

उदाहरण

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

• डिक्शनरी का साइड पैनल.
• ग्लोबल साइड पैनल.
• एक से ज़्यादा साइड पैनल.
• साइड पैनल खोलें.
• साइट के हिसाब से साइड पैनल.

टाइप

CloseOptions

Chrome 141+ Chrome 148 से browser.*

प्रॉपर्टी

• tabId

  number ज़रूरी नहीं

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

• windowId

  number ज़रूरी नहीं

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

GetPanelOptions

प्रॉपर्टी

• tabId

  number ज़रूरी नहीं

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

OpenOptions

Chrome 116+ browser.* Chrome 148 से

प्रॉपर्टी

• tabId

  number ज़रूरी नहीं

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

• windowId

  number ज़रूरी नहीं

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

PanelBehavior

प्रॉपर्टी

• openPanelOnActionClick

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

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

PanelClosedInfo

Chrome 142 और इसके बाद के वर्शन Chrome 148 और इसके बाद के वर्शन के लिए browser.*

प्रॉपर्टी

• पाथ

  स्ट्रिंग

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

• tabId

  number ज़रूरी नहीं

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

• windowId

  संख्या

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

PanelLayout

Chrome 140+ browser.* Chrome 148 से

प्रॉपर्टी

• साइड

  साइड

PanelOpenedInfo

Chrome 141+ Chrome 148 से browser.*

प्रॉपर्टी

• पाथ

  स्ट्रिंग

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

• tabId

  number ज़रूरी नहीं

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

• windowId

  संख्या

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

PanelOptions

प्रॉपर्टी

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

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

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

• पाथ

  string ज़रूरी नहीं

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

• tabId

  number ज़रूरी नहीं

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

Side

Chrome 140+ browser.* Chrome 148 से

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

Enum

"left"

"right"

SidePanel

प्रॉपर्टी

• default_path

  स्ट्रिंग

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

तरीके

close()

Chrome 141+ Chrome 148 से browser.*

browser.sidePanel.close(
  options: CloseOptions,
): Promise<void>

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

पैरामीटर

• विकल्प

  CloseOptions

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

रिटर्न

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

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

getLayout()

Chrome 140+ browser.* Chrome 148 से

browser.sidePanel.getLayout(): Promise<PanelLayout>

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

रिटर्न

• Promise<PanelLayout>

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

getOptions()

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

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

पैरामीटर

• विकल्प

  GetPanelOptions

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

रिटर्न

• Promise<PanelOptions>

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

getPanelBehavior()

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

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

रिटर्न

• Promise<PanelBehavior>

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

open()

Chrome 116+ browser.* Chrome 148 से

browser.sidePanel.open(
  options: OpenOptions,
): Promise<void>

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

पैरामीटर

• विकल्प

  OpenOptions

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

रिटर्न

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

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

setOptions()

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

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

पैरामीटर

• विकल्प

  PanelOptions

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

रिटर्न

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

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

setPanelBehavior()

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

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

पैरामीटर

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

  PanelBehavior

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

रिटर्न

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

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

इवेंट

onClosed

Chrome 142 और इसके बाद के वर्शन Chrome 148 और इसके बाद के वर्शन के लिए browser.*

browser.sidePanel.onClosed.addListener(
  callback: function,
)

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

पैरामीटर

• कॉलबैक

  फ़ंक्शन

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

  (info: PanelClosedInfo) => void

  • जानकारी

    PanelClosedInfo

onOpened

Chrome 141+ Chrome 148 से browser.*

browser.sidePanel.onOpened.addListener(
  callback: function,
)

एक्सटेंशन का साइड पैनल खुलने पर ट्रिगर होता है.

पैरामीटर

• कॉलबैक

  फ़ंक्शन

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

  (info: PanelOpenedInfo) => void

  • जानकारी

    PanelOpenedInfo