Page Shadow - Guide de la syntaxe des filtres

Cette documentation n'est applicable qu'à la version 2.11 de Page Shadow

Les règles de filtre permettent de corriger l'affichage des sites web lorsque les fonctions Augmenter le contraste et/ou Inverser les couleurs sont activées. Les corrections peuvent porter sur la désactivation de la modification du style d'un élément (couleur d'arrière-plan, couleur des textes ou des liens, inversion de la couleur) ou le fait de forcer un style sur un élément. Ces règles permettent par exemple de corriger l'affichage de certains éléments qui n'apparaissent pas. Il vous est possible d'écrire vos propres règles de filtre. Si vous avez des connaissances en HTML/CSS, c'est assez simple. Dans un fichier de filtre, une seule règle par ligne est possible.

Vous pouvez utiliser l'éditeur interne à l'extension (Filtres > Éditer mon filtre) qui dispose de la coloration syntaxique adaptée et qui auto-complète automatiquement les règles que vous écrivez.

Syntaxe

La syntaxe d'un filtre est de la forme suivante : siteOuPageWeb[1]|regle[2]|selecteurCss ou paramètre[3]

Chaque partie du filtre est divisée par un caractère | (barre verticale).

[1] siteOuPageWeb

La première partie de la règle (siteOuPageWeb) indique le site web/la page web sur laquelle le filtre doit être appliqué. Cette partie peut être de la forme suivante :

  • Un domaine : par exemple eliastiksofts.com ou www.eliastiksofts.com (ces deux domaines sont traités séparément)
  • Une page web : par exemple https://www.eliastiksofts.com/fr/page-shadow/filters/guide/index.php
  • Une règle avec jokers (peut matcher un domaine ou une page web) : par exemple *eliastiksofts.com/en/* matche toutes les pages du site Eliastik's Softs en version anglaise
  • Une expression régulière (peut matcher un domaine ou une page web) : par exemple /(.*)google.(.*)recaptcha(.*)/ matche les Google ReCaptcha

[2] regle

Cette partie du filtre correspond à la règle en elle-même. Il existe plusieurs règles différentes qui sont reconnues par l'extension :

Règles standard
  • disableContrastFor : désactive complètement la fonction Augmenter le contraste pour un ou plusieurs éléments
  • forceTransparentBackground : force un arrière-plan transparent pour un ou plusieurs éléments
  • disableBackgroundStylingFor : désactive la coloration de l'arrière-plan par la fonction Augmenter le contraste pour un ou plusieurs éléments
  • disableTextColorStylingFor : désactive la coloration des textes par la fonction Augmenter le contraste pour un ou plusieurs éléments
  • disableInputBorderStylingFor : désactive la coloration de la bordure des champs de formulaire par la fonction Augmenter le contraste pour un ou plusieurs éléments
  • disableLinkStylingFor : désactive la coloration des liens par la fonction Augmenter le contraste pour un ou plusieurs éléments
  • disableFontFamilyStylingFor : désactive la modification de la police de caractères (thèmes personnalisés) par la fonction Augmenter le contraste pour un ou plusieurs éléments
  • disableElementInvertFor : désactive l'inversion des couleurs par la fonction Inverser les couleurs pour un ou plusieurs éléments
  • hasBackgroundImg : indique à Page Shadow qu'un ou plusieurs éléments ont une image d'arrière-plan
  • forceCustomLinkColorFor : force la modification de la couleur des liens par la fonction Augmenter le contraste pour un ou plusieurs éléments
  • forceCustomBackgroundColorFor : force la modification de la couleur d'arrière-plan par la fonction Augmenter le contraste pour un ou plusieurs éléments
  • forceCustomTextColorFor : force la modification de la couleur des textes par la fonction Augmenter le contraste pour un ou plusieurs éléments
  • disableShadowRootsCustomStyle : force la désactivation des styles des Shadow Roots par la fonction Augmenter le contraste pour un ou plusieurs éléments
  • forceCustomVisitedLinkColor : force la modification de la couleur des liens visités pour un ou plusieurs éléments
  • disableCustomVisitedLinkColor : désactive la modification de la couleur des liens visités pour un ou plusieurs éléments
  • forceFontFamilyStylingFor : force la police de caractère personnalisée pour les thèmes personnalisés pour un ou plusieurs éléments
  • forceInputBorderStylingFor : force l'affichage d'une bordure pour un ou plusieurs champs de formulaire
  • forceCustomLinkColorAsBackground : met la couleur d'arrière-plan d'un ou plusieurs éléments à celle des liens du thème
  • forceCustomTextColorAsBackground : met la couleur d'arrière-plan d'un ou plusieurs éléments à celle des textes du thème
  • forceCustomLinkVisitedColorAsBackground : met la couleur d'arrière-plan d'un ou plusieurs éléments à celle des liens visités du thème
  • forceDisableDefaultBackgroundColor : force la désactivation de la couleur d'arrière-plan par défaut d'un ou plusieurs éléments, à utiliser en dernier recours
  • forceDisableDefaultBackground : force la désactivation de l'arrière-plan par défaut d'un ou plusieurs éléments, à utiliser en dernier recours
  • forceDisableDefaultFontColor : force la désactivation de la police de caractères par défaut d'un ou plusieurs éléments, à utiliser en dernier recours
  • enablePseudoElementsStyling : active la modification du style des pseudo-éléments CSS :after et :before par l'extension pour un ou plusieurs éléments, désactivé par défaut
  • overrideShadowRootsCustomStyle : même règle que disableShadowRootsCustomStyle
  • invertElementAsImage : active l'inversion des couleurs d'un ou plusieurs éléments en tant qu'image
  • invertElementAsVideo : active l'inversion des couleurs d'un ou plusieurs éléments en tant que vidéo
  • invertElementAsBackground : active l'inversion des couleurs d'un ou plusieurs éléments en tant qu'image d'arrière-plan
  • enableSelectiveInvert : active l'inversion sélective pour un ou plusieurs éléments
  • enablePseudoElementSelectiveInvert : active l'inversion sélective pour un ou plusieurs pseudo-éléments
  • invertPseudoElement : active l'inversion des couleurs pour un ou plusieurs pseudo-éléments
  • forcePseudoElementsTransparentBackground : force un fond transparent sur un ou plusieurs pseudo-éléments d'un élément
  • preserveBrightColor : indique à Page Shadow qu'un ou plusieurs éléments ont un fond/texte de couleur vive, et les considère comme tel
  • hasBrightColorWithWhiteText/hasBrightColorWithBlackText : si un élément est détecté en tant qu'élément ayant un fond de couleur vive (que ce soit automatiquement, ou via le filtre preserveBrightColor), affiche le texte en noir ou blanc de manière forcée.
Règles spéciales

Ces règles modifient la façon dont Page Shadow fonctionne de manière interne. Elles permettent d'activer ou désactiver certaines fonctionnalités.

  • enablePerformanceMode : active le mode performance pour le site ou la page web. Cette règle ne nécessite pas de sélecteur CSS. Cela revient à désactiver la détection des images d'arrière-plan et à activer les règles disableTransparentBackgroundAutoDetect, disableMutationObserversForSubChilds, disableMutationObserverAttributes, disableMutationObserverClass, disableMutationObserverStyle et disableShadowRootStyleOverride. Cela peut donc causer des problèmes d'affichage sur certains sites avec la fonction Augmenter le contraste (qui peuvent être compensés avec les règles standard sur les éléments mal affichés).
  • disablePerformanceMode : désactive le mode performance pour le site ou la page web. Règle destinée à être combinée avec la règle enablePerformanceMode pour activer par exemple le mode performance pour le site web globalement et pour le désactiver pour quelques pages.
  • disableTransparentBackgroundAutoDetect : désactive la détection automatique des arrières-plan transparents, n'améliore pas les performances lorsque désactivé seul
  • enableTransparentBackgroundAutoDetect : active la détection automatique des arrières-plan transparents (cette fonctionnalité est activée de base par défaut)
  • opacityDetectedAsTransparentThreshold : paramètre la limite pour laquelle la fonction de détection automatique des arrières-plan transparents traite une opacité comme étant un arrière-plan transparent (par défaut toute opacité inférieure ou égale à 0.1 est traitée comme un fond transparent)
  • enableMutationObserversForSubChilds : lorsque activé, l'extension parcourera tous les sous-éléments d'un élément ajouté à la page (activé par défaut)
  • disableMutationObserversForSubChilds : désactive le parcours de tous les sous-éléments d'un élément ajouté à la page, peut améliorer les performances mais peut causer des problèmes d'affichage
  • enableMutationObserverAttributes : active la détection des mutations d'attributs (style ou class en HTML), activé par défaut
  • disableMutationObserverAttributes : désactive la détection des mutations d'attributs, peut améliorer les performances
  • enableMutationObserverClass : active la détection des mutations de l'attribut HTML class (désactivé par défaut)
  • disableMutationObserverClass : désative la détection des mutations de l'attribut HTML class, peut améliorer les performances
  • enableMutationObserverStyle : active la détection des mutations de l'attribut HTML style (activé par défaut)
  • disableMutationObserverStyle : désactive la détection des mutations de l'attribut HTML style, peut améliorer les performances
  • enableShadowRootStyleOverride : active l'écrasement des styles par défaut des éléments Shadow Roots (activé par défaut)
  • disableShadowRootStyleOverride : désactive l'écrasement des styles par défaut des éléments Shadow Roots, peut améliorer les performances sur les sites qui utilisent cette fonctionnalité
  • shadowRootStyleOverrideDelay : paramètre le délai (par défaut 100 ms) nécessaire avant d'analyser un élement qui contient un Shadow Root pour améliorer leur détection, indiquer un délai inférieur ou égal à 0 désactive cette fonctionnalité
  • enableThrottleMutationObserverBackgrounds : active le ralentissement du traitement des Mutation Observers, améliore considérablement les performances. Désactivé par défaut
  • disableThrottleMutationObserverBackgrounds : désactive le ralentissement du traitement des Mutation Observers
  • delayMutationObserverBackgrounds : délai en ms appliqué au traitement des Mutation Observers lorsque la règle enableThrottleMutationObserverBackgrounds est activée. Par défaut 0, ce qui signifie que les mutations sont traitées dès que possible
  • throttledMutationObserverTreatedByCall : nombre de mutations à traiter à chaque appel, par défaut 50. Un nombre élevé réduit les performances.
  • delayApplyMutationObserversSafeTimer : délai avant de réappliquer les paramètres de Page Shadow après une détection par Mutation Observers
  • enableObserveBodyChange/disableObserveBodyChange : observe le changement d'état de l'élément body (suppression puis création d'un nouvel élément body). Corrige des problèmes avec certains sites web (comme Github) ou applications SPA. Désactiver cette option peut améliorer les performances
  • observeBodyChangeTimerInterval : l'observation du changement d'état de l'élément body s'appuie sur un timer qui s'exécute à un intervalle donné (au lieu d'utiliser les Mutation Observer). L'intervalle est en ms
  • enableBrightColorDetection/disableBrightColorDetection : détecte les éléments avec des couleurs vives et, si l'option est activée par l'utilisateur, désactive la fonction Augmenter le contraste pour ces éléments. La désactivation de cette option peut améliorer les performances
  • brightColorLightnessTresholdMin : si un élément a une valeur de luminosité supérieure à ce seuil et inférieure à la valeur maximum, l'élément sera détecté comme élément de couleur vive
  • brightColorLightnessTresholdMax : si un élément a une valeur de luminosité inférieure à ce seuil et supérieure à la valeur minimum, l'élément sera détecté comme élément de couleur vive
  • enableThrottleBackgroundDetection/disableThrottleBackgroundDetection : applique un délai à la détection des arrière-plans au chargement des pages, ce qui permet d'améliorer les performances sur les grandes pages
  • throttleBackgroundDetectionElementsTreatedByCall : défini le nombre d'éléments traités par chaque appel de boucle lorsque la détection des arrière-plans est ralentie. Une valeur élevée peut impacter les performances
  • backgroundDetectionStartDelay : applique un délai avant d'appliquer le traitement de l'arrière-plan des éléments. Par défaut 1 ms.
  • useBackgroundDetectionAlreadyProcessedNodes : utilise une liste d'éléments déjà traités pour le traitement des arrière-plans pour éviter de traiter à nouveau les mêmes éléments. Peut améliorer les performances, mais peut augmenter l'utilisation de la mémoire.
  • enableBrightColorDetectionSubelement/disableBrightColorDetectionSubelement : active ou désactive le traitement des sous-éléments des éléments avec couleurs vives. Désactiver cette option peut potentiellement améliorer les performances, mais des problèmes d'affichage peuvent se produire sur certains sites en utilisant la fonction de préservation des éléments avec couleurs vives
  • observeDocumentChange : observe le changement d'état du document (élément HTML), et plus particulièrement de l'attribut style. Corrige des problèmes avec certains sites web qui écrasent la valeur de l'attribut style qui est utilisée pour gérer les variables CSS de Page Shadow. Désactiver cette option peut améliorer les performances.
  • observeDocumentChangeTimerInterval : l'observation du changement d'état du document (élément HTML) s'appuie sur un timer qui s'exécute à un intervalle donné (au lieu d'utiliser les Mutation Observer). L'intervalle est en ms.
  • enableDarkImageDetection/disableDarkImageDetection : active ou désactive la détection des images/arrières-plans comportant un grand nombre de couleurs sombres (comme par exemple les textes et logos), afin d'inverser leurs couleurs si le paramètre Inverser les couleurs > Sélectif est activé par l'utilisateur. Désactiver cette option améliore les performances.
  • darkImageDetectionHslTreshold : si un pixel a une valeur de luminosité inférieure à ce seuil, le pixel sera considéré comme sombre. La valeur maximale est 1, la valeur minimale est 0 (pourcentage).
  • brightColorLightnessTresholdTextMin : pareil que brightColorLightnessTresholdMin, mais ne s'applique qu'aux éléments textuels.
  • brightColorSaturationTresholdMin : valeur de saturation (dans l'espace de couleur HSL) minimum afin de détecter un texte comme ayant une couleur vive.
  • enableNotMatchingFiltersDetection/disableNotMatchingFiltersDetection : si un élément ne correspond plus à l'un des filtres qui lui a été appliqué précédemment, le filtre est retiré de l'élément. Activer cette option peut réduire les performances et augmenter la consommation de mémoire, car Page Shadow doit stocker les informations sur les éléments qui correspondaient précédemment à un filtre donné.
  • intervalApplyClassChanges : paramètre l'intervalle (en ms) des changements des classes CSS sur les éléments. Augmenter l'intervalle peut améliorer les performances.
  • classChangeMaxElementsTreatedByCall : nombre d'éléments traités (changement de classes CSS) à chaque intervalle. Augmenter ce nombre peut réduire les performances.
  • darkImageDetectionMinAlpha : la valeur minimale (en pourcentage) du canal alpha nécessaire pour analyser le pixel d'une image. Si la valeur est sous ce seuil, le pixel est ignoré. Par défaut 0.5 (pour 50%).
  • darkImageDetectionBlockSize : lorsqu'un pixel est détecté comme étant sombre selon la valeur de luminosité, son voisinnage est analysé à la recherche de pixels transparents. Cette valeur paramètre le nombre de pixels à analyser autour du pixel détecté.
  • darkImageDetectionTransparentPixelsRatio : lors de l'analyse du voisinnage du pixel détecté comme étant sombre, paramètre le ratio minimum de pixels transparents nécessaires. Si ce ratio est dépassé, alors l'image est détectée comme étant une image sombre.
  • darkImageDetectionDarkPixelsRatio : lors de l'analyse du voisinnage du pixel détecté comme étant sombre, paramètre le ratio minimum de pixels sombres supplémentaires nécessaires (par rapport aux pixels non transparents). Si ce ratio est dépassé, alors l'image est détectée comme étant une image sombre.
  • enableThrottleDarkImageDetection/disableThrottleDarkImageDetection : active ou désactive le ralentissement de l'analyse des images des pages web.
  • throttleDarkImageDetectionDelay : paramètre le délai (en ms) avant d'exécuter l'analyse des images mises en file d'attente. Augmenter ce délai peut améliorer les performances.
  • throttleDarkImageDetectionBatchSize : paramètre le nombre d'images en file d'attente à analyser en une fois.
  • enableThrottleMutationObserverBackgroundsSubChilds/disableThrottleMutationObserverBackgroundsSubChilds : active ou désactive le ralentissement de l'analyse des sous-enfants d'un élément détecté par Mutation Observers.
  • delayMutationObserverBackgroundsSubchilds : paramètre le délai (en ms) avant d'exécuter l'analyse des sous-enfants d'un élément. Augmenter ce délai peut améliorer les performances.
  • throttledMutationObserverSubchildsTreatedByCall : paramètre le nombre de sous-enfants en file d'attente à analyser en une fois.
  • delayApplyClassChanges : applique un délai supplémentaire (en ms) avant le changement des classes CSS sur les éléments. Augmenter le délai peut améliorer les performances.
  • throttleBackgroundDetectionMaxExecutionTime : si l'exécution de l'appel (analyse des éléments) dépasse ce temps d'exécution (en ms), l'appel est interrompu pour libérer des ressources. Cela améliore considérablement les performances.
  • throttleDarkImageDetectionMaxExecutionTime : si l'exécution de l'appel (analyse des images) dépasse ce temps d'exécution (en ms), l'appel est interrompu pour libérer des ressources. Cela améliore considérablement les performances.
  • throttledMutationObserverMaxExecutionTime : si l'exécution de l'appel (mutation observers) dépasse ce temps d'exécution (en ms), l'appel est interrompu pour libérer des ressources. Cela améliore considérablement les performances.
  • throttledMutationObserverSubchildsMaxExecutionTime : si l'exécution de l'appel (analyse des sous-enfants d'un élément) dépasse ce temps d'exécution (en ms), l'appel est interrompu pour libérer des ressources. Cela améliore considérablement les performances.
  • applyClassChangesMaxExecutionTime : si l'exécution de l'appel (changement des classes CSS des éléments) dépasse ce temps d'exécution (en ms), l'appel est interrompu pour libérer des ressources. Cela améliore considérablement les performances.
  • autoThrottleBackgroundDetectionTime : si le ralentissement de l'analyse des arrières-plans n'est pas activé, il est activé automatiquement si le temps d'exécution dépasse cette valeur (en ms). Cela permet d'éviter de bloquer les pages web si le temps d'exécution initial de l'analyse est trop long.
  • enableThrottleApplyClassChanges/disableThrottleApplyClassChanges : action ou désactive le ralentissement de l'application par Page Shadow des changements de classes CSS aux éléments. Cela peut améliorer les performances dans certains scénarios.
  • enableURLChangeDetection/disableURLChangeDetection : active ou désactive la détection du changement d'adresse URL sur les applications SPA (single page application), ce qui permet à Page Shadow de réappliquer les paramètres et filtres selon la nouvelle URL. Désactiver cette option peut améliorer les performances sur certains sites web qui modifient souvent leur URL.

Il est possible d'indiquer plusieurs règles du même type en les séparant par une virugle. Le nom des règles est sensible à la casse.

[3] selecteurCss ou paramètre

Cette partie du filtre contient le sélecteur CSS correspondant aux éléments sur lesquels appliquer le filtre. Il est possible de spécifier plusieurs sélecteurs en les séparant par une virgule. Si le sélecteur n'est pas valide, la règle sera ignorée. Le sélecteur CSS est traité par la fonction document.querySelectorAll au sein du code de l'extension. Pour la liste complète des sélecteurs CSS disponibles, rendez-vous sur la documentation MDN.

Cette partie peut aussi correspondre à un paramètre qui n'est pas un sélecteur CSS, par exemple certaines règles spéciales comme les règles suivantes nécessitent un paramètre (par exemple un nombre) : opacityDetectedAsTransparentThreshold, shadowRootStyleOverrideDelay, delayMutationObserverBackgrounds, autoThrottleMutationObserverBackgroundsTreshold, throttledMutationObserverTreatedByCall, delayApplyMutationObserversSafeTimer, observeBodyChangeTimerInterval, brightColorLightnessTresholdMin, brightColorLightnessTresholdMax, throttleBackgroundDetectionElementsTreatedByCall, observeDocumentChangeTimerInterval, darkImageDetectionHslTreshold, darkImageDetectionDarkPixelCountTreshold, brightColorLightnessTresholdTextMin, brightColorSaturationTresholdMin, intervalApplyClassChanges, classChangeMaxElementsTreatedByCall, darkImageDetectionMinAlpha, darkImageDetectionBlockSize, darkImageDetectionTransparentPixelsRatio, darkImageDetectionDarkPixelsRatio, throttleDarkImageDetectionDelay, throttleDarkImageDetectionBatchSize, delayMutationObserverBackgroundsSubchilds, throttledMutationObserverSubchildsTreatedByCall, delayApplyClassChanges, throttleBackgroundDetectionMaxExecutionTime, throttleDarkImageDetectionMaxExecutionTime, throttledMutationObserverMaxExecutionTime, throttledMutationObserverSubchildsMaxExecutionTime, applyClassChangesMaxExecutionTime et autoThrottleBackgroundDetectionTime. La règle spéciale shadowRootStyleOverrideDelay nécessite aussi un paramètre supplémentaire (le délai en ms).

Exemple de règle

Ce filtre est utilisé pour corriger l'affichage des Google ReCaptcha lorsque la fonction Augmenter le contraste est activé. Elle désactive la fonction pour certains éléments qui étaient cachés.

/(.*)google.(.*)recaptcha(.*)/|disableContrastFor|.rc-imageselect-checkbox,.rc-imageselect-checkbox *,.rc-button-default,.rc-button-default *,.rc-imageselect-candidates,.rc-imageselect-candidates *,.rc-imageselect-desc,.rc-imageselect-desc *

Créer un fichier complet de règles de filtre

Il est possible de créer un fichier complet de filtre. Pour cela, il est nécessaire que le fichier commence avec le code suivant qui contient les méta-données du fichier de filtre :

#! Page Shadow Filter 1.0
#! Name: Titre du filtre
#! Homepage: https://www.pagedaccueildufiltre.com
#! Sourcename: Nom de la source du site (nom du site web ou autre)
#! Version: Version du filtre
#! License: Licence
#! Expires: Nombre de jours correspondant à l'expiration du cache du filtre du côté de l'utilisateur, suivi d'une mise à jour automatique
#! Description: Description du filtre

Il faut ensuite écrire une règle de filtre par ligne.