chrome.sidePanel

الوصف

يمكنك استخدام واجهة برمجة تطبيقات chrome.sidePanel لاستضافة المحتوى في اللوحة الجانبية للمتصفّح بجانب المحتوى الرئيسي لصفحة ويب.

الأذونات

sidePanel

لاستخدام واجهة برمجة التطبيقات Side Panel API، عليك إضافة إذن "sidePanel" في ملف بيان الإضافة:

manifest.json:

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

مدى التوفّر

الإصدار 114 من Chrome أو الإصدارات الأحدث MV3+

المفاهيم والاستخدام

تسمح واجهة برمجة التطبيقات Side Panel API للإضافات بعرض واجهة المستخدم الخاصة بها في اللوحة الجانبية، ما يوفّر تجارب دائمة تكمّل تجربة التصفُّح للمستخدم.

القائمة المنسدلة لللوحة الجانبية
واجهة المستخدم في اللوحة الجانبية لمتصفّح Chrome

وتشمل بعض الميزات ما يلي:

  • تبقى اللوحة الجانبية مفتوحة عند التنقل بين علامات التبويب (في حال ضبطها على هذا الإجراء).
  • يمكن أن تكون متاحة فقط على مواقع إلكترونية محددة.
  • كصفحة إضافة، يمكن للّوحات الجانبية الوصول إلى جميع واجهات برمجة تطبيقات 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-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
    });
  }
});

عندما ينتقل المستخدم مؤقتًا إلى علامة تبويب لا تكون فيها اللوحة الجانبية مفعّلة، سيتم إخفاء اللوحة الجانبية. وستظهر تلقائيًا مرة أخرى عندما ينتقل المستخدم إلى علامة تبويب كانت مفتوحة في السابق.

عندما ينتقل المستخدم إلى موقع إلكتروني لا تكون فيه اللوحة الجانبية مفعَّلة، سيتم إغلاق اللوحة الجانبية ولن تظهر الإضافة في القائمة المنسدلة في اللوحة الجانبية.

للاطّلاع على مثال كامل، يمكنك الاطّلاع على نموذج اللوحة الجانبية الخاصة بعلامة التبويب.

افتح اللوحة الجانبية من خلال النقر على رمز شريط الأدوات.

يمكن للمطوّرين السماح للمستخدمين بفتح اللوحة الجانبية عند النقر على رمز شريط أدوات الإجراءات من خلال 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(). ويسمح هذا الإذن للإضافات بفتح اللوحة الجانبية من خلال إيماءة مستخدم الإضافة، مثل النقر على رمز الإجراء. أو تفاعل أحد المستخدمين على صفحة الإضافة أو النص البرمجي للمحتوى، مثل النقر على زرّ. للحصول على عرض توضيحي كامل، يُرجى الاطّلاع على نموذج الإضافة Open Side Panel (فتح اللوحة الجانبية).

يعرض الرمز التالي كيفية فتح لوحة جانبية عامة في النافذة الحالية عندما ينقر المستخدم على قائمة سياق. عند استخدام 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.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() بعد تفاعل المستخدم، على سبيل المثال:

تثبيت اللوحة الجانبية

رمز الدبوس في واجهة المستخدم في اللوحة الجانبية
رمز الدبوس في واجهة المستخدم في اللوحة الجانبية

يعرض شريط أدوات اللوحة الجانبية رمز الدبوس عندما تكون اللوحة الجانبية مفتوحة. يؤدي النقر على هذا الرمز إلى تثبيت رمز إجراء الإضافة. النقر على رمز الإجراء بعد تثبيته، سينفّذ الإجراء التلقائي لرمز الإجراء الخاص بك فتح اللوحة الجانبية إذا تم ضبط ذلك بشكل صريح.

أمثلة

لمزيد من العروض التوضيحية لإضافات اللوحة الجانبية، يمكنك استكشاف أيّ من الإضافات التالية:

الأنواع

GetPanelOptions

أماكن إقامة

  • tabId

    الرقم اختياري

    في حال تحديدها، سيتم عرض خيارات اللوحة الجانبية لعلامة التبويب المحدّدة. بخلاف ذلك، يتم إرجاع الخيارات التلقائية للّوحة الجانبية (التي يتم استخدامها في أي علامة تبويب لا تتضمَّن إعدادات محدّدة).

OpenOptions

الإصدار 116 من Chrome أو الإصدارات الأحدث

