Bonnes pratiques concernant les éléments personnalisés

Les éléments personnalisés vous permettent de créer vos propres balises HTML. Cette liste de contrôle couvre les meilleures pratiques pour vous aider à créer des éléments de haute qualité.

Les éléments personnalisés vous permettent d'étendre le code HTML et de définir vos propres balises. Il s'agit d'un incroyablement puissante, mais elles sont aussi de bas niveau, ce qui signifie qu'il ne s'agit pas toujours déterminer la meilleure façon de mettre en œuvre votre propre élément.

Pour vous aider à créer la meilleure expérience possible, nous avons mis au point cette liste de contrôle. Il décrit toutes les choses qui, selon nous, sont nécessaires pour être est un élément personnalisé qui se comporte bien.

Checklist

Shadow DOM

Attributs et propriétés

Événements

Vidéo explicative

Ne pas remplacer l'auteur de la page

Il est possible qu'un développeur utilisant votre élément veuille remplacer certaines son état initial. Par exemple, si vous modifiez son role ARIA ou sa mise au point avec tabindex Vérifiez si ces attributs et d'autres attributs globaux ont été définis. avant d'appliquer vos propres valeurs.

connectedCallback() {
  if (!this.hasAttribute('role'))
    this.setAttribute('role', 'checkbox');
  if (!this.hasAttribute('tabindex'))
    this.setAttribute('tabindex', 0);

Rendre les propriétés inactives

Un développeur peut tenter de définir une propriété sur votre élément avant ses a été chargée. Cela est particulièrement vrai si le développeur utilise qui gère le chargement des composants, les insère dans la page et de lier leurs propriétés à un modèle.

Dans l'exemple suivant, Angular lie de manière déclarative les isChecked à la propriété checked de la case à cocher. Si la définition de Howto-box a été chargé en différé. Il est possible qu'Angular tente de définir la propriété cochée avant la mise à jour de l'élément.

<howto-checkbox [checked]="defaults.isChecked"></howto-checkbox>

Un élément personnalisé doit gérer ce scénario en vérifiant si des propriétés ont des déjà défini sur son instance. <howto-checkbox> illustre ce modèle à l'aide d'une méthode appelée _upgradeProperty().

connectedCallback() {
  ...
  this._upgradeProperty('checked');
}

_upgradeProperty(prop) {
  if (this.hasOwnProperty(prop)) {
    let value = this[prop];
    delete this[prop];
    this[prop] = value;
  }
}

_upgradeProperty() capture la valeur de l'instance non mise à niveau et supprime la propriété afin qu'elle n'occulte pas le setter de la propriété de l'élément personnalisé. Ainsi, lorsque le chargement de la définition de l'élément est terminé, il peut immédiatement reflètent l'état correct.

Éviter les problèmes de réentrée

Il est tentant d'utiliser attributeChangedCallback() pour refléter l'état dans une sous-jacente. Exemple:

// When the [checked] attribute changes, set the checked property to match.
attributeChangedCallback(name, oldValue, newValue) {
  if (name === 'checked')
    this.checked = newValue;
}

Mais cela peut créer une boucle infinie si le setter de la propriété reflète également l'attribut.

set checked(value) {
  const isChecked = Boolean(value);
  if (isChecked)
    // OOPS! This will cause an infinite loop because it triggers the
    // attributeChangedCallback() which then sets this property again.
    this.setAttribute('checked', '');
  else
    this.removeAttribute('checked');
}

Une alternative consiste à autoriser le setter de propriété à refléter l'attribut, et pour que le getter détermine sa valeur en fonction de l'attribut.

set checked(value) {
  const isChecked = Boolean(value);
  if (isChecked)
    this.setAttribute('checked', '');
  else
    this.removeAttribute('checked');
}

get checked() {
  return this.hasAttribute('checked');
}

Dans cet exemple, l'ajout ou la suppression de l'attribut définit également la propriété.

Enfin, attributeChangedCallback() peut être utilisé pour gérer les effets secondaires. comme l'application d'états ARIA.

attributeChangedCallback(name, oldValue, newValue) {
  const hasValue = newValue !== null;
  switch (name) {
    case 'checked':
      // Note the attributeChangedCallback is only handling the *side effects*
      // of setting the attribute.
      this.setAttribute('aria-checked', hasValue);
      break;
    ...
  }
}