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

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

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

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

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

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