<access-settings>

Présentation

Presentation

access-settings est un composant web autonome pour ajouter sans effort des options d'accessibilité à votre site web.

access-settings is a standalone web component that makes it easy to add accessibility options to your website.

Il est basé sur une API qu'il est possible d'utiliser indépendamment pour une intégration avancée.

It's built around an API that can be used independently for advanced integration scenarios.

Démarrage rapide

Quick start

Composant web

Web component

Ajouter l'appel du script dans la balise <head> de votre page html :

Add the script tag to the <head> of your HTML page :

<script src="https://cdn.jsdelivr.net/npm/access-settings@1" type="module" ></script>

Puis insérer le composant en fin de balise <body> :

Then insert the component at the end of the <body> tag :

<access-settings all></access-settings>

Et le tour est joué ! Sur la droite de votre écran apparaît l'icône de configuration de vos préférences.

That's it ! A settings icon for configuring your preferences will appear on the right side of your screen.

Pour une utilisation plus avancée, vous pouvez parcourir la suite de cette documentation.

For more advanced usage, continue reading this documentation.

Bookmarklet (βeta)

En tant qu'internaute, vous pouvez utiliser le composant <access-settings> en tant que As a user, you can use the <access-settings> component as a bookmarklet.

Pour cela, faites glisser le bouton suivant jusqu'à votre barre de favoris :

To do this, drag the button below to your bookmarks/favorites bar :

Sur n'importe quelle page web, vous pourrez cliquer sur ce favori pour configuer vos préférences d'accessibilité.

On any webpage, click this bookmark to configure your accessibility preferences.

Avertissement : selon la politique de sécurité de la page visitée ainsi que la qualité du code css, il se peut que le composant ne puisse pas se charger ou ne fonctionne pas correctement.

Warning: Depending on the security policy of the page you're visiting, as well as the quality of the CSS code, the component may fail to load or not work correctly.

API

Vous pouvez aussi utiliser uniquement l'API et gérer vous-même l'interface utilisateur.

You can also use just the API and build your own user interface.

import accessSettings from "https://cdn.jsdelivr.net/npm/access-settings@1/dist/api.min.js"; const checkBox = document.querySelector("#myCheckBox"); checkBox.addEventListener("change", e => { accessSettings.dyslexicFont = e.target.checked; }); Rendu : Preview :

Détails de l'API API reference

Types d'installation

Installation

CDN

Comme indiqué plus haut, l'utilisation d'un serveur CDN est la façon la plus simple et la plus rapide d'installer le composant.

As mentioned above, using a CDN is the easiest and fastest way to install the component.

<!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <title>My accessible page</title> <script src="https://cdn.jsdelivr.net/npm/access-settings@1" type="module" > </script> </head> <body> <access-settings all></access-settings> </body> </html>

NPM

Vous pouvez aussi installer le composant par NPM.

You can also install the component via NPM.

npm install access-settings

Téléchargement direct

Direct download

Ou encore télécharger directement le fichier sur GitHub, ou uniquement l'API.

Alternatively, you can directly download the file from GitHub, or just the API alone.

Options du composant

Component options

all

Pour afficher toutes les options, utiliser l'attribut all.

To display all options, use the attribute all.

<access-settings all></access-settings>

dyslexic-font

Pour activer l'option police dyslexie, utiliser l'attribut dyslexic-font.

To activate the dyslexia font option, use the attribute dyslexic-font.

La police utilisée est Open Dyslexic depuis le serveur CDN|Fonts.

The font used is Open Dyslexic from the CDN|Fonts server.

<access-settings dyslexic-font> </access-settings>

invert-colors

Pour activer l'option d'inversion des couleurs, utiliser l'attribut invert-colors.

To enable the color inversion option, use the attribute invert-colors.

<access-settings invert-colors> </access-settings>

contrast

Pour activer le réglage du contraste, utiliser l'attribut contrast.

To enable contrast setting, use the attribute contrast.

<access-settings contrast> </access-settings>

font-size

Pour activer le réglage de la taille du texte, utiliser l'attribut font-size.

To enable text size setting, use the attribute font-size.

<access-settings font-size> </access-settings>

line-height

Pour activer le réglage de la hauteur de ligne, utiliser l'attribut line-height.

To enable line height setting, use the attribute line-height.

<access-settings line-height> </access-settings>

