chrome.events

refresh date: 2026-09-25 robots: noindex

الوصف

تحتوي مساحة الاسم 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 وruntime. وهذا ما تفعله معظم واجهات برمجة تطبيقات 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 على معرّف فريد غير مستخدَم حاليًا في قاعدة أخرى أو معرّف فارغ.

ملاحظة: ملاحظة: تظل القواعد سارية في جميع جلسات التصفّح. لذلك، يجب تثبيت القواعد أثناء تثبيت الإضافة باستخدام الحدث runtime.onInstalled. يُرجى العِلم أنّ هذا الحدث يتم تشغيله أيضًا عند تحديث إضافة. لذلك، يجب أولاً محو القواعد المثبَّتة سابقًا ثم تسجيل قواعد جديدة.

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

لإزالة القواعد، استخدِم الدالة 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، باستثناء مطابقة المخطط والمنفذ.

الأنواع

Event

عنصر يسمح بإضافة أدوات معالجة أحداث Chrome وإزالتها

الخصائص

• addListener

  void

  يتم تسجيل دالة رد اتصال لمتتبِّع الأحداث في حدث معيّن.

  تبدو الدالة addListener على النحو التالي:

  (callback: H) => {...}

  • callback

    H

    يتم استدعاؤها عند وقوع حدث. تعتمد مَعلمات هذه الدالة على نوع الحدث.

• addRules

  void

  يتيح هذا الإذن تسجيل القواعد لمعالجة الأحداث.

  تبدو الدالة addRules على النحو التالي:

  (rules: Rule<anyany>[], callback?: function) => {...}

  • القواعد

    Rule<anyany>[]

    القواعد التي يجب تسجيلها ولا تحلّ هذه القواعد محلّ القواعد المسجَّلة سابقًا.

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي:

    (rules: Rule<anyany>[]) => void

    • القواعد

      Rule<anyany>[]

      القواعد التي تم تسجيلها، ويتم ملء المَعلمات الاختيارية بالقيم.

• getRules

  void

  تعرض هذه الطريقة القواعد المسجَّلة حاليًا.

  تبدو الدالة getRules على النحو التالي:

  (ruleIdentifiers?: string[], callback: function) => {...}

  • ruleIdentifiers

    string[] اختياري

    في حال تمرير مصفوفة، يتم عرض القواعد التي تحتوي على معرّفات في هذه المصفوفة فقط.

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي:

    (rules: Rule<anyany>[]) => void

    • القواعد

      Rule<anyany>[]

      القواعد التي تم تسجيلها، ويتم ملء المَعلمات الاختيارية بالقيم.

• hasListener

  void

  تبدو الدالة hasListener على النحو التالي:

  (callback: H) => {...}

  • callback

    H

    أداة معالجة الحدث التي سيتم اختبار حالة تسجيلها

  • returns

    قيمة منطقية

    تكون القيمة "صحيح" إذا تم تسجيل callback في الحدث.

• hasListeners

  void

  تبدو الدالة hasListeners على النحو التالي:

  () => {...}

  • returns

    قيمة منطقية

    تكون القيمة "صحيح" إذا تم تسجيل أي متتبِّعات أحداث للحدث.

• removeListener

  void

  لإلغاء تسجيل دالة ردّ نداء لمتتبِّع الأحداث من حدث معيّن.

  تبدو الدالة removeListener على النحو التالي:

  (callback: H) => {...}

  • callback

    H

    أداة معالجة الحدث التي سيتم إلغاء تسجيلها

• removeRules

  void

  لإلغاء تسجيل القواعد المسجَّلة حاليًا

  تبدو الدالة removeRules على النحو التالي:

  (ruleIdentifiers?: string[], callback?: function) => {...}

  • ruleIdentifiers

    string[] اختياري

    في حال تمرير مصفوفة، يتم إلغاء تسجيل القواعد التي تحتوي على معرّفات في هذه المصفوفة فقط.

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي:

    () => void

Rule

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

الخصائص

• الإجراءات

  any[]

  قائمة بالإجراءات التي يتم تنفيذها في حال استيفاء أحد الشروط

• الحالات الطبية

  any[]

  قائمة بالشروط التي يمكن أن تؤدي إلى تنفيذ الإجراءات

• id

  string اختياري

  معرّف اختياري يسمح بالإشارة إلى هذه القاعدة

• الحملة

  number اختيارية

  أولوية اختيارية لهذه القاعدة القيمة التلقائية هي 100.

• الإشارات

  string[] اختياري

  يمكن استخدام العلامات لإضافة تعليقات توضيحية إلى القواعد وتنفيذ العمليات على مجموعات من القواعد.

UrlFilter

