الوصف
استخدِم واجهة برمجة التطبيقات chrome.sidePanel
لاستضافة المحتوى في اللوحة الجانبية للمتصفِّح إلى جانب المحتوى الرئيسي لصفحة الويب.
الأذونات
sidePanel
لاستخدام واجهة برمجة التطبيقات Side Panel API، أضِف الإذن "sidePanel"
في ملف manifest الخاص بالإضافة:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
مدى التوفّر
المفاهيم والاستخدام
تسمح واجهة Side Panel API للإضافات بعرض واجهة المستخدم الخاصة بها في اللوحة الجانبية، ما يوفّر تجارب دائمة تتكامل مع تجربة التصفّح لدى المستخدم.
![القائمة المنسدلة لللوحة الجانبية](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/example-side-panel.png?authuser=5&hl=ar)
وتشمل بعض الميزات ما يلي:
- تظل اللوحة الجانبية مفتوحة عند التنقل بين علامات التبويب (في حال ضبطها على ذلك).
- ويمكن أن تتوفّر هذه الميزة على مواقع إلكترونية محدّدة فقط.
- باعتبارها صفحة إضافة، يمكن للّوحات الجانبية الوصول إلى جميع واجهات برمجة تطبيقات 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()
لتفعيل لوحة جانبية في علامة تبويب محدَّدة. يستخدم هذا المثال chrome.tabs.onUpdated()
للاستماع إلى أي تعديلات تم إجراؤها على علامة التبويب. تتحقّق هذه الخدمة مما إذا كان عنوان URL هو www.google.com وأنّها تفعّل اللوحة الجانبية. وبخلاف ذلك، سيتم إيقافها.
service-work.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-work.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-work.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-work.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()
بعد تفاعل أحد المستخدمين، مثل:
- نقرة على إجراء
- اختصار لوحة المفاتيح
- قائمة السياقات
- إيماءة مستخدم على صفحة إضافة أو نص برمجي للمحتوى.
تثبيت اللوحة الجانبية
![رمز التثبيت في واجهة مستخدم اللوحة الجانبية](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/side-panel-pin.png?authuser=5&hl=ar)
يعرض شريط أدوات اللوحة الجانبية رمز تثبيت عندما تكون اللوحة الجانبية مفتوحة. يؤدي النقر على الرمز إلى تثبيت رمز إجراء الإضافة. يؤدي النقر على رمز الإجراء بعد تثبيته إلى تنفيذ الإجراء التلقائي لرمز الإجراء، ولن يفتح اللوحة الجانبية إلا في حال ضبط هذا الإعداد صراحةً.
أمثلة
لمزيد من العروض التوضيحية لإضافات واجهة برمجة التطبيقات Side Panel API، يمكنك الاطّلاع على أيٍّ من الإضافات التالية:
- اللوحة الجانبية للمعجم
- اللوحة الجانبية العامة:
- لوحات جانبية متعدّدة:
- افتح اللوحة الجانبية.
- اللوحة الجانبية الخاصة بالموقع الإلكتروني:
الأنواع
GetPanelOptions
أماكن إقامة
-
tabId
الرقم اختياري
وفي حال تحديدها، سيتم عرض خيارات اللوحة الجانبية لعلامة التبويب المحدّدة. وبخلاف ذلك، سيتم عرض خيارات اللوحة الجانبية التلقائية (المستخدمة لأي علامة تبويب لا تحتوي على إعدادات معيّنة).
OpenOptions
أماكن إقامة
-
tabId
الرقم اختياري
علامة التبويب التي يمكن فتح اللوحة الجانبية فيها. إذا كانت علامة التبويب المقابلة تحتوي على لوحة جانبية خاصة بعلامة التبويب، لن تكون اللوحة مفتوحة إلا لعلامة التبويب تلك. إذا لم تكن هناك لوحة خاصة بعلامات التبويب، سيتم فتح اللوحة العامة في علامة التبويب المحدّدة وأي علامات تبويب أخرى بدون لوحة خاصة بعلامات التبويب المفتوحة حاليًا. سيؤدي هذا إلى إلغاء أي لوحة جانبية نشطة حاليًا (شاملة أو خاصة بعلامات تبويب) في علامة التبويب المقابلة. يجب تقديم سمة واحدة على الأقل أو سمة
windowId
. -
windowId
الرقم اختياري
النافذة التي يمكن فتح اللوحة الجانبية فيها. لا ينطبق ذلك إلا إذا كانت الإضافة تحتوي على لوحة جانبية عامة (غير مرتبطة بعلامات تبويب) أو إذا تم أيضًا تحديد
tabId
. سيؤدي هذا الإجراء إلى إلغاء أي لوحة جانبية عامة نشطة حاليًا فتحها المستخدم في النافذة المحدّدة. يجب تقديم سمة واحدة على الأقل أو سمةtabId
.
PanelBehavior
أماكن إقامة
-
openPanelOnActionClick
منطقية اختيارية
ما إذا كان النقر على رمز الإضافة سيؤدي إلى إيقاف عرض إدخال الإضافة في اللوحة الجانبية. يكون الإعداد التلقائي بالقيمة "خطأ".
PanelOptions
أماكن إقامة
-
مفعّلة
منطقية اختيارية
ما إذا كان يجب تفعيل اللوحة الجانبية. وهذه خطوة اختيارية. القيمة التلقائية هي true.
-
المسار
سلسلة اختيارية
المسار إلى ملف HTML لللوحة الجانبية المطلوب استخدامه. يجب أن يكون هذا موردًا محليًا ضمن حزمة الإضافة.
-
tabId
الرقم اختياري
في حال تحديد هذه السمة، لن يتم تطبيق خيارات اللوحة الجانبية إلا على علامة التبويب التي تحتوي على هذا المعرّف. وإذا تم حذفها، تحدِّد هذه الخيارات السلوك التلقائي (المستخدَم لأي علامة تبويب لا تتضمّن إعدادات محدَّدة). ملاحظة: في حال ضبط المسار نفسه للسمة tabId ومعرّف TabId التلقائي، ستكون اللوحة الخاصة بمعرّف TabId هذا مثيلاً مختلفًا عن لوحة المَعلمة TabId التلقائي.
SidePanel
أماكن إقامة
-
default_path
سلسلة
المسار المحدّد للمطوِّر لعرض اللوحة الجانبية.
الطُرق
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
تعرض إعدادات اللوحة النشطة.
المَعلمات
-
الخيارات
تُحدِّد السياق الذي يجب عرض الإعدادات من أجله.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(options: PanelOptions) => void
-
الخيارات
-
المرتجعات
-
Promise<PanelOptions>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
يتم عرض السلوك الحالي لللوحة الجانبية للإضافة.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(behavior: PanelBehavior) => void
-
المستهلكين
-
المرتجعات
-
Promise<PanelBehavior>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
يؤدي هذا الاختصار إلى فتح اللوحة الجانبية للإضافة. وقد يتم طلب ذلك فقط استجابةً لأحد إجراءات المستخدم.
المَعلمات
-
الخيارات
تُحدِّد السياق الذي سيتم فيه فتح اللوحة الجانبية.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
تعمل هذه السياسة على ضبط اللوحة الجانبية.
المَعلمات
-
الخيارات
خيارات الضبط لتطبيقها على اللوحة.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
تحدِّد هذه السياسة سلوك اللوحة الجانبية للإضافة. هذه عملية تأكيد.
المَعلمات
-
المستهلكين
السلوك الجديد الذي سيتم ضبطه
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.