chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات 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 في مطابقة أدوات الاختيار بكفاءة أكبر.

أدوات الاختيار المركّبة (مقبولة) أدوات الاختيار المعقّدة (غير مناسبة)
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) => {...}

  • css

    string[] اختياري

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

  • isBookmarked

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

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

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

  • pageUrl

    UrlFilter اختياري

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

RequestContentScript

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

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

الخصائص

  • المنشئ

    void

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

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

  • allFrames

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

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

  • css

    string[] اختياري

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

  • js

    string[] اختياري

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

  • matchAboutBlank

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

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

SetIcon

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

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

الخصائص

  • المنشئ

    void

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

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

  • imageData

    ‫ImageData | عنصر اختياري

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

ShowAction

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

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

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

الخصائص

ShowPageAction

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

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

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

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

الخصائص

الفعاليات

onPageChanged

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

الشروط

PageStateMatcher

الإجراءات

RequestContentScript

SetIcon

ShowPageAction

ShowAction