مرجع متقدم · متقدم
إصلاحات الصفحة والبرامج النصية المساعدة
تعرّف إلى إصلاحات الصفحة المضمّنة وصياغة البرامج النصية المساعدة. ولا تنفّذ حزم Shield AdBlock 1.0.2 هذه الصياغة من القوائم المضافة أو القواعد المخصصة.
نظرة عامة
تستخدم إصلاحات الصفحة أدوات مساعدة صغيرة مضمّنة مع Shield لتغيير سلوك محدد بدقة في الصفحة. يستطيع الفلتر اختيار أداة مساعدة مدعومة ووسائطها؛ لكنه لا يستطيع توفير شيفرة JavaScript جديدة لينزّلها Shield ويشغّلها.
يتحكم مفتاح إصلاحات الصفحة بالإصلاحات المضمّنة. وتبقى هذه الإصلاحات المضمّنة إعدادًا منفصلًا، وتستمر في استخدام الأدوات المساعدة المضمّنة مع Shield. لا تتضمن حزم Shield AdBlock 1.0.2 إصلاحات من المصادر المضافة ولا البرامج النصية المساعدة من القواعد التي تكتبها، على Chrome وEdge وFirefox. يمكن أن تُظهر إعدادات متقدمة أدوات متقدمة، وإظهارها لا يضيف تلك الفئة غير الموجودة في الحزمة.
تتضمن حزم 1.0.2 هذه الإصلاحات المضمّنة، ولا تتضمن فئة البرامج النصية المساعدة من القوائم المضافة أو القواعد المخصصة. وقد يظل المحتوى المضمّن من مواقع أخرى دون تغيير، حتى إذا عمل إصلاح مضمّن في الصفحة الرئيسية.
الصياغة
تعرض أمثلة هذا الدليل صياغة الفلاتر. وهي ليست برامج نصية مساعدة تُنفَّذ من القوائم المضافة أو القواعد المخصصة في حزم Shield AdBlock 1.0.2. وتستمر إصلاحات الصفحة المضمّنة في استخدام الأدوات المساعدة المضمّنة عندما يكون ذلك الإعداد مفعّلًا.
استخدم صيغة مقيدة بمضيف، مثل:
news.example##+js(set-constant, adBlockDetected, false)
تطلب هذه الصيغة الأداة المساعدة المضمّنة set-constant لذلك الموقع. وهي ليست شيفرة JavaScript أو CSS أو ضمانًا بأن الموقع يستخدم تلك الخاصية. تُفصل الوسائط بفواصل؛ وتُعامل الفاصلة المُهربة كنص حرفي، وتُزال طبقة واحدة من علامتي اقتباس خارجيتين متطابقتين.
الأدوات المساعدة الحالية
يتعرف هذا الإصدار إلى الأسماء الأساسية العشرة التالية. لا تشمل نطاقات الوسائط اسم الأداة المساعدة. تعرض الأمثلة الاستدعاء داخل +js(...)؛ وأضف لكل منها نطاق موقع مقصودًا، مثل news.example##.
مرّر أفقيًا لقراءة الجدول كاملًا.
| الأداة المساعدة وأسماؤها البديلة | الغرض والوسائط | المثال | الأثر المتوقع والحدود |
|---|---|---|---|
set-constant؛ set |
ضبط خاصية ذات مسار منقّط على قيمة واحدة مسموحة؛ بالضبط 2 من الوسائط. | +js(set-constant, adBlockDetected, false) |
يثبت سلوك الثابت المدعوم. تُرفض السلاسل النصية العشوائية والشيفرة والأعداد غير المحدودة. |
abort-current-script؛ acs، abort-current-inline-script، acis |
إيقاف برنامج نصي حالي عند الوصول إلى خاصية؛ الخاصية مع نصين اختياريين للمطابقة في المحتوى والمصدر، 1–3 من الوسائط. | +js(abort-current-script, adblock) |
يؤثر في وصول البرنامج النصي المطابق، لا في كل برامج الصفحة. يجب أن تكون نصوص المطابقة حرفية. |
abort-on-property-read؛ aopr |
إيقاف الشيفرة عند قراءة خاصية؛ بالضبط 1 من الوسائط. | +js(abort-on-property-read, adblock) |
يؤثر في سلسلة الخصائص المحددة، التي يجب أن تكون مسار معرّفات منقّطًا بسيطًا. |
abort-on-property-write؛ aopw |
إيقاف الشيفرة عند الكتابة إلى خاصية؛ بالضبط 1 من الوسائط. | +js(abort-on-property-write, antiAdblock.write) |
يستهدف سلسلة الخصائص تلك؛ وقد يعطّل شيفرة مشروعة تكتب إليها. |
prevent-addEventListener؛ aeld، addEventListener-defuser |
منع تسجيل مستمع مطابق؛ نصان حرفيان للحدث ومصدر المعالج، بالضبط 2 من الوسائط. | +js(prevent-addEventListener, click, antiAdblock) |
يجب أن يتطابق الشرطان. لا يمكن لشروط فارغة أو شروط ! جعل الطلب كله غير مشروط؛ وتُرفض التعبيرات النمطية والخيارات الإضافية من الصيغ الأصلية. |
prevent-fetch؛ no-fetch-if |
منع عمليات الجلب المطابقة من الصفحة؛ شرط مع رمز استجابة اختياري، 1–2 من الوسائط. | +js(prevent-fetch, url:ads method:POST, emptyObj) |
يطابق كل الشروط الحرفية المقدمة ويوفّر الاستجابة الفارغة المختارة. ولا يلغي كل أنواع الطلبات على مستوى المتصفح. |
prevent-xhr؛ no-xhr-if |
منع طلبات XMLHttpRequests المطابقة؛ شرط مع رمز استجابة اختياري، 1–2 من الوسائط. | +js(prevent-xhr, url:collect method:POST, emptyArr) |
يستخدم شروط العنوان وطريقة الطلب؛ وتُرفض شروط mode: الخاصة بالجلب فقط. |
json-prune |
إزالة خصائص JSON؛ مسارات الحذف مع مسارات مطلوبة اختيارية، 1–2 من الوسائط. | +js(json-prune, payload.secret, payload.ready) |
يحذف من بنية JSON المطابقة عندما توجد المسارات المطلوبة. هذه لغة مسارات محدودة، وليست JSONPath عشوائية. |
prevent-window-open؛ nowoif، no-window-open-if، window.open-defuser |
منع استدعاءات window.open المطابقة؛ 0–1 من الوسائط الحرفية. |
+js(prevent-window-open) |
دون شرط، يمنع الاستدعاءات ضمن النطاق المؤهل. يمكن للمطابقة الحرفية فحص وسائط الاستدعاء المجمّعة، لا العنوان وحده؛ وتُرفض خيارات الاستبدال والتأخير. |
prevent-setTimeout؛ nostif، no-setTimeout-if، setTimeout-defuser |
منع المؤقتات المطابقة؛ نص مطابقة اختياري لدالة الاستدعاء اللاحق وتأخير اختياري، 0–2 من الوسائط. | +js(prevent-setTimeout, adRefresh, 1000) |
يطابق نص دالة الاستدعاء اللاحق والتأخير المحدد. يجب أن يكون التأخير عددًا منتهيًا؛ وتُرفض وسائط التعبيرات النمطية والخيارات الإضافية. |
قد تنتهي الأسماء الأساسية والبديلة أيضًا باللاحقة .js. فضّل الأسماء الأساسية في القواعد الجديدة ليسهل فهم المقصود.
حدود الوسائط
تقبل أدوات الخصائص المساعدة معرّفات منقّطة، لا تعبيرات الأقواس أو استدعاءات الدوال أو السلاسل التي تصل إلى النموذج الأولي. تقبل set-constant القيم المسماة undefined وfalse وtrue وnull وnoopFunc وtrueFunc وfalseFunc وnoopPromiseResolve وnoopPromiseReject وemptyObj وemptyArr، والصيغ الفارغة المدعومة، والأعداد الصحيحة من −32767 إلى 32767.
تقبل أدوات الطلبات المساعدة شروطًا حرفية محدودة تفصل بينها مسافات. أسماء الحقول هي url وmethod، وللجلب فقط mode. الشرط المجرد جزء من عنوان. ويتاح النفي باستخدام !؛ ويجب أن تتطابق كل الشروط. رموز الاستجابة هي النص الفارغ الافتراضي وemptyStr وemptyObj وemptyArr. تُرفض الحقول أو رموز الاستجابة غير المعروفة.
يستخدم حذف خصائص JSON مسارات منقّطة تفصل بينها مسافات. ويمكن أن تتضمن أجزاؤها المحدودة صيغ * و[] و[-] و{-} المدعومة، مع قيود على الموضع والعمل. وتُرفض المسارات التي تصل إلى النموذج الأولي. فضّل مسارًا مسمى بسيطًا ما لم تتحقق من البنية المتداخلة بدقة والأثر المطلوب.
الحدود
التعرف إلى اسم البرنامج النصي المساعد لا يكفي لتشغيل القاعدة. يجب أن تتأهل جميع شروط عدد الوسائط وصياغتها ونطاق الموقع والمفاتيح، ويجب أن تتضمن الحزمة تلك الفئة. لا تتضمن حزم Shield AdBlock 1.0.2 البرامج النصية المساعدة من القوائم المضافة أو القواعد المخصصة، لذا لا تُنفَّذ قاعدة تطابق هذه الصياغة من قائمة أضفتها أو قاعدة كتبتها. تتسبب وسائط التعبيرات النمطية والأسماء غير المعروفة والخيارات الإضافية غير المدعومة في تجاوز القاعدة كاملة. لا تُقبل صياغة AdGuard #%# للبرامج النصية المساعدة بديلًا عن ##+js(...).
للإصلاحات المضمّنة حالة أهلية وتسجيل خاصة بها. نجاح الإعداد أو التسجيل لا يثبت أن الأداة المساعدة نُفّذت أو اعترضت الاستدعاء المقصود أو أزالت إعلانًا مرئيًا. ولا تضمن أي أداة إزالة إعلانات يوتيوب أو التوافق مع كل إصدارات البرامج النصية المساعدة لحاجب آخر.
أمثلة
لتعطيل أداة مساعدة مسماة على موقع، استخدم استثناءً لبرنامج نصي مساعد:
news.example#@#+js(set-constant)
يعطّل الاستثناء الذي يتضمن الاسم فقط تلك الأداة ضمن النطاق المطابق. أما news.example#@#+js() فهو استثناء أوسع لكل البرامج النصية المساعدة. ولا تعطّل هذه الاستثناءات قواعد الشبكة أو إخفاء العناصر. راجع الاستثناءات بالعناية نفسها التي تراجع بها الاستدعاءات، وأعد تحميل الموقع بعد التغيير.