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

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

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

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

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