أماكن إقامة

  • tabId

    الرقم اختياري

    علامة التبويب التي تريد فتح اللوحة الجانبية فيها إذا كانت علامة التبويب المقابلة تحتوي على لوحة جانبية خاصة بعلامة التبويب، لن تكون اللوحة مفتوحة إلا لعلامة التبويب هذه. إذا لم تكن هناك لوحة خاصة بعلامة تبويب، سيتم فتح اللوحة العامة في علامة التبويب المحدّدة وأي علامات تبويب أخرى بدون لوحة خاصة بعلامة تبويب مفتوحة حاليًا. سيؤدي هذا إلى إلغاء أي لوحة جانبية نشطة حاليًا (عامة أو خاصة بعلامة التبويب) في علامة التبويب المقابلة. يجب تقديم سمة واحدة على الأقل من هذه السمة أو windowId.

  • windowId

    الرقم اختياري

    النافذة المراد فتح اللوحة الجانبية فيها ينطبق ذلك فقط إذا كانت الإضافة تحتوي على لوحة جانبية عمومية (غير خاصة بعلامات التبويب) أو تم تحديد tabId أيضًا. سيؤدي هذا إلى تجاهل أي لوحة جانبية عامة نشطة حاليًا أنشأها المستخدم في النافذة المحدّدة. يجب تقديم سمة واحدة على الأقل من هذه السمة أو tabId.

PanelBehavior

أماكن إقامة

  • openPanelOnActionClick

    قيمة منطقية اختيارية

    سيؤدي النقر على رمز الإضافة إلى إيقاف/تفعيل عرض إدخال الإضافة في اللوحة الجانبية. وتكون القيمة التلقائية على "خطأ".

PanelOptions

أماكن إقامة

  • مفعّلة

    قيمة منطقية اختيارية

    لتحديد ما إذا كان يجب تفعيل اللوحة الجانبية أم لا. هذه خطوة اختيارية. القيمة التلقائية هي true.

  • المسار

    سلسلة اختيارية

    المسار إلى ملف HTML باللوحة الجانبية المراد استخدامه. يجب أن يكون هذا موردًا محليًا ضمن حزمة الإضافة.

  • tabId

    الرقم اختياري

    في حال تحديد خيارات اللوحة الجانبية، لن يتم تطبيقها إلا على علامة التبويب التي تحمل رقم التعريف هذا. في حال حذف هذه الخيارات، يتم ضبط السلوك التلقائي (يتم استخدامه مع أي علامة تبويب لم يتم ضبط إعدادات محدّدة لها). ملاحظة: في حال ضبط المسار نفسه لرقم تعريف علامة التبويب هذا ومعرّف علامة التبويب التلقائي، ستكون لوحة رقم تعريف علامة التبويب هذا مثيلاً مختلفًا عن اللوحة لرقم تعريف علامة التبويب التلقائي.

SidePanel

أماكن إقامة

  • default_path

    سلسلة

    المسار الذي حدّده المطوّر لعرض اللوحة الجانبية

الطُرق

getOptions()

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

تعرض إعدادات اللوحة النشطة.

المعلمات

  • الخيارات

    GetPanelOptions

    تُحدِّد السياق لعرض الإعدادات.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (options: PanelOptions) => void

المرتجعات

  • Promise&lt;PanelOptions&gt;

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getPanelBehavior()

وعود 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

تعرض السلوك الحالي للإضافة في اللوحة الجانبية.

المعلمات

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (behavior: PanelBehavior) => void

المرتجعات

  • Promise&lt;PanelBehavior&gt;

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

open()

وعود الإصدار 116 من Chrome والإصدارات الأحدث 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

تفتح اللوحة الجانبية للإضافة. ويمكن طلب ذلك فقط استجابةً لإجراء المستخدم.

المعلمات

  • الخيارات

    OpenOptions

    تحدِّد هذه السياسة السياق الذي سيتم فيه فتح اللوحة الجانبية.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

setOptions()

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

تضبط هذه السياسة اللوحة الجانبية.

المعلمات

  • الخيارات

    PanelOptions

    خيارات الضبط المطلوب تطبيقها على اللوحة

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

setPanelBehavior()

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

تضبط هذه السياسة سلوك اللوحة الجانبية للإضافة. هذه عملية أفضل.

المعلمات

  • المستهلكين

    PanelBehavior

    السلوك الجديد المراد ضبطه.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.