combinaison

combination

Vous pouvez bien sûr combiner ces options.

You can of course combine these options.

<access-settings contrast font-size line-height> </access-settings>

side="left"

Par défaut le composant est placé sur le bord droit de l'écran. Pour le positionner à gauche, utiliser l'attribut side="left"

By default the component is placed on the right edge of the screen. To position it on the left, use the attribute side="left"

<access-settings all side="left"> </access-settings>

rounded

Pour que le contour de l'icône soit arrondi, utiliser l'attribut rounded

To round the icon outline, use the attribute rounded

<access-settings all rounded>

lang

La langue par défaut est déterminée par l'attribut lang de l'élément racine html. Vous pouvez la surcharger en définissant un attribut lang sur le composant.

Default language is determined by the attribute lang of the root element html. You can override it by setting a lang attribute to the component.

<access-settings all lang="es">

Les langues disponibles sont français (fr), anglais (en) et espagnol (es).

Available languages are French (fr), English (en) and Spanish (es).

important

Pour outrepasser les règles css existantes, ajouter l'attribut important.

To override existing css rules, add the attribute important.

Attention, cette méthode n'est pas conseillée, elle permet juste le bon fonctionnement du composant dans le cas où le css existant ne suit pas les bonnes pratiques et est difficilement modifiable.

Please note that this method is not recommended. It simply allows the component to function properly in cases where the existing CSS does not follow best practices and is difficult to modify.

<access-settings all important>

Personnalisation

Personalization

Ajouter une langue

Add a language

Vous pouvez ajouter la langue de votre choix de la façon suivante.

You can add the language of your choice as follows.

<!DOCTYPE html> <html lang="oc"> import { AccessSettings } from "https://cdn.jsdelivr.net/npm/access-settings@1"; AccessSettings.languages.oc = { "dyslexic-font": "Poliça disléxica", "invert-colors": "Colors invertidas", "contrast": "Contraste", "font-size": "Talha de poliça", "line-height": "Nautor de linha", "reset": "Reïnicializar", "close": "Tampar" };

Position

Vous pouvez définir le positionnement du composant.

You can define the positioning of the component.

accessibility-settings { position:fixed; top:5px; right:5px; }

Si l'attribut side est défini à left, il vous faudra définir la propriété css left plutôt que right.

If the attribute side is defined to left, you will need define the css property left rather than right.

Style de l'icône

Icon style

Vous pouvez personnaliser le style de l'icône en css

You can customize the icon style in css

access-settings::part(icon) { background-color: brown; fill:white; }

Changer d'icône

Change icon

<access-settings all> <span slot="icon">⚙︎</span> </access-settings>

Style des éléments

Elements style

Les pseudo-éléments The pseudo-elements ::part suivants vous permettent de personnaliser entièrement le style du composant : following allow you to fully customize the style of the component :

  • details : element <details>
    • summary : element <summary>
      • icon : element <svg>
    • form : element <form>

Exemple

access-settings::part(line-height) { background-color:violet; } access-settings::part(font-size-label) { font-weight:bold; }

Ajouter des options

Add options

Vous pouvez ajouter des options de la façon suivante :

You can add options as follows

<access-settings all> <div slot="option"> <label> <input type="checkbox" id="custom-input"> Une nouvelle option </label> </div> </access-settings> const input = document.querySelector("#custom-input"); input.addEventListener("change", () => { if (input.checked) alert("nouvelle option cochée"); })

Évènements

Events

change

Vous pouvez ajouter des écouteurs sur l'évènement change.

You can add listeners on the change event.

La propriété detail de l'évènement contient les propriétés :

The detail property of the event contains the properties :

  • prop : nom de la propriété modifiée name of the modified property
  • value : nouvelle valeur new value
  • preferences : valeurs actuelles de toutes les préférences current values of all preferences
const access = document.querySelector("access-settings"); access.addEventListener("change", e => { const { prop, value, preferences } = e.detail; alert(`Property ${prop} has changed to ${value}. Preferences are now ${JSON.stringify(preferences)}.`); })

API

Accès

Access

import accessSettings from "https://cdn.jsdelivr.net/npm/access-settings@1/dist/api.min.js";

Propriétés

Properties

accessSettings.dyslexicFont = true; accessSettings.invertColors = false; accessSettings.contrast = 110; accessSettings.fontSize = 18; accessSettings.lineHeight = 1.6;

