chrome.events

الوصف

تحتوي مساحة الاسم 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، باستثناء مطابقة المخطط والمنفذ.

الأنواع

Event

كائن يسمح بإضافة أدوات معالجة الأحداث وإزالتها من خلال حدث Chrome.

أماكن إقامة

  • addListener

    فراغ

    يتم تسجيل معاودة الاتصال لأداة معالجة الحدث بالحدث.

    تبدو دالة addListener كما يلي:

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

    • رد الاتصال

      H

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

  • addRules

    فراغ

    تسجيل القواعد للتعامل مع الأحداث.

    تبدو دالة addRules كما يلي:

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

    • القواعد

      القاعدة<anyany>[]

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

    • رد الاتصال

      الدالة اختيارية

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

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

      • القواعد

        القاعدة<anyany>[]

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

  • getRules

    فراغ

    يعرض القواعد المسجّلة حاليًا.

    تبدو دالة getRules كما يلي:

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

    • ruleIdentifiers

      string[] اختيارية

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

    • رد الاتصال

      دالة

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

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

      • القواعد

        القاعدة<anyany>[]

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

  • hasListener

    فراغ

    تبدو دالة hasListener كما يلي:

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

    • رد الاتصال

      H

      المستمع الذي سيتم اختبار حالة التسجيل الخاصة به.

    • returns

      منطقي

      صحيح إذا كانت ميزة معاودة الاتصال مسجَّلة في الفعالية.

  • hasListeners

    فراغ

    تبدو دالة hasListeners كما يلي:

    () => {...}

    • returns

      منطقي

      صحيح إذا تم تسجيل أي أدوات معالجة للحدث في الفعالية.

  • removeListener

    فراغ

    لإلغاء تسجيل معاودة الاتصال لأداة معالجة الحدث من حدث.

    تبدو دالة removeListener كما يلي:

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

    • رد الاتصال

      H

      المستمع الذي سيكون غير مسجَّل.

  • removeRules

    فراغ

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

    تبدو دالة removeRules كما يلي:

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

    • ruleIdentifiers

      string[] اختيارية

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

    • رد الاتصال

      الدالة اختيارية

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

      () => void

Rule

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

أماكن إقامة

  • الإجراءات

    أي[]

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

  • الحالات

    أي[]

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

  • id

    سلسلة اختيارية

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

  • الحملة

    الرقم اختياري

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

  • الإشارات

    string[] اختيارية

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

UrlFilter

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

أماكن إقامة

  • cidrBlocks

    string[] اختيارية

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

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

  • hostContains

    سلسلة اختيارية

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

  • hostEquals

    سلسلة اختيارية

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

  • hostPrefix

    سلسلة اختيارية

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

  • hostSuffix

    سلسلة اختيارية

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

  • originAndPathMatches

    سلسلة اختيارية

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

  • pathContains

    سلسلة اختيارية

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

  • pathEquals

    سلسلة اختيارية

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

  • pathPrefix

    سلسلة اختيارية

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

  • pathSuffix

    سلسلة اختيارية

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

  • ports

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

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

  • queryContains

    سلسلة اختيارية

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

  • queryEquals

    سلسلة اختيارية

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

  • queryPrefix

    سلسلة اختيارية

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

  • querySuffix

    سلسلة اختيارية

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

  • المخططات

    string[] اختيارية

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

  • urlContains

    سلسلة اختيارية

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

  • urlEquals

    سلسلة اختيارية

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

  • urlMatches

    سلسلة اختيارية

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

  • urlPrefix

    سلسلة اختيارية

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

  • urlSuffix

    سلسلة اختيارية

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