Maîtriser les Web Components : Créez des Composants Réutilisables et Interopérables
Maîtriser les Web Components : Créez des Composants Réutilisables et Interopérables

Gestion des Attributs et Propriétés des Composants

Introduction aux Attributs et Propriétés dans les Web Components

Dans l'univers des Web Components, la capacité d'un composant à interagir avec le monde extérieur est primordiale. Cette interaction s'opère principalement via la gestion de ses attributs et de ses propriétés. Comprendre la distinction fondamentale entre ces deux concepts et savoir comment les manipuler est essentiel pour créer des composants réutilisables, configurables et interopérables.

Un Web Component n'est pas une entité figée ; il doit pouvoir être configuré lors de son instanciation (via HTML) et son état doit pouvoir être modifié dynamiquement (via JavaScript). C'est là qu'interviennent les attributs et les propriétés.

  • Les attributs sont des mécanismes HTML, des paires clé-valeur textuelles définies directement dans le balisage HTML.
  • Les propriétés sont des mécanismes JavaScript, des paires clé-valeur définies sur l'instance DOM de l'élément.

Bien qu'ils semblent similaires, leur nature et leur comportement sont distincts, et cette leçon vous éclairera sur leurs différences, leurs usages et les meilleures pratiques pour les gérer efficacement dans vos Web Components.

Attributs vs. Propriétés : Une Distinction Fondamentale

C'est l'un des concepts les plus importants à maîtriser lors du développement de Web Components. Bien qu'ils puissent sembler interconnectés, ils représentent deux facettes différentes de la configuration et de l'état d'un élément.

Les Attributs HTML

Les attributs sont ce que vous voyez et manipulez directement dans le balisage HTML de votre page.

  • Nature : Ce sont des paires nom-valeur textuelles, toujours représentées comme des chaînes de caractères.
  • Définition : Ils sont définis dans la balise d'ouverture de l'élément : 
    <mon-bouton couleur="rouge" desactive></mon-bouton>
  • Accès : Vous pouvez accéder aux attributs via les méthodes de l'API Element :
    • element.getAttribute('nom-attribut') : Récupère la valeur de l'attribut.
    • element.setAttribute('nom-attribut', 'valeur') : Définit ou modifie la valeur de l'attribut.
    • element.hasAttribute('nom-attribut') : Vérifie la présence de l'attribut.
    • element.removeAttribute('nom-attribut') : Supprime l'attribut.
  • Cas d'utilisation : Idéaux pour la configuration initiale ou les états binaires (attributs booléens comme disabled, checked). Ils sont facilement inspectables et modifiables via les outils de développement du navigateur.
  • Convention de nommage : Les attributs utilisent généralement le kebab-case (par exemple, data-value, max-length).

Les Propriétés JavaScript (Propriétés DOM)

Les propriétés sont des membres d'un objet JavaScript, spécifiques à l'instance DOM de l'élément.

  • Nature : Ce sont des paires nom-valeur qui peuvent contenir n'importe quel type de donnée : chaînes de caractères, nombres, booléens, objets, tableaux, fonctions, etc.
  • Définition : Elles sont définies et manipulées directement en JavaScript. 
    const monBouton = document.querySelector('mon-bouton');
monBouton.couleur = 'bleu';
monBouton.options = { mode: 'sombre', taille: 'large' };
  • Accès : Vous y accédez directement comme des propriétés d'objet :
    • element.propertyName : Récupère la valeur de la propriété.
    • element.propertyName = value : Définit ou modifie la valeur de la propriété.
  • Cas d'utilisation : Idéales pour gérer l'état dynamique du composant, stocker des données complexes (objets, tableaux) ou exposer des API programmatiques. Elles sont le moyen privilégié pour la communication bidirectionnelle entre le code JavaScript et le composant.
  • Convention de nommage : Les propriétés utilisent généralement le camelCase (par exemple, dataValue, maxLength).

Le Problème de la Réflexion (Reflection)

Un point crucial à comprendre est que les attributs et les propriétés ne se synchronisent pas automatiquement dans les deux sens.

  • Lorsqu'un attribut est défini en HTML, il initialise la propriété correspondante (si elle existe et est gérée pour cela) lors de la création du composant.
  • Modifier un attribut via setAttribute ne met pas automatiquement à jour la propriété JavaScript correspondante.
  • Modifier une propriété JavaScript element.propertyName = value ne met pas automatiquement à jour l'attribut HTML correspondant.

Cette absence de synchronisation automatique nécessite une gestion manuelle ou semi-automatique si vous souhaitez que les changements de l'un se reflètent sur l'autre. C'est ce que nous allons voir ensuite.

