chrome.sidePanel

توضیحات

از API chrome.sidePanel برای میزبانی محتوا در پنل کناری مرورگر در کنار محتوای اصلی یک صفحه وب استفاده کنید.

مجوزها

sidePanel

برای استفاده از API پنل کناری، مجوز "sidePanel" را در فایل مانیفست افزونه اضافه کنید:

مانیفست.json:

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

در دسترس بودن

کروم ۱۱۴+ نسخه MV3+

مفاهیم و کاربردها

رابط برنامه‌نویسی کاربردی پنل کناری (Side Panel API) به افزونه‌ها اجازه می‌دهد تا رابط کاربری (UI) خود را در پنل کناری نمایش دهند و تجربه‌های پایداری را فراهم کنند که مکمل سفر مرور کاربر باشند.

منوی کشویی پنل کناری
رابط کاربری پنل کناری مرورگر کروم.

برخی از ویژگی‌ها عبارتند از:

  • هنگام پیمایش بین تب‌ها، پنل کناری باز می‌ماند (اگر طوری تنظیم شده باشد).
  • فقط در وب‌سایت‌های خاص قابل دسترسی است.
  • به عنوان یک صفحه افزونه، پنل‌های جانبی به تمام APIهای کروم دسترسی دارند.
  • در تنظیمات کروم، کاربران می‌توانند مشخص کنند که پنل در کدام سمت نمایش داده شود.

موارد استفاده

بخش‌های زیر برخی از موارد استفاده رایج برای API پنل کناری را نشان می‌دهند. برای مثال‌های کامل افزونه، به نمونه‌های افزونه مراجعه کنید.

نمایش پنل کناری یکسان در همه سایت‌ها

پنل کناری را می‌توان در ابتدا از ویژگی "default_path" در کلید "side_panel" مانیفست تنظیم کرد تا پنل کناری یکسانی در هر سایت نمایش داده شود. این باید به یک مسیر نسبی در دایرکتوری افزونه اشاره کند.

مانیفست.json:

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

پنل کناری.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() برای گوش دادن به هرگونه به‌روزرسانی انجام شده در تب استفاده می‌کند. این افزونه بررسی می‌کند که آیا URL برابر با www.google.com است یا خیر و پنل کناری را فعال می‌کند. در غیر این صورت، آن را غیرفعال می‌کند.

سرویس-ورکر.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 کلیک می‌کنند، پنل کناری را باز کنند. ابتدا، کلید "action" را در مانیفست تعریف کنید:

مانیفست.json:

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

حالا، این کد را به مثال قبلی اضافه کنید:

سرویس-ورکر.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));
...

باز کردن پنل کناری به صورت برنامه‌نویسی شده در تعامل با کاربر

کروم ۱۱۶، sidePanel.open() را معرفی می‌کند. این قابلیت به افزونه‌ها اجازه می‌دهد تا پنل کناری را از طریق یک حرکت کاربر افزونه، مانند کلیک روی آیکون عملیات ، یا یک تعامل کاربر در صفحه افزونه یا اسکریپت محتوا ، مانند کلیک روی یک دکمه، باز کنند. برای مشاهده‌ی نسخه‌ی نمایشی کامل، به نمونه‌ی افزونه‌ی Open Side Panel مراجعه کنید.

کد زیر نحوه باز کردن یک پنل کناری سراسری در پنجره فعلی را هنگامی که کاربر روی یک منوی زمینه کلیک می‌کند نشان می‌دهد. هنگام استفاده از sidePanel.open() ، باید زمینه‌ای را که باید در آن باز شود انتخاب کنید. از windowId برای باز کردن یک پنل کناری سراسری استفاده کنید. به طور جایگزین، tabId را طوری تنظیم کنید که پنل کناری فقط در یک تب خاص باز شود.

سرویس-ورکر.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() تنظیم می‌کند. سپس وقتی کاربر به تب دیگری می‌رود، آن را با پنل کناری اصلی جایگزین می‌کند.

سرویس-ورکر.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 });
  }
});

برای کد کامل، نمونه پنل‌های جانبی چندگانه را ببینید.

تجربه کاربری پنل کناری

