chrome.events

الوصف

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

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

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

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

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

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

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

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

قد تتوافق كائنات الأحداث مع القواعد. لا تستدعي كائنات الأحداث هذه دالة استدعاء إذا أحداث، ولكن يمكنك اختبار ما إذا كانت أي قاعدة مسجَّلة تتضمّن شرطًا واحدًا على الأقل مستوفًى وتم تنفيذها الإجراءات المرتبطة بهذه القاعدة. تحتوي كائنات الأحداث التي تدعم واجهة برمجة التطبيقات declarative API على ثلاث الطرق ذات الصلة: 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 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);

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

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

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

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

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

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

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

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

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

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

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

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

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

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