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

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

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

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

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

browser.action.onClicked.addListener(handleActionClick);

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

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

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

browser.action

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

browser.management

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

browser.notifications

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

browser.permissions

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

browser.runtime

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

browser.storage.onChanged

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

browser.webNavigation

توفّر هذه السمة معلومات عن حالة طلبات التنقّل أثناء الرحلة.

الفلاتر

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

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

browser.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 وbrowser.runtime.onMessage، مع عاملي الخدمة في الإضافات.

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