chrome.declarativeContent

الوصف

استخدِم واجهة برمجة التطبيقات chrome.declarativeContent API لتنفيذ الإجراءات استنادًا إلى محتوى الصفحة، بدون طلب الإذن لقراءة محتوى الصفحة.

الأذونات

declarativeContent

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

العبارة الرئيسية: يتحكّم إجراء الإضافة في رمز شريط أدوات الإضافة.

تتيح لك واجهة برمجة تطبيقات المحتوى البيان تفعيل إجراء الإضافة بناءً على عنوان URL لصفحة ويب، أو إذا كانت أداة اختيار لغة CSS تتطابق مع عنصر على الصفحة، بدون الحاجة إلى إضافة أذونات المضيف أو إدخال نص برمجي للمحتوى.

استخدام إذن activeTab للتفاعل مع الصفحة بعد أن ينقر المستخدم على إجراء الإضافة.

القواعد

تتكون القواعد من شروط وإجراءات. في حالة استيفاء أي من الشروط، يتم تنفيذ جميع الإجراءات. الإجراءان هما setIcon() وshowAction().

تتطابق السمة PageStateMatcher مع صفحات الويب في حال استيفاء جميع المعايير المدرَجة فقط. ويمكن أن يتطابق مع عنوان URL للصفحة أو أداة اختيار مركّب css أو حالة الإشارات المرجعية للصفحة. تفعِّل القاعدة التالية تنفيذ الإضافة على صفحات Google عند توفّر حقل كلمة المرور:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

نجاح: يتم إنشاء جميع الشروط والإجراءات باستخدام دالة إنشائية كما هو موضَّح في المثال السابق.

لتفعيل إجراء الإضافة أيضًا لمواقع Google الإلكترونية التي تتضمّن فيديو، يمكنك إضافة شرط ثانٍ، لأنّ كل شرط يكفي لتشغيل جميع الإجراءات المحدّدة:

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

يختبر حدث onPageChanged ما إذا كانت أيّ قاعدة تتضمّن شرطًا واحدًا على الأقل تمّ تنفيذه وينفّذ الإجراءات. تسري القواعد في جميع جلسات التصفح، لذلك، أثناء وقت تثبيت الإضافة، يجب أولاً استخدام removeRules لمحو القواعد المُثبَّتة سابقًا ثم استخدام addRules لتسجيل قواعد جديدة.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

ملاحظة: عليك دائمًا تسجيل القواعد أو إلغاء تسجيلها بشكل مجمّع لأنّ كل عملية من هذه العمليات تعيد إنشاء بُنى البيانات الداخلية. وتُعدّ إعادة الإنشاء هذه مكلفة من الناحية الحسابية، ولكنها تسهّل عملية إنشاء خوارزمية مطابقة أسرع.

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

مطابقة عنوان URL للصفحة

تتطابق السمة PageStateMatcher.pageurl عند استيفاء معايير عناوين URL. والمعايير الأكثر شيوعًا هي سلسلة من المضيف أو المسار أو عنوان URL، متبوعًا بـ "يحتوي على" أو "يساوي" أو "بادئة" أو "لاحقة". ويشمل الجدول التالي بعض الأمثلة:

المعايير	سلسلة مطابقة لـ
{ hostSuffix: 'google.com' }	جميع عناوين URL على Google
{ pathPrefix: '/docs/extensions' }	عناوين URL لمستندات الإضافات
{ urlContains: 'developer.chrome.com' }	عناوين URL لجميع مستندات مطوّري برامج Chrome

جميع المعايير حسّاسة لحالة الأحرف. للحصول على قائمة كاملة بالمعايير، يمكنك الاطّلاع على UrlFilter.

مطابقة CSS

يجب أن تكون شروط PageStateMatcher.css أدوات اختيار مركّبة، مما يعني أنّه لا يمكنك تضمين تركيبات، مثل المسافة البيضاء أو ">" في أدوات الاختيار. ويساعد هذا Chrome في مطابقة أدوات الاختيار بكفاءة أكبر.

محدّدات المركّبات (OK)	أدوات الاختيار المعقدة (غير مقبولة)
a	div p
iframe.special[src^='http']	p>span.highlight
ns|*	p + ol
#abcd:checked	p::first-line

لا تتطابق شروط CSS إلا مع العناصر المعروضة: إذا كان العنصر الذي يتطابق مع أداة الاختيار هو display:none أو كان أحد عناصره الرئيسية display:none، لن يؤدي ذلك إلى تطابُق الشرط. إنّ العناصر المصمّمة باستخدام visibility:hidden، أو التي يتم وضعها خارج الشاشة، أو المخفية بواسطة عناصر أخرى، يمكن أن تجعل الشرط مطابقًا.

مطابقة الحالة التي تم وضع إشارة عليها

يسمح الشرط PageStateMatcher.isBookmarked بمطابقة حالة الإشارات المرجعية لعنوان URL الحالي في الملف الشخصي للمستخدم. للاستفادة من هذا الشرط، يجب الإعلان عن إذن "الإشارات المرجعية" في بيان الإضافة.

الأنواع

ImageDataType

يمكنك الاطّلاع على https://developer.mozilla.org/en-US/docs/Web/API/ImageData.

النوع

ImageData

PageStateMatcher

يطابق حالة صفحة الويب بناءً على معايير مختلفة.

أماكن إقامة

• الدالة الإنشائية

  void

  تبدو الدالة constructor على النحو التالي:

  (arg: PageStateMatcher)=> {...}

  • وسيطة

    PageStateMatcher

  • returns

    PageStateMatcher

