Propriétés et attributs
Lors de l'écriture de code source HTML, il est possible de définir des attributs sur les éléments HTML. Ensuite, lorsque le navigateur parse le code, un nœud DOM correspondant est créé. Ce nœud est un objet et a donc des propriétés.
Les propriétés avec un type complexe, comme un objet ou une fonction n'ont pas d'attribut, car elles ne peuvent pas être sérialisées en une chaine de caractère.
Dans la documentation, il sera toujours affiché le nom de la propriété en premier et en dessous le format de l'attribut s'il diffère de celui de la propriété. L'attribut suit généralement le format de casse kebab-case.
|
Propriété attribut |
Explication |
|---|---|
|
value |
Ici, l'attribut à le même nom que la propriété |
|
helpTex help-text |
Ici, l'attribut n'a pas le même nom que la propriété |
<dsa-input
id="input"
type="text"
name="name"
label="Nom"
value="Martin"
help-text="Votre nom de famille comme le figure sur vos papier d'identité"
autocomplete="family-name"
></dsa-input>
<script type="text/typescript">
import '@ds-autonomie/web-components/dist/components/input/input.js';
import type { DSAInput } from '@ds-autonomie/web-components';
const inputEl = document.querySelector<DSAInput>('#input')
if (inputEl !== null) {
inputEl.value = "Smith";
inputEl.helpText = ""
}
</script>
Méthodes
Les méthodes sont des fonctions disponibles sur l'instance d'un composant. Elles permettent de déclencher un comportement du composant.
<dsa-input
id="input"
type="text"
name="name"
label="Nom"
value="Martin"
help-text="Votre nom de famille comme le figure sur vos papier d'identité"
autocomplete="family-name"
></dsa-input>
<script type="text/typescript">
import '@ds-autonomie/web-components/dist/components/input/input.js';
import type { DSAInput } from '@ds-autonomie/web-components';
const inputEl = document.querySelector<DSAInput>('#input')
if (inputEl !== null) {
inputEl.value = "Smith";
inputEl.helpText = ""
}
</script>
Slots
Les slots sont des emplacements au sein d'un composant. Un composant peut avoir un slot dit par défaut et des slots nommé.
Le slot par défaut accepte tout contenu comme le label pour d'un bouton :
<dsa-button>Click moi</dsa-button>
Un slot nommé nécessite l'attribut slot avec comme valeur le nom pour indiquer l'emplacement du contenu. Celui-ci peux être placer dans n'importe qu'elle ordre, le navigateur se chargera du bon emplacement.
<dsa-button>
<dsa-icon slot="prefix" name="file_download"></dsa-icon>
Télécharger
</dsa-button>
Évènements
Certains composants émettent des évènements pour signaler une action ou un changement au sein de celui-ci.
Il est fortement recommandé d'utiliser les évènements customisés (commençant par dsa-) plutôt que les évènements natifs (click, change, etc.). La raison est que les composants sont encapsulés dans un Shadow DOM et les évènements natifs sont reciblés.
<dsa-input
id="input"
type="text"
name="name"
label="Nom"
value="Martin"
help-text="Votre nom de famille comme le figure sur vos papier d'identité"
autocomplete="family-name"
></dsa-input>
<script type="text/typescript">
import '@ds-autonomie/web-components/dist/components/input/input.js';
import type { DSAInput } from '@ds-autonomie/web-components';
const inputEl = document.querySelector<DSAInput>('#input')
if (inputEl !== null) {
inputEl.addEventListener('dsa-input', (event) => {
console.log(event.target.value);
});
}
</script>
De la même manière que pour les évènements natifs, les événements dsa- “bouillonnent” (bubble up).
Quelques exemples de solutions et explications.
Ne pas utiliser les balises auto-fermantes
Les balises auto-fermantes n'existent pas en HTML. Les composants doivent obligatoirement avoir une balise fermante.
<!-- INVALID -->
<dsa-divider />
<!-- CORRECT -->
<dsa-divider></dsa-divider>
Rendu et mises à jour des composants
Tout les composants ont une propriété updateComplete: Promise<void> .
La promesse renvoyée se résout lorsque l'élément a terminé sa mise à jour. La valeur de la promesse est un booléen qui est true si l'élément a terminé la mise à jour sans déclencher une autre mise à jour. La promesse renvoie false si une propriété a été définie à l'intérieur de updated(). Si la promesse est rejetée, une exception a été levée pendant la mise à jour.
const checkbox = document.querySelector('dsa-checkbox');
checkbox.checked = true;
checkbox.updateComplete.then(() => {
console.log(checkbox.hasAttribute('checked')); // true
});