الوصف
استخدِم واجهة برمجة التطبيقات chrome.declarativeContent
API لتنفيذ الإجراءات استنادًا إلى محتوى الصفحة، بدون طلب الإذن لقراءة محتوى الصفحة.
الأذونات
declarativeContent
الاستخدام
تتيح لك واجهة برمجة تطبيقات المحتوى البيان تفعيل إجراء الإضافة استنادًا إلى عنوان 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 الحالي في الملف الشخصي للمستخدم. للاستفادة من هذا الشرط، يجب الإعلان عن إذن "الإشارات المرجعية" في بيان الإضافة.
الأنواع
ImageDataType
يمكنك الاطّلاع على https://developer.mozilla.org/en-US/docs/Web/API/ImageData.
النوع
ImageData
PageStateMatcher
يطابق حالة صفحة الويب بناءً على معايير مختلفة.
أماكن إقامة
-
الدالة الإنشائية
void
تبدو الدالة
constructor
على النحو التالي:(arg: PageStateMatcher) => {...}
-
وسيطة
-
returns
-
-
css
سلسلة[] اختيارية
يطابق ما إذا كانت كل أدوات اختيار لغة CSS في الصفيفة تتطابق مع العناصر المعروضة في إطار لها المصدر نفسه كإطار الصفحة الرئيسي. يجب أن تكون جميع أدوات الاختيار في هذه الصفيفة أدوات اختيار مركّبة لتسريع المطابقة. ملاحظة: يمكن أن يؤدي إدراج المئات من أدوات اختيار لغة CSS أو أدوات اختيار لغة CSS التي تتطابق مع مئات المرات في كل صفحة إلى إبطاء المواقع الإلكترونية.
-
isBookmarked
منطقية اختيارية
Chrome 45 والإصدارات الأحدثيطابق إذا كانت حالة الصفحة الموضوع بإشارة مرجعية تساوي القيمة المحددة. يتطلب هذا الإجراء إذن الإشارات المرجعية.
-
pageUrl
UrlFilter اختياري
تتم المطابقة في حال استيفاء شروط
UrlFilter
لعنوان URL ذي المستوى الأعلى للصفحة.
RequestContentScript
إجراء حدث تعريفي يؤدي إلى إدخال نص برمجي للمحتوى.
تحذير: لا يزال هذا الإجراء تجريبيًا وغير متاح في الإصدارات الثابتة من Chrome.
أماكن إقامة
-
الدالة الإنشائية
void
تبدو الدالة
constructor
على النحو التالي:(arg: RequestContentScript) => {...}
-
وسيطة
-
returns
-
-
allFrames
منطقية اختيارية
ما إذا كان سيتم تشغيل النص البرمجي للمحتوى في جميع إطارات الصفحة المطابقة، أو في الإطار العلوي فقط الإعداد التلقائي هو
false
. -
css
سلسلة[] اختيارية
أسماء ملفات CSS التي سيتم إدخالها كجزء من النص البرمجي للمحتوى
-
js
سلسلة[] اختيارية
أسماء ملفات JavaScript التي سيتم إدخالها كجزء من النص البرمجي للمحتوى
-
matchAboutBlank
منطقية اختيارية
لتحديد ما إذا كان سيتم إدراج النص البرمجي للمحتوى في
about:blank
وabout:srcdoc
. الإعداد التلقائي هوfalse
.
SetIcon
إجراء حدث تعريفي يضبط رمز مربّع n-dip لإجراء الصفحة أو إجراء المتصفّح أثناء استيفاء الشروط المقابلة. يمكن استخدام هذا الإجراء بدون أذونات المضيف، ولكن يجب أن تتضمّن الإضافة إجراء صفحة أو متصفّح.
يجب تحديد سمة واحدة من imageData
أو path
. كلاهما قواميس يعين عدد من وحدات البكسل لتمثيل صورة. تمثيل الصورة في imageData
هو كائن ImageData، على سبيل المثال، من عنصر canvas
، بينما تمثيل الصورة في path
هو المسار إلى ملف صورة ذي صلة ببيان الإضافة. إذا كانت وحدات بكسل الشاشة scale
تتوافق مع وحدة بكسل مستقلة عن الجهاز، سيتم استخدام الرمز scale * n
. في حال عدم إدخال هذا المقياس، سيتم تغيير حجم صورة أخرى إلى الحجم المطلوب.
أماكن إقامة
-
الدالة الإنشائية
void
تبدو الدالة
constructor
على النحو التالي:(arg: SetIcon) => {...}
-
وسيطة
-
returns
-
-
imageData
ImageData | كائن اختياري
تمثّل هذه السمة عنصر
ImageData
أو القاموس {size -> ImageData} الذي يمثّل الرمز المطلوب ضبطه. إذا تم تحديد الرمز كقاموس، فسيتم اختيار الصورة المستخدمة بناءً على كثافة وحدات البكسل في الشاشة. إذا كان عدد وحدات بكسل الصور التي تلائم وحدة مساحة شاشة واحدة يساويscale
، يتم عندئذٍ اختيار صورة بحجمscale * n
، حيث يكون n هو حجم الرمز في واجهة المستخدم. يجب تحديد صورة واحدة على الأقل. يُرجى العِلم أنّdetails.imageData = foo
تساويdetails.imageData = {'16': foo}
.
ShowAction
إجراء حدث تعريفي يضبط إجراء شريط أدوات الإضافة على حالة مفعّلة عند استيفاء الشروط المقابلة. يمكن استخدام هذا الإجراء بدون أذونات المضيف. إذا كانت الإضافة تمتلك إذن activeTab، فإن النقر على إجراء الصفحة يمنح إمكانية الوصول إلى علامة التبويب النشطة.
على الصفحات التي لا تستوفي الشروط، سيصبح إجراء شريط أدوات الإضافة باللون الرمادي، وسيؤدي النقر عليه إلى فتح قائمة السياق بدلاً من تشغيل الإجراء.
أماكن إقامة
-
الدالة الإنشائية
void
تبدو الدالة
constructor
على النحو التالي:(arg: ShowAction) => {...}
-
وسيطة
-
returns
-
ShowPageAction
يُرجى استخدام declarativeContent.ShowAction
.
إجراء حدث تعريفي يضبط إجراء الصفحة للإضافة على حالة مفعّلة أثناء استيفاء الشروط المقابلة. يمكن استخدام هذا الإجراء بدون أذونات المضيف، ولكن يجب أن تتضمّن الإضافة إجراء صفحة. إذا كانت الإضافة تمتلك إذن activeTab، فإن النقر على إجراء الصفحة يمنح إمكانية الوصول إلى علامة التبويب النشطة.
على الصفحات التي لا تستوفي الشروط، سيصبح إجراء شريط أدوات الإضافة باللون الرمادي، وسيؤدي النقر عليه إلى فتح قائمة السياق بدلاً من تشغيل الإجراء.
أماكن إقامة
-
الدالة الإنشائية
void
تبدو الدالة
constructor
على النحو التالي:(arg: ShowPageAction) => {...}
-
وسيطة
-
returns
-
فعاليات
onPageChanged
توفّر واجهة برمجة التطبيقات للحدث البيان التي تتكوَّن من addRules
وremoveRules
وgetRules
.