این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

chrome.sidePanel

شرح

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

مجوزها

sidePanel

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

manifest.json:

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

دسترسی

Chrome 114+ MV3+

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

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

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

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

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

موارد استفاده کنید

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

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

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

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() برای گوش دادن به هر گونه به روز رسانی انجام شده در برگه استفاده می کند. بررسی می کند که آیا URL 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
    });
  }
});

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

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

برای مثال کامل، نمونه پانل جانبی مخصوص Tab را ببینید.

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

توسعه‌دهندگان می‌توانند به کاربران اجازه دهند وقتی روی نماد نوار ابزار عملکرد با 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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

برای نمونه کامل به پانل های جانبی متعدد مراجعه کنید.

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

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

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

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

از طریق ژست کاربر باز کنید

می توانید پانل کناری را از طریق تعاملات کاربر با استفاده از sidePanel.open() و sidePanel.setPanelBehavior() باز کنید، مانند:

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

مثال ها

برای نمایش‌های نمایشی افزونه‌های Side Panel API، یکی از برنامه‌های افزودنی زیر را کاوش کنید:

انواع

GetPanelOptions

خواص

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

OpenOptions

Chrome 116+

خواص

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

PanelBehavior

خواص

openPanelOnActionClick
بولی اختیاری
آیا با کلیک کردن روی نماد برنامه افزودنی، نمایش ورودی برنامه افزودنی در پانل کناری تغییر می کند. پیش فرض به نادرست.

PanelOptions

خواص

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

SidePanel

خواص

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

مواد و روش ها

getOptions()

وعده

chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

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

مولفه های

گزینه ها
GetPanelOptions
زمینه را برای بازگشت پیکربندی مشخص می کند.
پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
(options: PanelOptions)=>void
```
- گزینه ها
  PanelOptions

برمی گرداند

Promise< PanelOptions >
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getPanelBehavior()

وعده

chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

مولفه های

پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
(behavior: PanelBehavior)=>void
```
- رفتار - اخلاق
  رفتار پانل

برمی گرداند

Promise< PanelBehavior >
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

open()

Promise Chrome 116+

chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

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

مولفه های

گزینه ها
OpenOptions
زمینه باز شدن پانل کناری را مشخص می کند.
پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
()=>void
```

برمی گرداند

قول<باطل>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

setOptions()

وعده

chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

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

مولفه های

گزینه ها
PanelOptions
گزینه های پیکربندی برای اعمال در پانل.
پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
()=>void
```

برمی گرداند

قول<باطل>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

setPanelBehavior()

وعده

chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

رفتار پانل جانبی برنامه افزودنی را پیکربندی می کند. این یک عملیات فوق العاده است.

مولفه های

رفتار - اخلاق
رفتار پانل
رفتار جدیدی که باید تنظیم شود.
پاسخ به تماس
عملکرد اختیاری
پارامتر callback به نظر می رسد:
```
()=>void
```

برمی گرداند

قول<باطل>
Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.