Gestion des Attributs dans les Web Components

Pour qu'un Web Component puisse réagir aux changements de ses attributs HTML, il doit explicitement déclarer les attributs qu'il souhaite "observer".

static get observedAttributes()

Cette méthode statique est utilisée au sein de votre classe CustomElement pour retourner un tableau des noms d'attributs que le composant doit surveiller.

class MonElementCompteur extends HTMLElement {
  static get observedAttributes() {
    return ['compte', 'label']; // Liste des attributs à observer
  }

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.innerHTML = `
      <style>
        :host { display: block; padding: 10px; border: 1px solid #ccc; }
        span { font-weight: bold; }
      </style>
      <p>Label: <span id="label"></span></p>
      <p>Compte: <span id="compte"></span></p>
      <button>Incrémenter</button>
    `;
    this._count = 0; // Propriété interne
    this._label = '';
  }

  // La méthode connectedCallback est appelée lorsque le composant est ajouté au DOM
  connectedCallback() {
    this._count = parseInt(this.getAttribute('compte') || '0', 10);
    this._label = this.getAttribute('label') || 'Par défaut';
    this._updateDisplay();

    this.shadowRoot.querySelector('button').addEventListener('click', () => {
      this._count++;
      this.setAttribute('compte', this._count); // Met à jour l'attribut
      this._updateDisplay();
    });
  }

  // Méthode interne pour mettre à jour l'affichage
  _updateDisplay() {
    this.shadowRoot.getElementById('compte').textContent = this._count;
    this.shadowRoot.getElementById('label').textContent = this._label;
  }

  // La méthode attributeChangedCallback est appelée lorsqu'un attribut observé change
  attributeChangedCallback(name, oldValue, newValue) {
    console.log(`Attribut '${name}' a changé de '${oldValue}' à '${newValue}'`);
    if (oldValue !== newValue) {
      switch (name) {
        case 'compte':
          this._count = parseInt(newValue, 10);
          this._updateDisplay();
          break;
        case 'label':
          this._label = newValue;
          this._updateDisplay();
          break;
      }
    }
  }
}

customElements.define('mon-element-compteur', MonElementCompteur);

attributeChangedCallback(name, oldValue, newValue)

C'est la méthode de rappel (callback) du cycle de vie des Web Components qui est invoquée chaque fois qu'un des attributs listés dans observedAttributes est :

  • ajouté
  • supprimé
  • modifié
  • ou lorsque la valeur de l'attribut change.

Les arguments de cette fonction sont :

  • name : Le nom de l'attribut qui a changé.
  • oldValue : L'ancienne valeur de l'attribut (sera null si l'attribut a été ajouté).
  • newValue : La nouvelle valeur de l'attribut (sera null si l'attribut a été supprimé).

Dans l'exemple ci-dessus, attributeChangedCallback est utilisée pour mettre à jour la propriété interne _count ou _label et ensuite rafraîchir l'affichage du composant chaque fois que l'attribut compte ou label est modifié, que ce soit via un appel setAttribute ou directement dans le HTML initial.

Gestion des Propriétés dans les Web Components

Les propriétés sont le moyen privilégié pour la communication JavaScript-to-component. Elles sont plus flexibles que les attributs car elles peuvent stocker n'importe quel type de données.

Définition et Accès aux Propriétés

Les propriétés d'un Web Component sont simplement des propriétés de l'instance de sa classe. Vous pouvez les définir dans le constructor ou dynamiquement.

class MonElementAvance extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.innerHTML = `
      <style>
        :host { display: block; padding: 20px; border: 1px dashed blue; }
        p { margin: 5px 0; }
      </style>
      <p>Titre: <span id="titre"></span></p>
      <p>Données: <span id="donnees"></span></p>
    `;

    // Définition de propriétés par défaut
    this._titre = 'Titre par défaut';
    this._data = { message: 'Aucune donnée', version: 1 };
  }

  connectedCallback() {
    this._updateDisplay();
  }

  // Getter pour la propriété 'titre'
  get titre() {
    return this._titre;
  }

  // Setter pour la propriété 'titre'
  set titre(newValue) {
    if (typeof newValue === 'string' && newValue !== this._titre) {
      this._titre = newValue;
      this._updateDisplay();
      // Optionnel: Refléter la propriété vers l'attribut si désiré
      this.setAttribute('titre', newValue);
    }
  }

  // Getter pour la propriété 'data'
  get data() {
    return this._data;
  }

  // Setter pour la propriété 'data'
  set data(newValue) {
    // Vérifier si la nouvelle valeur est un objet et différente
    // (Une comparaison d'objet simple comme !== ne fonctionne pas pour les contenus)
    if (typeof newValue === 'object' && newValue !== null && JSON.stringify(newValue) !== JSON.stringify(this._data)) {
      this._data = newValue;
      this._updateDisplay();
      // ATTENTION: Ne PAS réfléchir les objets complexes vers des attributs.
      // Les attributs sont des chaînes de caractères.
    }
  }

  _updateDisplay() {
    this.shadowRoot.getElementById('titre').textContent = this._titre;
    this.shadowRoot.getElementById('donnees').textContent = JSON.stringify(this._data);
  }
}

