chrome.events

الوصف

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

chrome.alarms.onAlarm.addListener(function(alarm) {
  appendToLog('alarms.onAlarm --'
              + ' name: '          + alarm.name
              + ' scheduledTime: ' + alarm.scheduledTime);
});

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

أمثلة على واجهات برمجة التطبيقات التي تستخدم الأحداث: alarms وi18n وidentity ووقت التشغيل. معظم Chrome واجهات برمجة التطبيقات (APIs).

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

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

يتم استخدام معالِجات الأحداث التعريفية مثلاً في Declarative Web Request API Declarative Content API: توضّح هذه الصفحة المفاهيم الأساسية لجميع الأحداث التعريفية. فقط.

القواعد

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

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

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

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

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

كائنات الأحداث

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

إضافة القواعد

لإضافة قواعد، يجب استدعاء الدالة addRules() لكائن الحدث. يتطلب الأمر مجموعة من مثيلات القواعد كمعاملته الأولى ودالة استدعاء عند استدعائها عند الإكمال.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

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

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

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

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

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

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

لاسترداد قائمة بالقواعد المسجَّلة حاليًا، يمكنك طلب الدالة getRules(). يقبل هي مصفوفة اختيارية لمعرّفات القواعد تتضمّن الدلالات نفسها مثل removeRules ودالة استدعاء.

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});

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

الأداء

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

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

بدلاً من:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);

يُفضَّل توفيره:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

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

بدلاً من:

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

يُفضَّل توفيره:

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

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

بدلاً من:

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

يُفضَّل توفيره:

  var rule = { conditions: [condition1, condition2],
                actions: [new chrome.declarativeWebRequest.CancelRequest()]};
  chrome.declarativeWebRequest.onRequest.addRules([rule]);

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

الأحداث التي تتم فلترتها هي آلية تسمح للمستمعين بتحديد مجموعة فرعية من الأحداث التي تهتم بها. لن يتم استدعاء مستمع يستخدم فلترًا للأحداث التي لا تتجاوز ما يجعل رمز الاستماع أكثر وضوحًا وفعالية. يحتاج عاملو خدمات أن يتم استياقه منها للتعامل مع الأحداث التي لا تهمه.

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

chrome.webNavigation.onCommitted.addListener(function(e) {
  if (hasHostSuffix(e.url, 'google.com') ||
      hasHostSuffix(e.url, 'google.com.au')) {
    // ...
  }
});

في ما يلي:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

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