Démarrage rapide

Les composants mdui sont des Web Components standards. Vous pouvez les utiliser comme vous utiliseriez une balise <div>. La documentation de chaque composant décrit en détail son API complète : propriétés, méthodes, événements, slots, CSS Parts, propriétés CSS personnalisées, etc.

Ce chapitre présente les bases de l'utilisation des Web Components.

Attributs et propriétés

Il existe des attributs HTML et des propriétés JavaScript. Ils sont généralement liés et restent synchronisés : modifier un attribut HTML met à jour la propriété JavaScript, et vice versa.

Les attributs HTML peuvent être définis directement dans le code HTML du composant, et lus ou modifiés via getAttribute et setAttribute :

<mdui-button variant="text">Cliquez-moi</mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  // Modifier l'attribut HTML
  button.setAttribute('variant', 'outlined');

  // Lire l'attribut HTML
  console.log(button.getAttribute('variant')); // outlined
</script>

Les propriétés JavaScript peuvent être lues ou modifiées directement sur l'instance du composant :

<mdui-button variant="text">Cliquez-moi</mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  // Définir la propriété JavaScript
  button.variant = 'outlined';

  // Lire la propriété JavaScript
  console.log(button.variant); // outlined
</script>

Certaines propriétés sont de type booléen. Pour ces propriétés, la présence de l'attribut HTML rend la propriété JavaScript true, son absence la rend false. Pour des raisons de compatibilité avec certains frameworks, la chaîne "false" est également interprétée comme false.

<!-- Ce composant a l'attribut disabled, donc la propriété disabled est true -->
<mdui-button disabled></mdui-button>

<script>
  const button = document.querySelector('mdui-button');

  button.removeAttribute('disabled'); // équivaut à button.disabled = false;
  button.setAttribute('disabled', ''); // équivaut à button.disabled = true;

  // Cas particulier : la chaîne "false" équivaut à false
  button.setAttribute('disabled', 'false'); // équivaut à button.disabled = false;
</script>

Parfois, les propriétés sont des tableaux, des objets ou des fonctions. Dans ce cas, il n'y a pas d'attribut HTML correspondant. Par exemple, la propriété labelFormatter du composant <mdui-slider> est une fonction, et ne peut être définie qu'en JavaScript :

<mdui-slider></mdui-slider>

<script>
  const slider = document.querySelector('mdui-slider');
  slider.labelFormatter = (value) => `${value}%`;
</script>

Voici un extrait de la documentation du composant <mdui-slider> à titre d'illustration :

Ce tableau montre que name a un attribut HTML et une propriété JavaScript, et la colonne reflect indique que la modification de la propriété JavaScript met à jour l'attribut HTML. Pour value, la modification de la propriété JavaScript ne met pas à jour l'attribut HTML. labelFormatter n'existe qu'en tant que propriété JavaScript.

Méthodes

Certains composants exposent des méthodes publiques que vous pouvez appeler pour réaliser différentes actions. Par exemple, la méthode focus() du composant <mdui-text-field> permet de donner le focus au champ de texte.

<mdui-text-field></mdui-text-field>

<script>
  const textField = document.querySelector('mdui-text-field');
  textField.focus();
</script>

Consultez les pages de documentation de chaque composant pour la liste complète des méthodes et de leurs paramètres.

Événements

Certains composants déclenchent des événements lors d'opérations spécifiques. Par exemple, le composant <mdui-dialog> déclenche l'événement open lorsqu'il commence à s'ouvrir. Vous pouvez écouter cet événement pour exécuter des actions personnalisées.

<mdui-dialog>Boîte de dialogue</mdui-dialog>

