browser.events

الوصف

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

Event هو عنصر يتيح لك تلقّي إشعارات عند حدوث أمر مثير للاهتمام. في ما يلي مثال على استخدام الحدث browser.alarms.onAlarm لتلقّي إشعار كلما انقضى وقت التنبيه:

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

كما يوضّح المثال، يمكنك التسجيل لتلقّي الإشعارات باستخدام addListener(). يكون وسيط addListener() دائمًا عبارة عن دالة تحدّدها للتعامل مع الحدث، ولكن تعتمد مَعلمات الدالة على الحدث الذي تتعامل معه. من خلال الاطّلاع على المستندات الخاصة بالدالة alarms.onAlarm، يمكنك ملاحظة أنّ الدالة تتضمّن مَعلمة واحدة، وهي كائن alarms.Alarm يتضمّن تفاصيل حول المنبّه المنقضي.

أمثلة على واجهات برمجة التطبيقات التي تستخدم الأحداث: alarms وi18n وidentity وruntime. معظم واجهات برمجة التطبيقات في Chrome تفعل ذلك.

معالجات الأحداث الوصفية

توفّر معالجات الأحداث التعريفية وسيلة لتحديد القواعد التي تتألف من شروط وإجراءات تعريفية. يتم تقييم الشروط في المتصفّح بدلاً من محرّك JavaScript، ما يقلّل من وقت الاستجابة ويسمح بتحقيق كفاءة عالية جدًا.

تُستخدَم معالجات الأحداث التعريفية مثلاً في Declarative Content API. توضّح هذه الصفحة المفاهيم الأساسية لجميع معالجات الأحداث التعريفية.

القواعد

تتألف أبسط قاعدة ممكنة من شرط واحد أو أكثر وإجراء واحد أو أكثر:

const rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

في حال استيفاء أيّ من الشروط، يتم تنفيذ جميع الإجراءات.

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

const rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

عناصر الحدث

قد تتوافق عناصر الأحداث مع القواعد. لا تستدعي عناصر الأحداث هذه دالّة رد الاتصال عند وقوع الأحداث، بل تختبر ما إذا كانت أي قاعدة مسجّلة تتضمّن شرطًا واحدًا على الأقل تم استيفاؤه، وتنفّذ الإجراءات المرتبطة بهذه القاعدة. تحتوي عناصر الأحداث المتوافقة مع واجهة برمجة التطبيقات التعريفية على ثلاث طرق ذات صلة، وهي: events.Event.addRules() وevents.Event.removeRules() وevents.Event.getRules().

إضافة قواعد

لإضافة قواعد، استدعِ الدالة addRules() الخاصة بعنصر الحدث. تتلقّى هذه الدالة مصفوفة من مثيلات القواعد كمعلَمة أولى، ودالة رد اتصال يتم استدعاؤها عند اكتمال العملية.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

في حال تم إدراج القواعد بنجاح، تحتوي المَعلمة details على مصفوفة من القواعد المُدرَجة التي تظهر بالترتيب نفسه كما في rule_list الذي تم تمريره، حيث تم ملء المَعلمتَين الاختياريتَين id وpriority بالقيم التي تم إنشاؤها. إذا كانت أي قاعدة غير صالحة، مثلاً لأنّها تتضمّن شرطًا أو إجراءً غير صالحَين، لن تتم إضافة أي من القواعد وسيتم ضبط المتغيّر runtime.lastError عند استدعاء دالّة رد الاتصال. يجب أن تحتوي كل قاعدة في rule_list على معرّف فريد لم يسبق أن استخدمته قاعدة أخرى أو معرّف فارغ.

إزالة القواعد

لإزالة القواعد، استخدِم الدالة removeRules(). تقبل هذه الطريقة مصفوفة اختيارية من معرّفات القواعد كمعلَمة أولى ودالة رد اتصال كمعلَمة ثانية.

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

إذا كانت rule_ids مصفوفة من المعرّفات، تتم إزالة جميع القواعد التي تتضمّن معرّفات مُدرَجة في المصفوفة. إذا كانت rule_ids تعرض معرّفًا غير معروف، سيتم تجاهل هذا المعرّف بدون إشعار. إذا كانت قيمة rule_ids هي undefined، ستتم إزالة جميع القواعد المسجّلة لهذه الإضافة. يتم استدعاء الدالة callback() عندما تتم إزالة القواعد.

استرداد القواعد

لاسترداد قائمة بالقواعد المسجّلة، استخدِم الدالة getRules(). يقبل هذا الإجراء صفيفًا اختياريًا من معرّفات القواعد يتضمّن الدلالات نفسها التي يتضمّنها removeRules()، بالإضافة إلى دالة ردّ الاتصال.

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

تشير المَعلمة details التي تم تمريرها إلى الدالة callback() إلى مصفوفة من القواعد تتضمّن مَعلمات اختيارية تم ملؤها.

الأداء

لتحقيق أفضل أداء، عليك مراعاة الإرشادات التالية.

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

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

يُفضّل استخدام مطابقة السلسلة الفرعية على التعبيرات العادية في events.UrlFilter. تكون المطابقة المستندة إلى السلسلة الفرعية سريعة للغاية.

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

إذا كانت هناك العديد من القواعد التي تتشارك الإجراءات نفسها، ادمِج القواعد في قاعدة واحدة. تفعّل القواعد إجراءاتها بمجرد استيفاء شرط واحد. يؤدي ذلك إلى تسريع عملية المطابقة وتقليل استهلاك الذاكرة لمجموعات الإجراءات المكرّرة.

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.declarativeWebRequest.onRequest.addRules([rule]);

الأحداث التي تمّت فلترتها

الأحداث التي تمّت فلترتها هي آلية تتيح لأدوات معالجة الأحداث تحديد مجموعة فرعية من الأحداث التي تهمّها. لن يتم استدعاء أداة معالجة تستخدم فلترًا للأحداث التي لا تستوفي معايير الفلتر، ما يجعل رمز المعالجة أكثر تعريفًا وفعالية. لا يلزم تنشيط عامل الخدمة للتعامل مع الأحداث التي لا تهمه.

تهدف الأحداث التي تمّت فلترتها إلى السماح بالانتقال من رمز الفلترة اليدوية.

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

عند مطابقة عناوين URL (كما في المثال أعلاه)، تتيح فلاتر الأحداث إمكانات مطابقة عناوين URL نفسها التي يمكن التعبير عنها باستخدام events.UrlFilter، باستثناء مطابقة المخطط والمنفذ.