• css

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

  يطابق ما إذا كانت كل أدوات اختيار لغة CSS في الصفيفة تتطابق مع العناصر المعروضة في إطار لها المصدر نفسه كإطار الصفحة الرئيسي. يجب أن تكون جميع أدوات الاختيار في هذه الصفيفة أدوات اختيار مركّبة لتسريع المطابقة. ملاحظة: يمكن أن يؤدي إدراج المئات من أدوات اختيار لغة CSS أو أدوات اختيار لغة CSS التي تتطابق مع مئات المرات في كل صفحة إلى إبطاء المواقع الإلكترونية.

• isBookmarked

  منطقية اختيارية

  Chrome 45 والإصدارات الأحدث

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

• pageUrl

  UrlFilter اختياري

  تتم المطابقة في حال استيفاء شروط UrlFilter لعنوان URL ذي المستوى الأعلى للصفحة.

RequestContentScript

إجراء حدث تعريفي يؤدي إلى إدخال نص برمجي للمحتوى.

تحذير: لا يزال هذا الإجراء تجريبيًا وغير متاح في الإصدارات الثابتة من Chrome.

أماكن إقامة

• الدالة الإنشائية

  void

  تبدو الدالة constructor على النحو التالي:

  (arg: RequestContentScript)=> {...}

  • وسيطة

    RequestContentScript

  • returns

    RequestContentScript

• allFrames

  منطقية اختيارية

  ما إذا كان سيتم تشغيل النص البرمجي للمحتوى في جميع إطارات الصفحة المطابقة، أو في الإطار العلوي فقط الإعداد التلقائي هو false.

• css

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

  أسماء ملفات CSS التي سيتم إدخالها كجزء من النص البرمجي للمحتوى

• js

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

  أسماء ملفات JavaScript التي سيتم إدخالها كجزء من النص البرمجي للمحتوى

• matchAboutBlank

  منطقية اختيارية

  لتحديد ما إذا كان سيتم إدراج النص البرمجي للمحتوى في about:blank وabout:srcdoc. الإعداد التلقائي هو false.

SetIcon

إجراء حدث تعريفي يضبط رمز مربّع n-dip لإجراء الصفحة أو إجراء المتصفّح الخاص بالإضافة عند استيفاء الشروط المقابلة. يمكن استخدام هذا الإجراء بدون أذونات المضيف، ولكن يجب أن تتضمّن الإضافة إجراء صفحة أو متصفّح.

يجب تحديد سمة واحدة من imageData أو path. كلاهما قواميس يعين عدد من وحدات البكسل لتمثيل صورة. تمثيل الصورة في imageData هو كائن ImageData، على سبيل المثال، من عنصر canvas، بينما تمثيل الصورة في path هو المسار إلى ملف صورة ذي صلة ببيان الإضافة. إذا كانت وحدات بكسل الشاشة scale تتوافق مع وحدة بكسل مستقلة عن الجهاز، سيتم استخدام الرمز scale * n. في حال عدم إدخال هذا المقياس، سيتم تغيير حجم صورة أخرى إلى الحجم المطلوب.

أماكن إقامة

• الدالة الإنشائية

  void

  تبدو الدالة constructor على النحو التالي:

  (arg: SetIcon)=> {...}

  • وسيطة

    SetIcon

  • returns

    SetIcon

• imageData

  ImageData|Object اختياري

  تمثّل هذه السمة عنصر ImageData أو القاموس {size -> ImageData} الذي يمثّل الرمز المطلوب ضبطه. إذا تم تحديد الرمز كقاموس، فسيتم اختيار الصورة المستخدمة بناءً على كثافة وحدات البكسل في الشاشة. إذا كان عدد وحدات بكسل الصور التي تلائم وحدة مساحة شاشة واحدة يساوي scale، يتم عندئذٍ اختيار صورة بحجم scale * n، حيث يكون n هو حجم الرمز في واجهة المستخدم. يجب تحديد صورة واحدة على الأقل. يُرجى العِلم أنّ details.imageData = foo تساوي details.imageData = {'16': foo}.

ShowAction

Chrome 97 والإصدارات الأحدث

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

على الصفحات التي لا تستوفي الشروط، سيصبح إجراء شريط أدوات الإضافة باللون الرمادي، وسيؤدي النقر عليه إلى فتح قائمة السياق بدلاً من تشغيل الإجراء.

أماكن إقامة

• الدالة الإنشائية

  void

  تبدو الدالة constructor على النحو التالي:

  (arg: ShowAction)=> {...}

  • وسيطة

    ShowAction

  • returns

    ShowAction

ShowPageAction

تم إيقافه منذ إصدار 97 من Chrome

يُرجى استخدام declarativeContent.ShowAction.

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

على الصفحات التي لا تستوفي الشروط، سيصبح إجراء شريط أدوات الإضافة باللون الرمادي، وسيؤدي النقر عليه إلى فتح قائمة السياق بدلاً من تشغيل الإجراء.

أماكن إقامة

• الدالة الإنشائية

  void

  تبدو الدالة constructor على النحو التالي:

  (arg: ShowPageAction)=> {...}

  • وسيطة

    ShowPageAction

  • returns

    ShowPageAction

فعاليات

onPageChanged

توفّر واجهة برمجة التطبيقات للحدث البيان التي تتكوَّن من addRules وremoveRules وgetRules.

الشروط

PageStateMatcher

المهام

RequestContentScript

SetIcon

ShowPageAction

ShowAction