chrome.sidePanel

الوصف

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

الأذونات

sidePanel

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

manifest.json:

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

مدى توفّر الخدمة

Chrome 114 والإصدارات الأحدث 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-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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

يمكنك الاطّلاع على اللوحات الجانبية المتعدّدة للاطّلاع على عيّنة كاملة.

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

ستظهر للمستخدمين اللوحات الجانبية المدمجة في Chrome أولاً. تعرض كل لوحة جانبية رمز الإضافة في قائمة اللوحة الجانبية. في حال عدم تضمين أي رموز، سيتم عرض رمز عنصر نائب يحمل الحرف الأول من اسم الإضافة.

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

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

يمكنك فتح اللوحة الجانبية من خلال تفاعلات المستخدم باستخدام sidePanel.open() وsidePanel.setPanelBehavior()، مثل:

أمثلة

لمزيد من العروض التوضيحية لإضافات واجهة برمجة التطبيقات Side Panel API، يمكنك الاطّلاع على أيٍّ من الإضافات التالية:

الأنواع

GetPanelOptions

أماكن إقامة

  • tabId

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

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

OpenOptions

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

أماكن إقامة

  • 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,
)

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

المَعلمات

  • الخيارات

    GetPanelOptions

    تُحدِّد السياق الذي يجب عرض الإعدادات من أجله.

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (options: PanelOptions)=>void

المرتجعات

  • Promise<PanelOptions>

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

getPanelBehavior()

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

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (behavior: PanelBehavior)=>void

المرتجعات

  • Promise<PanelBehavior>

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

open()

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

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

المَعلمات

  • الخيارات

    OpenOptions

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

setOptions()

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

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

المَعلمات

  • الخيارات

    PanelOptions

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

setPanelBehavior()

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

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

المَعلمات

  • المستهلكين

    PanelBehavior

    السلوك الجديد الذي سيتم ضبطه

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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