chrome.events

الوصف

تحتوي مساحة الاسم 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 على سمة معرّف لم تستخدمه قاعدة أخرى أو معرِّف فارغ.

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

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

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

الأنواع

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 في حال تطابق رقم المنفذ التلقائي.