chrome.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 في مطابقة المحدّدات بكفاءة أكبر.

أدوات الاختيار المجمّعة (حسنًا)	أدوات الاختيار المعقّدة (غير مقبولة)
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 بمطابقة حالة bookmarked لعنوان URL الحالي في الملف الشخصي للمستخدم. للاستفادة من هذا الشرط، يجب الإفصاح عن إذن "الإشارات المرجعية" في manifest الإضافة.