customElements.define('mon-element-avance', MonElementAvance);

Getters et Setters pour des Propriétés Réactives

L'utilisation de get et set est une pratique courante pour les raisons suivantes :

  1. Validation : Le setter permet de valider la valeur entrante avant de l'assigner à la propriété interne.
  2. Effets secondaires : Lorsque la valeur d'une propriété change, le setter peut déclencher des actions, comme :
    • Mettre à jour le rendu du composant.
    • Déclencher un événement personnalisé.
    • Refléter la propriété vers un attribut HTML (si la propriété est une chaîne ou un booléen simple).
  3. Encapsulation : getters et setters permettent de contrôler l'accès et la modification des propriétés internes du composant.

Dans l'exemple ci-dessus, lorsque element.titre = 'Nouveau titre' est appelé, le setter est exécuté, mettant à jour l'affichage et optionnellement l'attribut HTML correspondant.

Synchronisation : La Réflexion des Attributs et Propriétés

Comme mentionné, la synchronisation entre attributs et propriétés n'est pas automatique. Cependant, il est souvent souhaitable de la mettre en œuvre, en particulier pour les attributs/propriétés booléens ou de chaîne simple.

Quand synchroniser ?

  • Propriétés simples : Pour les propriétés qui stockent des chaînes de caractères, des nombres ou des booléens, la réflexion est souvent utile. Par exemple, si vous avez une propriété disabled qui est un booléen, vous voudrez probablement qu'elle reflète l'attribut HTML disabled pour que les styles CSS ou les sélecteurs CSS ([disabled]) puissent fonctionner correctement.
  • Accessibilité et CSS : Les outils d'accessibilité et les feuilles de style CSS interagissent principalement avec les attributs HTML. La synchronisation assure que l'état du composant est correctement exposé pour ces usages.
  • Initialisation via HTML : L'initialisation d'une propriété à partir de son attribut HTML est une pratique courante dans connectedCallback ou dans le constructor.

Mécanismes de Synchronisation

  1. Initialisation de la propriété à partir de l'attribut (Au chargement) : Dans connectedCallback (ou parfois le constructor), vous pouvez lire la valeur d'un attribut et l'assigner à la propriété interne correspondante.

    connectedCallback() {
  // Lire l'attribut 'compte' et initialiser la propriété interne
  this._count = parseInt(this.getAttribute('compte') || '0', 10);
  this._updateDisplay();
}

  2. Réflexion de la propriété vers l'attribut (Quand la propriété change) : Ceci est généralement fait dans le setter de la propriété.

    set titre(newValue) {
  if (typeof newValue === 'string' && newValue !== this._titre) {
    this._titre = newValue;
    this.setAttribute('titre', newValue); // Reflète la propriété vers l'attribut
    this._updateDisplay();
  }
}

  3. Mise à jour de la propriété à partir de l'attribut (Quand l'attribut change) : Ceci est fait dans attributeChangedCallback.

    attributeChangedCallback(name, oldValue, newValue) {
  if (oldValue !== newValue && name === 'titre') {
    this._titre = newValue; // Met à jour la propriété interne
    this._updateDisplay();
  }
}

Exemple Complet de Synchronisation

Reprenons l'exemple du compteur pour illustrer une synchronisation bidirectionnelle simple pour la propriété count.