کاربران ابتدا پنل‌های جانبی داخلی کروم را مشاهده خواهند کرد. هر پنل جانبی، آیکون افزونه را در منوی پنل جانبی نمایش می‌دهد. اگر هیچ آیکونی وجود نداشته باشد، یک آیکون با حرف اول نام افزونه نمایش داده می‌شود.

پنل کناری را باز کنید

برای اینکه به کاربران اجازه دهید پنل کناری را باز کنند، از یک آیکون اکشن در ترکیب با sidePanel.setPanelBehavior() استفاده کنید. روش دیگر، فراخوانی sidePanel.open() پس از تعامل کاربر است، مانند:

پنل کناری را پین کنید

آیکون را در رابط کاربری پنل کناری پین کنید.
آیکون را در رابط کاربری پنل کناری پین کنید.

نوار ابزار پنل کناری وقتی پنل کناری شما باز است، یک آیکون پین نمایش می‌دهد. کلیک روی آیکون، آیکون اکشن افزونه شما را پین می‌کند. کلیک روی آیکون اکشن پس از پین شدن، اکشن پیش‌فرض را برای آیکون اکشن شما اجرا می‌کند و فقط در صورتی پنل کناری را باز می‌کند که این قابلیت به صراحت پیکربندی شده باشد.

مثال‌ها

برای مشاهده دموهای بیشتر افزونه‌های API پنل کناری، هر یک از افزونه‌های زیر را بررسی کنید:

انواع

CloseOptions

کروم ۱۴۱+

خواص

  • شناسه برگه

    شماره اختیاری

    تبی که پنل کناری در آن بسته می‌شود. اگر یک پنل کناری مخصوص تب در تب مشخص شده باز باشد، برای آن تب بسته خواهد شد. حداقل یکی از این یا windowId باید ارائه شود.

  • شناسه پنجره

    شماره اختیاری

    پنجره‌ای که در آن پنل کناری بسته می‌شود. اگر یک پنل کناری سراسری در پنجره مشخص‌شده باز باشد، برای تمام تب‌های آن پنجره که هیچ پنل مخصوص تبی در آن فعال نیست، بسته خواهد شد. حداقل یکی از این یا tabId باید ارائه شود.

GetPanelOptions

خواص

  • شناسه برگه

    شماره اختیاری

    در صورت مشخص شدن، گزینه‌های پنل کناری برای برگه داده شده بازگردانده می‌شوند. در غیر این صورت، گزینه‌های پیش‌فرض پنل کناری (که برای هر برگه‌ای که تنظیمات خاصی ندارد استفاده می‌شود) را برمی‌گرداند.

OpenOptions

کروم ۱۱۶+

خواص

  • شناسه برگه

    شماره اختیاری

    تبی که پنل کناری در آن باز می‌شود. اگر تب مربوطه دارای پنل کناری مخصوص به تب باشد، پنل فقط برای آن تب باز خواهد بود. اگر پنل مخصوص به تب وجود نداشته باشد، پنل سراسری در تب مشخص شده و هر تب دیگری که پنل مخصوص به تب فعلی ندارد، باز خواهد شد. این امر هر پنل کناری فعال فعلی (سراسری یا مخصوص تب) را در تب مربوطه لغو می‌کند. حداقل یکی از this یا windowId باید ارائه شود.

  • شناسه پنجره

    شماره اختیاری

    پنجره‌ای که پنل کناری در آن باز می‌شود. این مورد فقط در صورتی قابل اجرا است که افزونه دارای یک پنل کناری سراسری (غیرمختص به تب) باشد یا tabId نیز مشخص شده باشد. این مورد، هر پنل کناری سراسری فعال فعلی را که کاربر در پنجره‌ی مورد نظر باز کرده است، لغو می‌کند. حداقل یکی از این یا tabId باید ارائه شود.

PanelBehavior

خواص

  • openPanelOnActionکلیک کنید

    بولی اختیاری

    اینکه آیا کلیک کردن روی آیکون افزونه، ورودی افزونه را در پنل کناری نمایش می‌دهد یا خیر. مقدار پیش‌فرض false است.

PanelClosedInfo

در حال بررسی

خواص

  • مسیر

    رشته

    مسیر منبع محلی درون بسته افزونه که محتوای آن در پنل نمایش داده می‌شود.

  • شناسه برگه

    شماره اختیاری

    شناسه اختیاری تبی که پنل کناری در آن بسته شده است. این شناسه فقط زمانی ارائه می‌شود که پنل مختص تب باشد.

  • شناسه پنجره

    شماره

    شناسه پنجره‌ای که پنل کناری در آن بسته شده است. این گزینه هم برای پنل‌های سراسری و هم برای پنل‌های مخصوص تب در دسترس است.

