chrome.declarativeContent

الوصف

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

الأذونات

declarativeContent

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

تتيح لك واجهة برمجة التطبيقات Declarative Content API تفعيل إجراء الإضافة استنادًا إلى عنوان 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 الحالي في الملف الشخصي للمستخدم. للاستفادة من هذا الشرط، "الإشارات المرجعية" يجب تعريفه في ملف الإضافة manifest.

الأنواع

النوع

ImageData

PageStateMatcher

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

أماكن إقامة

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

    فراغ

    تبدو دالة constructor كما يلي:

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

  • css

    string[] اختيارية

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

  • isBookmarked

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

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

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

  • pageUrl

    UrlFilter اختياري

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

RequestContentScript

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

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

أماكن إقامة

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

    فراغ

    تبدو دالة constructor كما يلي:

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

  • allFrames

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

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

  • css

    string[] اختيارية

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

  • JavaScript

    string[] اختيارية

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

  • matchAboutBlank

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

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

SetIcon

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

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

أماكن إقامة

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

    فراغ

    تبدو دالة constructor كما يلي:

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

  • بيانات الصورة

    ImageData | الكائن اختياري

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

ShowAction

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

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

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

أماكن إقامة

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

    فراغ

    تبدو دالة constructor كما يلي:

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

ShowPageAction

متوقفة منذ الإصدار 97 من Chrome

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

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

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

أماكن إقامة

فعاليات

onPageChanged

لتوفير Declarative Event API التي تتألّف من addRules وremoveRules وgetRules.

الشروط