<script>
  const dialog = document.querySelector('mdui-dialog');

  dialog.addEventListener('open', () => {
    console.log('Cet événement se déclenche lorsque la boîte de dialogue s'ouvre');
  });
</script>

Consultez les pages de documentation de chaque composant pour la liste complète des événements et de leurs paramètres.

Si vous utilisez mdui dans d'autres frameworks (comme Vue, React, Angular), vous pouvez utiliser la syntaxe du framework pour lier les événements. Cependant, la syntaxe de liaison d'événements de certains frameworks (comme React) ne fonctionne que pour les événements standards (comme click), et non pour les événements personnalisés (comme open). Dans ce cas, vous devez obtenir une référence à l'élément et utiliser addEventListener.

Pour plus d'informations sur l'utilisation de mdui avec React, consultez la section Intégration avec les frameworks - React.

Slot

De nombreux composants fournissent des slots pour insérer du contenu HTML personnalisé.

Le slot par défaut est le plus courant. Il s'agit d'un fragment de HTML ou de texte simple à l'intérieur du composant. Par exemple, le slot par défaut de <mdui-button> définit le texte du bouton. "Cliquez-moi" est le contenu du slot par défaut :

<mdui-button>Cliquez-moi</mdui-button>

Certains composants possèdent également des slots nommés. Pour les utiliser, spécifiez le nom du slot dans l'attribut slot de l'élément HTML. Dans l'exemple suivant, le composant <mdui-icon> a l'attribut slot="start", ce qui signifie qu'il s'agit du slot nommé start. L'icône sera donc placée à gauche à l'intérieur du composant :

<mdui-button>
  <mdui-icon slot="start" name="settings"></mdui-icon>
  Paramètres
</mdui-button>

L'ordre des slots nommés dans le code n'a pas d'importance, tant qu'ils se trouvent à l'intérieur du composant. Le navigateur les placera automatiquement au bon endroit.

Consultez les pages de documentation de chaque composant pour la liste des slots disponibles.

Propriétés CSS personnalisées

Les propriétés CSS personnalisées sont des variables CSS. mdui définit un ensemble de propriétés CSS personnalisées globales qui sont utilisées à l'intérieur des composants. En modifiant ces propriétés, vous pouvez modifier le style de tous les composants mdui globalement.

Par exemple, le code suivant réduit le rayon des coins arrondis de tous les composants :

:root {
  --mdui-shape-corner-extra-small: 0.125rem;
  --mdui-shape-corner-small: 0.25rem;
  --mdui-shape-corner-medium: 0.375rem;
  --mdui-shape-corner-large: 0.5rem;
  --mdui-shape-corner-extra-large: 0.875rem;
}

Vous pouvez aussi modifier ces propriétés dans un contexte local. Par exemple, le code suivant ne modifie les rayons que pour l'élément possédant la classe sharp et ses enfants :

.sharp {
  --mdui-shape-corner-extra-small: 0.125rem;
  --mdui-shape-corner-small: 0.25rem;
  --mdui-shape-corner-medium: 0.375rem;
  --mdui-shape-corner-large: 0.5rem;
  --mdui-shape-corner-extra-large: 0.875rem;
}

Certains composants exposent également leurs propres propriétés CSS personnalisées, qui leur sont spécifiques. Ces propriétés ne sont pas préfixées par --mdui. Par exemple, le code suivant modifie la propriété --z-index du composant <mdui-dialog> :

mdui-dialog {
  --z-index: 3000;
}

Consultez les pages de documentation de chaque composant pour la liste des propriétés CSS personnalisées supportées.

CSS Part

Les composants mdui utilisent le shadow DOM pour encapsuler les styles et le comportement. Les sélecteurs CSS standards ne peuvent pas cibler les éléments à l'intérieur du shadow DOM. Certains composants ajoutent donc un attribut part à leurs éléments internes. Vous pouvez utiliser le sélecteur CSS ::part pour les cibler et modifier leur style.

Par exemple, le code suivant utilise le part button pour modifier le padding du bouton, et les parts label, icon, end-icon pour modifier la couleur du texte et des icônes :

<mdui-button class="custom-button" icon="explore" end-icon="flight">Bouton</mdui-button>

<style>
  .custom-button::part(button) {
    padding: 0 2rem;
  }

  .custom-button::part(label) {
    color: blue;
  }

  .custom-button::part(icon) {
    color: red;
  }

  .custom-button::part(end-icon) {
    color: yellow;
  }
</style>

Pour connaître la structure des éléments internes et leurs styles par défaut, vous pouvez utiliser les outils de développement du navigateur.

Avant d'utiliser les CSS Parts, vérifiez si les propriétés CSS personnalisées globales ou spécifiques au composant peuvent répondre à vos besoins. Si c'est le cas, privilégiez les propriétés CSS personnalisées.

Consultez les pages de documentation de chaque composant pour la liste des parts exposés.

Mécanisme de mise à jour des composants

Les composants mdui sont développés avec Lit, une bibliothèque légère qui simplifie le développement des Web Components. Il est utile de comprendre comment ils sont rendus et mis à jour.

Lorsque vous modifiez une propriété d'un composant mdui, un nouveau rendu est déclenché. Cependant, ce processus de rendu n'est pas synchrone. Lorsque vous modifiez plusieurs propriétés en même temps, Lit met en cache ces changements et attend le prochain cycle de mise à jour pour appliquer le rendu. Ainsi, un composant ne fait l'objet que d'un seul rendu, quel que soit le nombre de modifications. De plus, seules les parties du shadow DOM qui ont changé sont mises à jour.

Dans l'exemple suivant, nous définissons la propriété JavaScript disabled du bouton à true, puis nous vérifions immédiatement son attribut HTML. Comme le rendu du composant n'a pas encore eu lieu, l'attribut HTML est toujours false :

const button = document.querySelector('mdui-button');
button.disabled = true;

console.log(button.hasAttribute('disabled')); // false

Pour attendre la fin du rendu après une modification de propriété, vous pouvez utiliser la propriété updateComplete du composant. Cette propriété retourne une Promise qui se résout lorsque le composant a terminé son rendu :

const button = document.querySelector('mdui-button');
button.disabled = true;

button.updateComplete.then(() => {
  console.log(button.hasAttribute('disabled')); // true
});