PanelLayout

کروم ۱۴۰+

خواص

PanelOpenedInfo

کروم ۱۴۱+

خواص

  • مسیر

    رشته

    مسیر منبع محلی درون بسته افزونه که محتوای آن در پنل نمایش داده می‌شود.

  • شناسه برگه

    شماره اختیاری

    شناسه اختیاری تبی که پنل کناری در آن باز می‌شود. این شناسه فقط زمانی ارائه می‌شود که پنل مختص تب باشد.

  • شناسه پنجره

    شماره

    شناسه پنجره‌ای که پنل کناری در آن باز می‌شود. این شناسه هم برای پنل‌های سراسری و هم برای پنل‌های مخصوص تب در دسترس است.

PanelOptions

خواص

  • فعال شده

    بولی اختیاری

    اینکه آیا پنل کناری باید فعال باشد یا خیر. این گزینه اختیاری است. مقدار پیش‌فرض آن true است.

  • مسیر

    رشته اختیاری

    مسیر فایل HTML پنل کناری برای استفاده. این باید یک منبع محلی در بسته افزونه باشد.

  • شناسه برگه

    شماره اختیاری

    در صورت مشخص شدن، گزینه‌های پنل کناری فقط برای تبی که این شناسه را دارد اعمال می‌شوند. در صورت حذف، این گزینه‌ها رفتار پیش‌فرض را تنظیم می‌کنند (برای هر تبی که تنظیمات خاصی ندارد استفاده می‌شود). توجه: اگر مسیر یکسانی برای این tabId و tabId پیش‌فرض تنظیم شده باشد، پنل مربوط به این tabId نمونه‌ای متفاوت از پنل مربوط به tabId پیش‌فرض خواهد بود.

Side

کروم ۱۴۰+

ترازبندی ممکن برای پنل کناری در رابط کاربری مرورگر را تعریف می‌کند.

شمارشی

«چپ»

«درست»

SidePanel

خواص

  • مسیر_پیش‌فرض

    رشته

    مسیر مشخص‌شده توسط توسعه‌دهنده برای نمایش پنل کناری.

روش‌ها

getLayout()

کروم ۱۴۰+
chrome.sidePanel.getLayout(): Promise<PanelLayout>

طرح‌بندی فعلی پنل کناری را برمی‌گرداند.

بازگشت‌ها

getOptions()

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

پیکربندی پنل فعال را برمی‌گرداند.

پارامترها

  • گزینه‌ها

    گزینه‌های GetPanel

    زمینه‌ای را که باید پیکربندی مربوط به آن برگردانده شود، مشخص می‌کند.

بازگشت‌ها

getPanelBehavior()

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

رفتار فعلی پنل کناری افزونه را برمی‌گرداند.

بازگشت‌ها

open()

کروم ۱۱۶+
chrome.sidePanel.open(
  options: OpenOptions,
): Promise<void>

پنل کناری افزونه را باز می‌کند. این قابلیت فقط می‌تواند در پاسخ به اقدام کاربر فراخوانی شود.

پارامترها

  • گزینه‌ها

    اوپن‌آپشن

    زمینه‌ای را مشخص می‌کند که در آن پنل کناری باز شود.

بازگشت‌ها

  • قول<void>

setOptions()

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

پنل کناری را پیکربندی می‌کند.

پارامترها

  • گزینه‌ها

    گزینه‌های پنل

    گزینه‌های پیکربندی که باید روی پنل اعمال شوند.

بازگشت‌ها

  • قول<void>

setPanelBehavior()

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

رفتار پنل کناری افزونه را پیکربندی می‌کند. این یک عملیات درج (upsert) است.

پارامترها

  • رفتار

    رفتار پنل

    رفتار جدیدی که باید تنظیم شود.

بازگشت‌ها

  • قول<void>

رویدادها

onOpened

کروم ۱۴۱+
chrome.sidePanel.onOpened.addListener(
  callback: function,
)

زمانی که پنل کناری افزونه باز شود، فعال می‌شود.

پارامترها