Réinitialiser une propriété

Reset a property

accessSettings.reset("dyslexicFont");

Tout réinitialiser

Reset all

accessSettings.reset();

Sauvegarder les préférences

Save preferences

Les préférences peuvent être sauvegardées dans le Preferences can be saved in the localStorage par la méthode save using the save method.

accessSettings.save();

Charger les préférences

Load preferences

Les préférences sauvegardées peuvent être chargées et appliquées par la méthode load.

Saved preferences can be loaded and applied using the load method.

accessSettings.load();

Effacer les préférences

Remove preferences

La sauvegarde des préférences peut être supprimée par la méthode remove.

Preference saving can be removed using the remove method.

accessSettings.remove();

Évènements

Events

Vous pouvez ajouter des écouteurs sur l'évènement change.

You can add listeners on the change event.

La propriété detail de l'évènement contient les propriétés :

The detail property of the event contains the properties :

  • prop : nom de la propriété modifiée name of the modified property
  • value : nouvelle valeur new value
  • prevValue : valeur précédente previous value
import accessSettings from "https://cdn.jsdelivr.net/npm/access-settings@1/dist/api.min.js"; accessSettings.addEventListener("change", e => { const { prop, value, prevValue } = e.detail; alert(`Property ${prop} has changed from ${prevValue} to ${value}`); }); accessSettings.fontSize = 20; // triggers event

Ajouter une propriété

Add custom property

Vous pouvez ajouter une propriété de la façon suivante :

You can add a custom property as follows :

import accessSettings from "https://cdn.jsdelivr.net/npm/access-settings@1/dist/api.min.js"; const root = document.documentElement; const rootCStyle = getComputedStyle(root); Object.defineProperty(accessSettings, "color", { // make the property enumerable so it can be saved enumerable : true, get() { return rootCStyle.color; }, set(value) { root.style.color = value; // trigger change event when property changes this.triggerChange("color", value); } }); // define initial value to make the reset method work accessSettings.initialValues.color = rootCStyle.color; Points à respecter : Points to respect :
  • La propriété doit être énumérable.
  • Property must be enumerable.
  • La méthode triggerChange doit être appelée quand la valeur de la propriété est modifiée.
  • Method triggerChange must be called when property value is changed.
  • La valeur initiale doit être définie dans l'objet accesSettings.initialValues.
  • Initial value must be set in object accesSettings.initialValues.

Dépannage

Troubleshooting

Erreur de chargement

Loading error

Selon la Depending on the stratégie de sécurité security policy de votre page web, il se peut que l'import du script depuis le serveur CDN soit impossible. of your web page, the import of the script from the CDN server may not be possible.

Auquel cas vous pouvez installer la bibliothèque via NPM ou par téléchargement direct.

In which case you can install the library via NPM or by direct download.

Le style ne s'applique pas

Style does not apply

Si la modification d'une préférence d'accessibilité reste sans effet, ou ne correspond pas au résultat attendu, cela provient probablement du non respect des bonnes pratiques css.

If the modification of an accessibility preference remains without effect, or does not correspond to the expected result, this is probably due to the lack of respect for good practices css.

Bonnes pratiques à respecter

Best practices to follow

  • Définir une taille absolue de police à la racine du document et n'utiliser que des unités relatives pour tous les autres éléments. Set an absolute font size at the root of the document use only relative units for all other elements.
    Mauvais exemple : Bad example : h1 { font-size:32px; } p { font-size:16px; }
    Bon exemple : Good example : :root { font-size:16px; } h1 { font-size:2rem; } /* em, rem, % are ok */ p { font-size:1rem; }
  • Définir les propriétés css sur les éléments génériques et non des sélecteurs trop spécifiques. Define css properties on generic elements and not overly specific selectors.
    Mauvais exemple : Bad example : .title { font-family:Roboto,Arial,sans-serif; } .paragraphe { font-family:system-ui,sans-serif; }
    Bon exemple : Good example : h1,h2,h3 { font-family:Roboto,Arial,sans-serif; } p { font-family:system-ui,sans-serif; }

Autres problèmes

Other problems

Si vous rencontrez un autre problème, vous pouvez ouvrir un If you encounter another problem, you can open an ticket issue sur github. on github.