تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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.

الأنواع

ImageDataType

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

النوع

ImageData

PageStateMatcher

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

أماكن إقامة

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

فراغ

تبدو دالة constructor كما يلي:
```
(arg: PageStateMatcher) => {...}
```
- وسيطة
  
  PageStateMatcher
- returns
  PageStateMatcher
css

string[] اختيارية

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

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

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

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

UrlFilter اختياري

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

RequestContentScript

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

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

أماكن إقامة

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

فراغ

تبدو دالة constructor كما يلي:
```
(arg: RequestContentScript) => {...}
```
- وسيطة
  
  RequestContentScript
- returns
  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) => {...}
```
- وسيطة
  
  SetIcon
- returns
  SetIcon
بيانات الصورة

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

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

ShowAction

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

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

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

أماكن إقامة

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

فراغ

تبدو دالة constructor كما يلي:
```
(arg: ShowAction) => {...}
```
- وسيطة
  
  ShowAction
- returns
  ShowAction

ShowPageAction

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

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

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

أماكن إقامة

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

فراغ

تبدو دالة constructor كما يلي:
```
(arg: ShowPageAction) => {...}
```
- وسيطة
  
  ShowPageAction
- returns
  ShowPageAction

فعاليات

onPageChanged

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

الشروط

PageStateMatcher

المهام