chrome.events

refresh date: 2026-09-25 robots: noindex

الوصف

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 يتضمّن تفاصيل حول التنبيه المنقضي.

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

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

توفّر معالجات الأحداث التعريفية وسيلة لتحديد القواعد التي تتألف من شروط تعريفية وإجراءات. يتم تقييم الشروط في المتصفّح بدلاً من محرّك 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 */ ]
};

عناصر الحدث

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