Référence avancée · Avancé
Syntaxe des filtres réseau
Utilisez le sous-ensemble vérifié de règles réseau et comprenez exceptions, périmètres et lignes refusées.
Vue d’ensemble
Shield accepte un sous-ensemble encadré du langage de filtres commun à de nombreuses listes de blocage. Il ignore toute ligne qu’il ne peut pas représenter fidèlement. Retirer une option inconnue pour qu’une ligne passe peut en changer le sens ; consultez plutôt l’aperçu.
Les exemples ci-dessous utilisent des domaines d’exemple réservés. Ils décrivent le comportement des règles, pas des règles à installer pour un vrai service. Ajoutez une ligne à la fois dans Vos règles, vérifiez sa portée et n’appliquez que la modification voulue.
Syntaxe
Motifs d’URL
Faites défiler horizontalement pour lire tout le tableau.
| Objectif | Syntaxe et exemple | Effet attendu et limites |
|---|---|---|
| Correspondre à un hôte | ||ads.example^ |
Correspond à cet hôte et à ses sous-domaines à la limite du nom d’hôte ; ne correspond pas à notads.example. Une règle sans type vise les requêtes ordinaires, pas la navigation de la page principale. |
| Ancrer une URL | |https://cdn.example/ads.js| |
Exige que l’URL commence et se termine à ces positions. Un changement de schéma, de chemin ou de requête peut empêcher la correspondance. |
| Correspondre à une partie d’URL | /ad/image/*$image |
Correspond aux URL de requêtes d’images contenant le chemin indiqué suivi d’un texte variable. Le joker final la distingue d’une expression régulière délimitée par des barres obliques. |
| Utiliser un joker | ||cdn.example/ads/* |
* correspond à un texte variable ; ^ correspond à un séparateur ou à la fin de l’URL. Les motifs à plusieurs jokers ont des limites d’admission et de traitement ; les motifs de taille arbitraire ne sont pas acceptés. |
Les motifs utilisent du texte d’URL en ASCII. N’incluez pas de #fragment : le navigateur n’envoie pas les fragments d’URL dans une requête réseau.
Types, origines et périmètres de sites
Faites défiler horizontalement pour lire tout le tableau.
| Objectif | Exemple | Effet attendu et limites |
|---|---|---|
| Limiter un type de requête | ||ads.example^$script |
S’applique aux scripts. Les autres types sont image, stylesheet, font, media, object, xmlhttprequest, subdocument, document, ping, websocket et other. Les alias incluent css, xhr, frame et doc. |
| Exclure un type | ||ads.example^$~image |
Exclut les images. Une règle uniquement négative exclut toujours les documents principaux ; elle ne devient pas une règle de blocage de page. |
| Inclure tous les types | ||ads.example^$all |
Inclut explicitement les documents principaux. $all,~script inclut les autres types modélisés. À utiliser avec prudence. |
| Limiter l’origine | ||ads.example^$third-party |
S’applique quand la requête est tierce par rapport au site qui la lance. 3p est un alias ; first-party, 1p, ~third-party et ~3p sélectionnent les requêtes propriétaires. |
| Limiter le site à l’origine de la requête | ||ads.example^$domain=news.example |
Limite la correspondance aux requêtes lancées par cet hôte. Des hôtes d’origine exclus peuvent être ajoutés comme ci-dessous. Les jokers d’entité dans les périmètres réseau $domain= sont refusés. |
Un périmètre d’inclusion et d’exclusion utilise | entre les noms d’hôtes et ~ devant un hôte exclu :
||ads.example^$domain=news.example|~pay.news.example
Exceptions et priorité
@@||ads.example^$script,domain=shop.example autorise les requêtes de script correspondantes lancées par le site indiqué. Elle ne met pas en pause toute la protection sur ce site.
Une exception ordinaire correspondante l’emporte sur un blocage ordinaire. Un blocage $important l’emporte sur une exception ordinaire ; une exception portant $important l’emporte sur ce blocage important. Un texte qui paraît plus précis ne constitue pas un système de priorité général.
Pour une exception de page entière, @@||shop.example^$document désactive la protection pour la page principale correspondante et ce qu’elle charge. Cette forme ne peut pas ajouter de condition d’origine, de périmètre de domaine d’origine, de types de ressources supplémentaires ni $all. Un $document sans exception est un blocage du document principal, pas une pause.
@@||news.example^$generichide arrête le masquage cosmétique général sur cet hôte. Les règles cosmétiques propres au site et le blocage des requêtes restent disponibles. Seule une exception sur une ancre d’hôte pure est acceptée ; les chemins, conditions d’origine et autres périmètres de type ne sont pas repris dans cette forme réservée aux hôtes.
Destinations des pop-ups
||popups.example^$popup correspond aux destinations de navigation des pop-ups via le gestionnaire de pop-ups de Shield. @@||accounts.example^$popup,domain=shop.example est une exception de pop-up limitée à un périmètre. Ce ne sont pas des règles de requêtes de script, et elles ne configurent pas le bloqueur de pop-ups intégré au navigateur.
Ne combinez pas $popup avec des types de requêtes, $all, $generichide ou une action de redirection : une seule ligne ne peut pas représenter les deux périmètres. Pour un problème de fenêtre de connexion, commencez par fenêtres de connexion et de paiement.
Fichiers hosts et blocs conditionnels
Les entrées hosts canoniques utilisant les adresses puits 0.0.0.0, 127.0.0.1, ::1, :: ou 0 sont converties en règles d’ancre d’hôte. Par exemple, 0.0.0.0 ads.example devient l’équivalent de ||ads.example^. Les autres formes réseau séparées par des espaces sont refusées.
Les listes peuvent utiliser !#if, !#else et !#endif imbriqués avec !, &&, || et des parenthèses. Les conditions sont évaluées pour la cible de paquet de Shield. Les conditions communes reconnues comme vraies incluent true, env_mv3 et cap_user_stylesheet ; env_chromium et env_firefox dépendent de la cible. Les constantes inconnues sont évaluées comme fausses. Ces directives sélectionnent des branches de la liste, pas des conditions de la page en direct.
Redirections inertes
Un ensemble fermé de ressources est accepté : redirect=noopjs ou redirect=noop.js fournit un script vide ; redirect=nooptext ou redirect=noop.txt fournit un texte vide ; redirect=noopjson fournit {}. Par exemple, ||ads.example/tracker.js$script,redirect=noopjs remplace le script par le script inerte quand la règle l’emporte.
Il s’agit de substitutions intégrées au paquet, pas de redirections vers des URL quelconques ni d’émulations complètes d’une bibliothèque tierce. Les noms de ressources inconnus et les actions de redirection sur des règles d’exception sont refusés. Un blocage strict concurrent de même priorité peut l’emporter sur une redirection.
Limites
Les filtres réseau en expression régulière, removeparam, csp, badfilter, redirect-rule et les modificateurs inconnus sont refusés sur toute la ligne. Cette référence ne promet pas la compatibilité avec toutes les fonctions d’EasyList, d’uBlock Origin ou d’AdGuard. L’absence d’une syntaxe ici ne prouve pas qu’elle a été testée puis refusée.
Les règles acceptées peuvent malgré tout dépasser la capacité du navigateur ou être neutralisées par des réglages de protection et des exceptions. Vérifiez l’aperçu et l’état de la protection ; une règle configurée ne prouve pas son effet sur la page.
Exemples
Une paire ciblée de blocage et d’exception :
||ads.example^$script,third-party
@@||ads.example^$script,domain=checkout.example
La première bloque les scripts tiers correspondants. La seconde autorise les requêtes de script correspondantes lancées par checkout.example. Après rechargement, testez le parcours réel du site ; une requête autorisée peut aussi laisser passer de la publicité ou du pistage.