أحداث لعمّال الخدمات

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

تعريف أحداث الإضافة

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

chrome.storage.local.get(["badgeText"], ({ badgeText }) => {
  chrome.action.setBadgeText({ text: badgeText });
  chrome.action.onClicked.addListener(handleActionClick);
});

chrome.action.onClicked.addListener(handleActionClick);

chrome.storage.local.get(["badgeText"], ({ badgeText }) => {
  chrome.action.setBadgeText({ text: badgeText });
});

الأحداث الشائعة

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

chrome.action

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

chrome.management

تقدّم الأحداث ذات الصلة بتثبيت الإضافات وإلغاء تثبيتها وتفعيلها وإيقافها.

chrome.notifications

يقدِّم أحداثًا ذات صلة بتفاعل المستخدم مع إشعارات النظام التي تم إنشاؤها من خلال الإضافة.

chrome.permissions

يشير إلى الحالات التي يمنح فيها المستخدم أذونات الإضافة أو ألغاها.

chrome.runtime

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

chrome.storage.onChanged

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

chrome.webNavigation

يقدّم معلومات عن حالة طلبات التنقّل أثناء الطيران.

الفلاتر

لحصر الأحداث على حالة استخدام معيَّنة، أو التخلص من استدعاءات الأحداث غير الضرورية، استخدِم واجهات برمجة التطبيقات التي تتيح فلاتر الأحداث. على سبيل المثال، يمكنك استخدام إضافة تستمع إلى حدث tabs.onUpdated لرصد انتقال المستخدِم إلى موقع إلكتروني معيّن. سيتم استدعاء هذا الحدث في كل عملية تنقّل ضمن كل علامة تبويب. بدلاً من ذلك، استخدِم webNavigation.onCompleted مع فلتر. مثال:

const filter = {
  url: [
    {
      urlMatches: 'https://www.google.com/',
    },
  ],
};

chrome.webNavigation.onCompleted.addListener(() => {
  console.info("The user has loaded my favorite website!");
}, filter);

أحداث مشغّلي خدمات الويب

يدعم عاملو خدمات الإضافات أكثر من أحداث مراحل النشاط الموضّحة في مكان آخر.

ServiceWorkerGlobal.fetch

يتم تنشيطها عند استرداد أي محتوى من حزمة الإضافة أو عند استدعاء fetch() وXMLHttpRequest() من إضافة أو نص برمجي منبثق. (لا يعترض معالج fetch مشغّل الخدمات المكالمات من النصوص البرمجية للمحتوى). وفي الحالات الثانية، عليك إضافة عناوين URL للصفحات التي تريد جلبها إلى مفتاح "host_permissions" في manifest.json.

ServiceWorkerGlobal.message

تتوفّر ميزة "تمرير رسالة مشغّل الخدمات" بالإضافة إلى تمرير الرسائل، ولكن لا يمكن التشغيل التفاعلي بين النظامين. وهذا يعني أنّ معالِجات رسائل مشغّل الخدمات لا يتم اعتراضها عند إرسال الرسائل باستخدام sendMessage() (المتاحة من خلال واجهات برمجة تطبيقات متعددة للإضافات). وبالمثل، لا يتم اعتراض الرسائل المُرسَلة باستخدام postMessage() من خلال معالِجات رسائل الإضافات. يتوفّر كلا النوعين من معالِجات الرسائل، أي ServiceWorkerGlobal.message وchrome.runtime.onMessage معًا، في مشغّلي خدمات الإضافات.

عليك تفضيل رسائل الإضافات ما لم يكن لديك سبب محدد لاستخدام مراسلة مشغّلي الخدمات.