browser.sidePanel

الوصف

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

الأذونات

sidePanel

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

manifest.json:

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

مدى التوفّر

الإصدار 114 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome الإصدار 3 من منصة MV والإصدارات الأحدث

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

تتيح واجهة 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() لتفعيل لوحة جانبية في علامة تبويب معيّنة. يستخدم هذا المثال browser.tabs.onUpdated() للاستماع إلى أي تعديلات يتم إجراؤها على علامة التبويب. تتحقّق هذه الإضافة مما إذا كان عنوان URL هو 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));
...

فتح اللوحة الجانبية آليًا عند تفاعل المستخدم

يقدّم الإصدار 116 من Chrome ميزة 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

الإصدار 141 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

• tabId

  number اختيارية

  علامة التبويب التي تريد إغلاق اللوحة الجانبية فيها إذا كانت هناك لوحة جانبية خاصة بعلامة تبويب مفتوحة في علامة التبويب المحدّدة، سيتم إغلاقها في علامة التبويب هذه. إذا كانت اللوحة الجانبية العامة فقط مفتوحة، سيتم رفض الوعد الذي تم إرجاعه من خلال طلب close() مع ظهور رسالة خطأ. تم تغيير هذا السلوك في الإصدار 145 من Chrome، حيث تعود الإصدارات السابقة إلى إغلاق اللوحة العامة. يجب توفير هذه السمة أو السمة windowId على الأقل.

• windowId

  number اختيارية

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

GetPanelOptions

الخصائص

• tabId

  number اختيارية

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

OpenOptions

الإصدار 116 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

• tabId

  number اختيارية

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

• windowId

  number اختيارية

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

PanelBehavior

الخصائص

• openPanelOnActionClick

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

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

PanelClosedInfo

الإصدار 142 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

• المسار

  سلسلة

  مسار المورد المحلي داخل حزمة الإضافة التي يتم عرض محتواها في اللوحة.

• tabId

  number اختيارية

  رقم التعريف الاختياري لعلامة التبويب التي تم إغلاق اللوحة الجانبية فيها لا يتم توفير هذه السمة إلا عندما تكون اللوحة خاصة بعلامة تبويب معيّنة.

• windowId

  الرقم

  رقم تعريف النافذة التي تم إغلاق اللوحة الجانبية فيها تتوفّر هذه الميزة لكلّ من اللوحات العامة واللوحات الخاصة بعلامات التبويب.

PanelLayout

الإصدار 140 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

• side

  الجانب

PanelOpenedInfo

الإصدار 141 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

• المسار

  سلسلة

  مسار المورد المحلي داخل حزمة الإضافة التي يتم عرض محتواها في اللوحة.

• tabId

  number اختيارية

  المعرّف الاختياري لعلامة التبويب التي يتم فتح اللوحة الجانبية فيها لا يتم توفير هذه السمة إلا عندما تكون اللوحة خاصة بعلامة تبويب معيّنة.

• windowId

  الرقم

  رقم تعريف النافذة التي يتم فتح اللوحة الجانبية فيها تتوفّر هذه الميزة لكلّ من اللوحات العامة واللوحات الخاصة بعلامات التبويب.

PanelOptions

الخصائص

• مفعّلة

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

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

• المسار

  string اختياري

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

• tabId

  number اختيارية

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

Side

الإصدار 140 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

"left"

"right"

SidePanel

الخصائص

• default_path

  سلسلة

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

الطُرق

close()

الإصدار 141 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

browser.sidePanel.close(
  options: CloseOptions,
): Promise<void>

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

المعلمات

• الخيارات

  CloseOptions

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

المرتجعات

• وعد<فراغ>

  تعرض هذه الطريقة كائن Promise يتم حله عند إغلاق اللوحة الجانبية.

getLayout()

الإصدار 140 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

browser.sidePanel.getLayout(): Promise<PanelLayout>

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

المرتجعات

• Promise<PanelLayout>

  تعرض هذه الطريقة كائن Promise يتم حله باستخدام PanelLayout.

getOptions()

browser.sidePanel.getOptions(
  options: GetPanelOptions,
): Promise<PanelOptions>

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

المعلمات

• الخيارات

  GetPanelOptions

  يحدّد السياق الذي سيتم عرض الإعدادات له.

المرتجعات

• Promise<PanelOptions>

  تعرِض هذه الطريقة Promise يتم حلّه باستخدام إعدادات اللوحة النشطة.

getPanelBehavior()

browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>

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

المرتجعات

• Promise<PanelBehavior>

  تعرض هذه الطريقة كائن Promise يتم حله من خلال سلوك اللوحة الجانبية للإضافة.

open()

الإصدار 116 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

browser.sidePanel.open(
  options: OpenOptions,
): Promise<void>

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

المعلمات

• الخيارات

  OpenOptions

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

المرتجعات

• وعد<فراغ>

  تعرض هذه الطريقة Promise يتم حلّه عند فتح اللوحة الجانبية.

setOptions()

browser.sidePanel.setOptions(
  options: PanelOptions,
): Promise<void>

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

المعلمات

• الخيارات

  PanelOptions

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

المرتجعات

• وعد<فراغ>

  تعرض هذه الدالة كائن Promise يتم حله عند ضبط الخيارات.

setPanelBehavior()

browser.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
): Promise<void>

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

المعلمات

• المستهلكين

  PanelBehavior

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

المرتجعات

• وعد<فراغ>

  تعرض هذه الدالة كائن Promise يتم حله عند ضبط السلوك الجديد.

الفعاليات

onClosed

الإصدار 142 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

browser.sidePanel.onClosed.addListener(
  callback: function,
)

يتم تنشيط هذا الحدث عند إغلاق اللوحة الجانبية للإضافة.

المعلمات

• callback

  دالة

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

  (info: PanelClosedInfo) => void

  • معلومات

    PanelClosedInfo

onOpened

الإصدار 141 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

browser.sidePanel.onOpened.addListener(
  callback: function,
)

يتم تنشيط هذا الحدث عند فتح اللوحة الجانبية للإضافة.

المعلمات

• callback

  دالة

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

  (info: PanelOpenedInfo) => void

  • معلومات

    PanelOpenedInfo