الوصف
تحتوي مساحة الاسم 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
يحتوي على تفاصيل
عن المنبّه المنقضي.
أمثلة على واجهات برمجة التطبيقات باستخدام الأحداث: المنبّهات وi18n والهوية ووقت التشغيل. تفعل معظم واجهات برمجة تطبيقات 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
، باستثناء مطابقة المخطط والمنفذ.
الأنواع
Event
يشير ذلك المصطلح إلى كائن يسمح بإضافة أدوات معالجة حدث في Chrome وإزالتها.
أماكن إقامة
-
addListener
void
يعمل هذا الإعداد على تسجيل معاودة الاتصال في أداة معالجة الحدث في حدث.
تبدو الدالة
addListener
على النحو التالي:(callback: H) => {...}
-
معاودة الاتصال
H
يتم استدعاؤه عند وقوع حدث. تعتمد معلمات هذه الدالة على نوع الحدث.
-
-
addRules
void
تسجِّل القواعد لمعالجة الأحداث.
تبدو الدالة
addRules
على النحو التالي:(rules: Rule<anyany>[], callback?: function) => {...}
-
getRules
void
إرجاع القواعد المسجّلة حاليًا.
تبدو الدالة
getRules
على النحو التالي:(ruleIdentifiers?: string[], callback: function) => {...}
-
ruleIdentifiers
سلسلة[] اختيارية
في حال تمرير صفيف، لن يتم عرض سوى القواعد التي تحتوي على معرّفات مضمّنة في هذا الصفيف.
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(rules: Rule<anyany>[]) => void
-
القواعد
القاعدة<any>[]
القواعد التي تم تسجيلها، تتم تعبئة المعلّمات الاختيارية بالقيم.
-
-
-
hasListener
void
تبدو الدالة
hasListener
على النحو التالي:(callback: H) => {...}
-
معاودة الاتصال
H
المستمع الذي سيتم اختبار حالة تسجيله
-
returns
boolean
صحيح في حال تسجيل callback في الحدث.
-
-
hasListeners
void
تبدو الدالة
hasListeners
على النحو التالي:() => {...}
-
returns
boolean
صحيح إذا كانت أي أدوات لمعالجة الحدث مسجّلة في الحدث
-
-
removeListener
void
لإلغاء تسجيل معاودة الاتصال لأداة معالجة الحدث من الحدث.
تبدو الدالة
removeListener
على النحو التالي:(callback: H) => {...}
-
معاودة الاتصال
H
المستمع الذي سيتم إلغاء تسجيله
-
-
removeRules
void
إلغاء تسجيل القواعد المسجّلة حاليًا.
تبدو الدالة
removeRules
على النحو التالي:(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
سلسلة[] اختيارية
في حال تمرير صفيف، لن يتم تسجيل سوى القواعد التي تحتوي على معرّفات مضمّنة في هذا الصفيف.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
-
Rule
وصف قاعدة تعريفية لمعالجة الأحداث.
أماكن إقامة
-
الإجراءات
أي[]
قائمة بالإجراءات التي يتم تشغيلها في حال استيفاء أحد الشروط.
-
conditions
أي[]
قائمة الشروط التي يمكن أن تؤدي إلى تشغيل الإجراءات.
-
id
سلسلة اختيارية
معرّف اختياري يسمح بالإشارة إلى هذه القاعدة.
-
الحملة
الرقم اختياري
أولوية اختيارية ضمن هذه القاعدة. وتكون القيمة التلقائية 100.
-
الإشارات
سلسلة[] اختيارية
يمكن استخدام العلامات لإضافة تعليقات توضيحية إلى القواعد وتنفيذ العمليات على مجموعات القواعد.
UrlFilter
فلترة عناوين URL لمعايير مختلفة اطّلِع على فلترة الأحداث. جميع المعايير حسّاسة لحالة الأحرف.
أماكن إقامة
-
cidrBlocks
سلسلة[] اختيارية
Chrome 123 والإصدارات الأحدثيطابق إذا كان جزء المضيف لعنوان 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
(الرقم | الرقم[])[] اختياري
يطابق ما إذا كان منفذ عنوان URL مُدرَجًا في أيٍّ من قوائم المنافذ المحدَّدة. على سبيل المثال، يطابق
[80, 443, [1000, 1200]]
جميع الطلبات على المنفذ 80 و443 وفي النطاق 1000-1200. -
queryContains
سلسلة اختيارية
يطابق إذا كان مقطع طلب البحث لعنوان URL يحتوي على سلسلة محددة.
-
queryEquals
سلسلة اختيارية
يطابق إذا كان مقطع طلب البحث لعنوان URL يساوي سلسلة محددة.
-
queryPrefix
سلسلة اختيارية
يطابق إذا كان مقطع طلب البحث لعنوان URL يبدأ بسلسلة محددة.
-
querySuffix
سلسلة اختيارية
يطابق إذا كان مقطع طلب البحث الخاص بعنوان URL ينتهي بسلسلة محددة.
-
schemes
سلسلة[] اختيارية
يطابق إذا كان مخطط عنوان URL يساوي أي من المخططات المحددة في الصفيف.
-
urlContains
سلسلة اختيارية
يطابق ما إذا كان عنوان URL (بدون معرّف جزء) يحتوي على سلسلة محدّدة. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي.
-
urlEquals
سلسلة اختيارية
يطابق إذا كان عنوان URL (بدون معرّف جزء) يساوي سلسلة محدّدة. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي.
-
urlMatches
سلسلة اختيارية
يطابق إذا كان عنوان URL (بدون معرّف جزء) يطابق تعبيرًا عاديًا محددًا. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي. تستخدم التعبيرات العادية بنية RE2.
-
urlPrefix
سلسلة اختيارية
يطابق إذا كان عنوان URL (بدون معرّف الجزء) يبدأ بسلسلة محدّدة. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي.
-
urlSuffix
سلسلة اختيارية
يطابق ما إذا كان عنوان URL (بدون معرّف جزء) ينتهي بسلسلة محدّدة. تتم إزالة أرقام المنافذ من عنوان URL إذا كانت تتطابق مع رقم المنفذ التلقائي.