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

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

الخصائص

  • المنشئ

    باطل

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

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

  • css

    string[] اختياري

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

  • isBookmarked

    boolean اختياري

    Chrome 45+

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

  • pageUrl

    UrlFilter اختياري

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

RequestContentScript

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

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

الخصائص

  • المنشئ

    باطل

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

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

  • allFrames

    boolean اختياري

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

  • css

    string[] اختياري

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

  • js

    string[] اختياري

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

  • matchAboutBlank

    boolean اختياري

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

SetIcon

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

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

الخصائص

  • المنشئ

    باطل

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

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

  • imageData

    ImageData | object اختيارية

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

ShowAction

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

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

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

الخصائص

  • المنشئ

    باطل

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

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

ShowPageAction

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

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

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

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

الخصائص

الفعاليات

onPageChanged

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

الشروط

PageStateMatcher

الإجراءات

RequestContentScript

SetIcon

ShowPageAction

ShowAction