<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Composant Compteur avec Synchronisation</title>
</head>
<body>

    <h1>Mon Compteur Bidirectionnel</h1>

    <my-counter count="5" label="Clicks"></my-counter>
    <my-counter label="Compteur Secondaire"></my-counter>

    <button id="externalUpdateBtn">Mettre à jour le premier compteur (externel)</button>

    <script>
        class MyCounter extends HTMLElement {
            static get observedAttributes() {
                return ['count', 'label'];
            }

            constructor() {
                super();
                this.attachShadow({ mode: 'open' });
                this.shadowRoot.innerHTML = `
                    <style>
                        :host {
                            display: inline-block;
                            margin: 10px;
                            padding: 15px;
                            border: 2px solid #007bff;
                            border-radius: 8px;
                            font-family: Arial, sans-serif;
                            background-color: #f8f9fa;
                        }
                        p { margin: 5px 0; }
                        button {
                            padding: 8px 15px;
                            background-color: #007bff;
                            color: white;
                            border: none;
                            border-radius: 4px;
                            cursor: pointer;
                        }
                        button:hover {
                            background-color: #0056b3;
                        }
                        .count-display {
                            font-size: 1.5em;
                            font-weight: bold;
                            color: #333;
                        }
                    </style>
                    <p>Label: <span class="label-display"></span></p>
                    <p>Count: <span class="count-display"></span></p>
                    <button>Increment</button>
                `;

                this._count = 0;
                this._label = '';

                this.shadowRoot.querySelector('button').addEventListener('click', () => {
                    this.count++; // Utilisation du setter de la propriété
                });
            }

            connectedCallback() {
                // Initialisation des propriétés depuis les attributs lors de la connexion au DOM
                this.count = parseInt(this.getAttribute('count') || '0', 10);
                this.label = this.getAttribute('label') || 'Default';
            }

            // Gestion de l'attribut 'count'
            get count() {
                return this._count;
            }

            set count(value) {
                const oldValue = this._count;
                const newValue = parseInt(value, 10);
                if (oldValue !== newValue) {
                    this._count = newValue;
                    this._updateCountDisplay();
                    // Refléter la propriété vers l'attribut HTML
                    this.setAttribute('count', this._count);
                }
            }

            // Gestion de l'attribut 'label'
            get label() {
                return this._label;
            }

            set label(value) {
                const oldValue = this._label;
                if (typeof value === 'string' && oldValue !== value) {
                    this._label = value;
                    this._updateLabelDisplay();
                    // Refléter la propriété vers l'attribut HTML
                    this.setAttribute('label', this._label);
                }
            }

            attributeChangedCallback(name, oldValue, newValue) {
                if (oldValue !== newValue) {
                    switch (name) {
                        case 'count':
                            // Mettre à jour la propriété 'count' via son setter
                            // qui se chargera de la validation et de la mise à jour de l'affichage
                            this.count = parseInt(newValue, 10);
                            break;
                        case 'label':
                            // Mettre à jour la propriété 'label' via son setter
                            this.label = newValue;
                            break;
                    }
                }
            }

            _updateCountDisplay() {
                this.shadowRoot.querySelector('.count-display').textContent = this._count;
            }

            _updateLabelDisplay() {
                this.shadowRoot.querySelector('.label-display').textContent = this._label;
            }
        }

        customElements.define('my-counter', MyCounter);

        // Exemple d'interaction externe
        document.getElementById('externalUpdateBtn').addEventListener('click', () => {
            const firstCounter = document.querySelector('my-counter');
            if (firstCounter) {
                // Modifier via la propriété (préférable en JS)
                firstCounter.count = firstCounter.count + 10;
                // Ou modifier via l'attribut (moins direct pour des types non string)
                // firstCounter.setAttribute('count', parseInt(firstCounter.getAttribute('count')) + 5);
            }
        });

        // Observer les changements d'attributs via l'inspecteur du navigateur
        // et voir comment le composant réagit
    </script>
</body>
</html>

Dans cet exemple:

  • La propriété count est initialisée depuis l'attribut count dans connectedCallback.
  • Lorsque la propriété count est modifiée via son setter (par le bouton interne ou le script externe), elle met à jour l'affichage et reflète la nouvelle valeur dans l'attribut HTML count via setAttribute.
  • Lorsque l'attribut count est modifié (par exemple, via setAttribute externe ou l'inspecteur du navigateur), attributeChangedCallback est déclenché. Il appelle ensuite le setter de la propriété count pour que toute la logique de mise à jour et de réflexion soit centralisée.

Cette approche permet une gestion robuste des états, assurant que les mises à jour des propriétés et des attributs sont cohérentes, quel que soit le point de départ de la modification.

Conclusion

La gestion des attributs et des propriétés est un pilier fondamental de la construction de Web Components robustes et interopérables.

  • Les attributs sont des chaînes de caractères idéales pour la configuration initiale et l'intégration HTML/CSS/Accessibilité.
  • Les propriétés sont des entités JavaScript qui peuvent gérer tous les types de données et sont parfaites pour la gestion de l'état dynamique et les API programmatiques.

Une compréhension claire de leur distinction et la mise en œuvre de mécanismes de synchronisation (particulièrement via static get observedAttributes(), attributeChangedCallback() et les getters/setters JavaScript) vous permettront de créer des composants Web flexibles, réactifs et faciles à utiliser. Maîtriser ces concepts vous ouvre la voie à la construction d'expériences utilisateur riches et d'architectures de composants modulaires et maintenables.