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

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

الإفصاح عن أحداث الإضافات

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

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