شرح
از chrome.sidePanel API برای میزبانی محتوا در پانل کناری مرورگر درکنار محتوای اصلی صفحه وب استفاده کنید.
اجازه‌ها
sidePanelبرای استفاده از Side Panel API، اجازه "sidePanel" را در فایل مانیفست افزونه اضافه کنید:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
دردسترس بودن
مفاهیم و کاربرد
Side Panel API به افزونه‌ها اجازه می‌دهد واسط کاربر خود را در پانل کناری نمایش دهند و تجربه‌های پایداری را فعال کنند که سفر مرور کاربر را تکمیل می‌کند.
برخی‌از ویژگی‌ها عبارت‌اند از:
- پانل کناری هنگام پیمایش بین زبانه‌ها باز می‌ماند (اگر این‌طور تنظیم شده باشد).
- این ویژگی می‌تواند فقط در وب‌سایت‌های خاصی دردسترس باشد.
- پانل‌های کناری به‌عنوان صفحه افزونه به همه میاناهای برنامه‌سازی کاربردی Chrome دسترسی دارند.
- در تنظیمات 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() برای فعال کردن پانل کناری در برگه خاصی استفاده کند. این مثال از 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
مشخصات
-
tabId
شماره اختیاری
برگه‌ای که پانل کناری در آن بسته می‌شود. اگر پانل کناری مختص برگه در برگه مشخص‌شده باز باشد، برای آن برگه بسته خواهد شد. اگر فقط پانل کناری سراسری باز باشد، وعده برگردانده‌شده توسط فراخوانی به
close()با خطا رد خواهد شد. این رفتار در Chrome 145 تغییر کرده است و نسخه‌های قبلی به بستن پانل سراسری بازمی‌گردند. حداقل یکی از این یاwindowIdباید ارائه شود. -
windowId
شماره اختیاری
پنجره‌ای که پانل کناری در آن بسته می‌شود. اگر پانل کناری سراسری در پنجره مشخص‌شده باز باشد، برای همه برگه‌های آن پنجره که هیچ پانل مختص برگه‌ای در آن‌ها فعال نیست بسته خواهد شد. حداقل یکی از این یا
tabIdباید ارائه شود.
GetPanelOptions
مشخصات
-
tabId
شماره اختیاری
اگر مشخص شده باشد، گزینه‌های پانل کناری برای برگه داده‌شده برگردانده می‌شود. درغیراین‌صورت، گزینه‌های پانل کناری پیش‌فرض را برمی‌گرداند (برای هر برگه‌ای که تنظیمات خاصی ندارد استفاده می‌شود).
OpenOptions
مشخصات
-
tabId
شماره اختیاری
زبانه‌ای که پانل کناری در آن باز می‌شود. اگر برگه مربوطه پانل کناری مختص برگه داشته باشد، پانل فقط برای آن برگه باز خواهد بود. اگر پانل مختص برگه وجود نداشته باشد، پانل سراسری در برگه مشخص‌شده و هر برگه دیگری که درحال‌حاضر پانل مختص برگه باز نداشته باشد باز خواهد شد. این کار هر پانل کناری فعال کنونی (سراسری یا مختص برگه) را در برگه مربوطه لغو می‌کند. حداقل یکی از این یا
windowIdباید ارائه شود. -
windowId
شماره اختیاری
پنجره‌ای که پانل کناری در آن باز می‌شود. این مورد فقط زمانی قابل‌اجرا است که افزونه پانل کناری سراسری (غیرمختص برگه) داشته باشد یا
tabIdنیز مشخص شده باشد. این کار هر پانل کناری سراسری فعالی را که کاربر در پنجره موردنظر باز کرده است لغو می‌کند. حداقل یکی از این یاtabIdباید ارائه شود.
PanelBehavior
مشخصات
-
openPanelOnActionClick
بولی اختیاری
آیا کلیک کردن روی نماد افزونه، نمایش ورودی افزونه را در پانل کناری تغییر می‌دهد یا نه. پیش‌فرض: نادرست.
PanelClosedInfo
مشخصات
-
مسیر
رشته
مسیر منبع محلی در بسته افزونه که محتوای آن در پانل نمایش داده می‌شود.
-
tabId
شماره اختیاری
شناسه اختیاری برگه‌ای که پانل کناری در آن بسته شده است. این مورد فقط زمانی ارائه می‌شود که پانل مختص برگه باشد.
-
windowId
شماره
شناسه پنجره‌ای که پانل کناری در آن بسته شده است. این ویژگی هم برای پانل‌های سراسری و هم برای پانل‌های مختص برگه دردسترس است.
PanelLayout
مشخصات
-
طرف
PanelOpenedInfo
مشخصات
-
مسیر
رشته
مسیر منبع محلی در بسته افزونه که محتوای آن در پانل نمایش داده می‌شود.
-
tabId
شماره اختیاری
شناسه اختیاری برگه که پانل کناری در آن باز شده است. این مورد فقط زمانی ارائه می‌شود که پانل مختص برگه باشد.
-
windowId
شماره
شناسه پنجره‌ای که پانل کناری در آن باز شده است. این ویژگی هم برای پانل‌های سراسری و هم برای پانل‌های مختص برگه دردسترس است.
PanelOptions
مشخصات
-
فعال شد
بولی اختیاری
آیا پانل کناری باید فعال باشد یا نه. این مورد اختیاری است. مقدار پیش‌فرض true است.
-
مسیر
رشته اختیاری
مسیر فایل HTML پانل کناری برای استفاده. این باید منبعی محلی در بسته افزونه باشد.
-
tabId
شماره اختیاری
اگر مشخص شود، گزینه‌های پانل کناری فقط برای برگه دارای این شناسه اعمال خواهد شد. اگر حذف شود، این گزینه‌ها رفتار پیش‌فرض را تنظیم می‌کنند (برای هر برگه‌ای که تنظیمات خاصی ندارد استفاده می‌شود). توجه: اگر مسیر یکسانی برای این tabId و tabId پیش‌فرض تنظیم شده باشد، پانل این tabId نمونه متفاوتی نسبت به پانل tabId پیش‌فرض خواهد بود.
Side
ترازهای ممکن برای پانل کناری را در واسط کاربر مرورگر تعریف می‌کند.
شمارشی
"left"
«right»
SidePanel
مشخصات
-
default_path
رشته
مسیر مشخص‌شده توسعه‌دهنده برای نمایش پانل کناری.
روش‌ها
close()
browser.sidePanel.close(
options: CloseOptions,
): Promise<void>
پانل کناری افزونه را می‌بندد. اگر پانل ازقبل بسته باشد، این یک عملیات بی‌تأثیر است.
پارامترها
-
گزینه‌ها
بافتی را که پانل کناری در آن بسته می‌شود مشخص می‌کند.
بازگشتی‌ها
-
Promise<void>
یک Promise برمی‌گرداند که وقتی پانل کناری بسته می‌شود حل می‌شود.
getLayout()
browser.sidePanel.getLayout(): Promise<PanelLayout>
چیدمان فعلی پانل کناری را برمی‌گرداند.
بازگشتی‌ها
-
Promise<PanelLayout>
یک Promise برمی‌گرداند که با
PanelLayoutحل می‌شود.
getOptions()
browser.sidePanel.getOptions(
options: GetPanelOptions,
): Promise<PanelOptions>
پیکربندی پانل فعال را برمی‌گرداند.
پارامترها
-
گزینه‌ها
بافتی را که پیکربندی برای آن برگردانده می‌شود مشخص می‌کند.
بازگشتی‌ها
-
Promise<PanelOptions>
یک Promise برمی‌گرداند که با پیکربندی پانل فعال حل می‌شود.
getPanelBehavior()
browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>
رفتار پانل کناری فعلی افزونه را برمی‌گرداند.
بازگشتی‌ها
-
Promise<PanelBehavior>
یک Promise برمی‌گرداند که با رفتار پانل کناری افزونه حل می‌شود.
open()
browser.sidePanel.open(
options: OpenOptions,
): Promise<void>
پانل کناری را برای افزونه باز می‌کند. این ممکن است فقط در پاسخ به کنش کاربر فراخوانی شود.
پارامترها
-
گزینه‌ها
بافتی را که پانل کناری در آن باز می‌شود مشخص می‌کند.
بازگشتی‌ها
-
Promise<void>
یک Promise برمی‌گرداند که وقتی پانل کناری باز می‌شود حل می‌شود.
setOptions()
browser.sidePanel.setOptions(
options: PanelOptions,
): Promise<void>
پانل کناری را پیکربندی می‌کند.
پارامترها
-
گزینه‌ها
گزینه‌های پیکربندی برای اعمال روی پانل.
بازگشتی‌ها
-
Promise<void>
یک Promise برمی‌گرداند که وقتی گزینه‌ها تنظیم شدند حل می‌شود.
setPanelBehavior()
browser.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
): Promise<void>
رفتار پانل کناری افزونه را پیکربندی می‌کند. این عملیات «درج یا به‌روزرسانی» است.
پارامترها
-
رفتار مصرف‌کننده
رفتار جدیدی که باید تنظیم شود.
بازگشتی‌ها
-
Promise<void>
یک Promise برمی‌گرداند که وقتی رفتار جدید تنظیم شد، حل می‌شود.
رویدادها
onClosed
browser.sidePanel.onClosed.addListener(
callback: function,
)
وقتی پانل کناری افزونه بسته می‌شود، فعال می‌شود.
پارامترها
-
تماس برگشتی
عملکرد
پارامتر
callbackبه‌صورت زیر است:(info: PanelClosedInfo) => void
-
اطلاعات
-
onOpened
browser.sidePanel.onOpened.addListener(
callback: function,
)
وقتی پانل کناری افزونه باز می‌شود، فعال می‌شود.
پارامترها
-
تماس برگشتی
عملکرد
پارامتر
callbackبه‌صورت زیر است:(info: PanelOpenedInfo) => void
-
اطلاعات
-