لفلترة عناوين URL وفقًا لمعايير مختلفة اطّلِع على فلترة الأحداث. جميع المعايير حسّاسة لحالة الأحرف.

الخصائص

• cidrBlocks

  string[] اختياري

  الإصدار 123 من Chrome والإصدارات الأحدث

  تتم المطابقة إذا كان جزء المضيف من عنوان URL هو عنوان IP ومضمّنًا في أي من مجموعات CIDR المحدّدة في الصفيفة.

• hostContains

  string اختياري

  تحدث المطابقة إذا كان اسم مضيف عنوان URL يحتوي على سلسلة محدّدة. لاختبار ما إذا كان مكوّن اسم المضيف يحتوي على البادئة "foo"، استخدِم hostContains: ".foo". يتطابق هذا مع "www.foobar.com" و"foo.com"، لأنّه تتم إضافة نقطة ضمنية في بداية اسم المضيف. وبالمثل، يمكن استخدام hostContains للمطابقة مع لاحقة المكوّن ('foo.‎') وللمطابقة التامة مع المكوّنات ('.foo.‎'). يجب إجراء المطابقة التامة ومطابقة اللاحقة للمكوّنات الأخيرة بشكل منفصل باستخدام hostSuffix، لأنّه لا تتم إضافة نقطة ضمنية في نهاية اسم المضيف.

• hostEquals

  string اختياري

  تتم المطابقة إذا كان اسم مضيف عنوان URL يساوي سلسلة محدّدة.

• hostPrefix

  string اختياري

  تتم المطابقة إذا كان اسم المضيف لعنوان URL يبدأ بسلسلة محدّدة.

• hostSuffix

  string اختياري

  تتم المطابقة إذا كان اسم المضيف لعنوان URL ينتهي بسلسلة محدّدة.

• originAndPathMatches

  string اختياري

  تتم المطابقة إذا كان عنوان URL بدون جزء طلب البحث ومعرّف الجزء يتطابق مع تعبير عادي محدّد. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي. تستخدم التعبيرات العادية بنية RE2.

• pathContains

  string اختياري

  تتم المطابقة إذا كان جزء المسار من عنوان URL يحتوي على سلسلة محدّدة.

• pathEquals

  string اختياري

  تتم المطابقة إذا كان جزء المسار من عنوان URL يساوي سلسلة محدّدة.

• pathPrefix

  string اختياري

  تتم المطابقة إذا كان جزء المسار من عنوان URL يبدأ بسلسلة محدّدة.

• pathSuffix

  string اختياري

  تتم المطابقة إذا كان جزء المسار من عنوان URL ينتهي بسلسلة محدّدة.

• ports

  (number | number[])[] اختيارية

  تتم المطابقة إذا كان منفذ عنوان URL مضمّنًا في أي من قوائم المنافذ المحدّدة. على سبيل المثال، يتطابق [80, 443, [1000, 1200]] مع جميع الطلبات على المنفذ 80 و443 وفي النطاق 1000-1200.

• queryContains

  string اختياري

  تتم المطابقة إذا كان جزء طلب البحث في عنوان URL يحتوي على سلسلة محدّدة.

• queryEquals

  string اختياري

  تتم المطابقة إذا كان جزء طلب البحث في عنوان URL يساوي سلسلة معيّنة.

• queryPrefix

  string اختياري

  تتم المطابقة إذا كان جزء طلب البحث في عنوان URL يبدأ بسلسلة محدّدة.

• querySuffix

  string اختياري

  تتم المطابقة إذا كان جزء طلب البحث في عنوان URL ينتهي بسلسلة محدّدة.

• المخطّطات

  string[] اختياري

  تتم المطابقة إذا كان مخطط عنوان URL مساويًا لأي من المخططات المحدّدة في الصفيف.

• urlContains

  string اختياري

  تتم المطابقة إذا كان عنوان URL (بدون معرّف الجزء) يحتوي على سلسلة محدّدة. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي.

• urlEquals

  string اختياري

  تتم المطابقة إذا كان عنوان URL (بدون معرّف الجزء) يساوي سلسلة محدّدة. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي.

• urlMatches

  string اختياري

  تتم المطابقة إذا كان عنوان URL (بدون معرّف الجزء) يطابق تعبيرًا عاديًا محدّدًا. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي. تستخدم التعبيرات العادية بنية RE2.

• urlPrefix

  string اختياري

  تتم المطابقة إذا كان عنوان URL (بدون معرّف الجزء) يبدأ بسلسلة محدّدة. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي.

• urlSuffix

  string اختياري

  تتم المطابقة إذا كان عنوان URL (بدون معرّف الجزء) ينتهي بسلسلة معيّنة. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي.