# Composant Bouton

Les boutons servent principalement à déclencher des actions, comme envoyer un e-mail, partager un document ou aimer un commentaire.

## Utilisation {#usage}

Importez le composant :

```js
import 'mdui/components/button.js';
```

Importez le type TypeScript correspondant :

```ts
import type { Button } from 'mdui/components/button.js';
```

Exemple d'utilisation :

```html
<mdui-button>Bouton</mdui-button>
```

## Exemples {#examples}

### Variante {#example-variant}

Utilisez l'attribut `variant` pour définir la variante du bouton.

```html
<mdui-button variant="elevated">Surélevé</mdui-button>
<mdui-button variant="filled">Rempli</mdui-button>
<mdui-button variant="tonal">Tonal</mdui-button>
<mdui-button variant="outlined">Contour</mdui-button>
<mdui-button variant="text">Texte</mdui-button>
```

### Pleine largeur {#example-full-width}

Ajoutez l'attribut `full-width` pour que le bouton occupe toute la largeur de son conteneur parent.

```html
<mdui-button full-width>Bouton</mdui-button>
```

### Icône {#example-icon}

Utilisez les attributs `icon` et `end-icon` pour ajouter une icône Material Icons à gauche et à droite du bouton. Vous pouvez également utiliser les slots `icon` et `end-icon`.

```html
<mdui-button icon="search" end-icon="arrow_forward">Icône</mdui-button>
<mdui-button>
  Slot
  <mdui-icon slot="icon" name="downloading"></mdui-icon>
  <mdui-icon slot="end-icon" name="attach_file"></mdui-icon>
</mdui-button>
```

### Lien {#example-link}

Ajoutez l'attribut `href` pour transformer le bouton en lien. Les attributs liés aux liens (`download`, `target`, `rel`) sont alors également disponibles.

```html
<mdui-button href="https://www.mdui.org" target="_blank">Lien</mdui-button>
```

### États désactivé et chargement {#example-disabled}

Ajoutez l'attribut `disabled` pour désactiver le bouton, et l'attribut `loading` pour lui appliquer un état de chargement.

```html
<mdui-button disabled>Désactivé</mdui-button>
<mdui-button loading>Chargement</mdui-button>
<mdui-button loading disabled>Chargement & Désactivé</mdui-button>
```

## mdui-button API

### Propriétés

<table>
<thead>
  <tr>
    <th>Attribut HTML</th>
    <th>Propriété JavaScript</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Défaut</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>variant</td>
    <td>variant</td>
    <td>true</td>
    <td>&#39;elevated&#39; | &#39;filled&#39; | &#39;tonal&#39; | &#39;outlined&#39; | &#39;text&#39;</td>
    <td>'filled'</td>
    <td><p>Forme du bouton. Les valeurs possibles incluent :</p>
<ul>
<li><code>elevated</code> : Bouton avec ombre, adapté aux scénarios où le bouton doit être visuellement distinct de l&#39;arrière-plan</li>
<li><code>filled</code> : Effet visuel fort, adapté aux actions finales importantes dans un processus, telles que &quot;Enregistrer&quot;, &quot;Confirmer&quot;, etc.</li>
<li><code>tonal</code> : Effet visuel entre <code>filled</code> et <code>outlined</code>, adapté aux actions de priorité moyenne à élevée, comme &quot;Suivant&quot; dans un flux</li>
<li><code>outlined</code> : Bouton avec bordure, adapté aux actions de priorité moyenne et secondaire, comme &quot;Retour&quot;</li>
<li><code>text</code> : Bouton texte, adapté aux actions de la plus basse priorité</li>
</ul>
</td>
  </tr>
  <tr>
    <td>full-width</td>
    <td>fullWidth</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Si le bouton doit remplir toute la largeur de l&#39;élément parent</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Nom de l&#39;icône Material Icons à gauche. Peut également être défini via <code>slot=&quot;icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td>endIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Nom de l&#39;icône Material Icons à droite. Peut également être défini via <code>slot=&quot;end-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>href</td>
    <td>href</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>URL cible du lien.</p>
<p>Si cette propriété est définie, le composant sera rendu comme un élément <code>&lt;a&gt;</code> et pourra utiliser les attributs liés aux liens.</p>
</td>
  </tr>
  <tr>
    <td>download</td>
    <td>download</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Nom du fichier à télécharger.</p>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> est défini.</p>
</td>
  </tr>
  <tr>
    <td>target</td>
    <td>target</td>
    <td>true</td>
    <td>&#39;_blank&#39; | &#39;_parent&#39; | &#39;_self&#39; | &#39;_top&#39;</td>
    <td></td>
    <td><p>Cible d&#39;ouverture du lien. Les valeurs possibles incluent :</p>
<ul>
<li><code>_blank</code> : Ouvre le lien dans une nouvelle fenêtre</li>
<li><code>_parent</code> : Ouvre le lien dans le contexte parent</li>
<li><code>_self</code> : Par défaut. Ouvre le lien dans le contexte courant</li>
<li><code>_top</code> : Ouvre le lien dans toute la fenêtre</li>
</ul>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> est défini.</p>
</td>
  </tr>
  <tr>
    <td>rel</td>
    <td>rel</td>
    <td>true</td>
    <td>&#39;alternate&#39; | &#39;author&#39; | &#39;bookmark&#39; | &#39;external&#39; | &#39;help&#39; | &#39;license&#39; | &#39;me&#39; | &#39;next&#39; | &#39;nofollow&#39; | &#39;noreferrer&#39; | &#39;opener&#39; | &#39;prev&#39; | &#39;search&#39; | &#39;tag&#39;</td>
    <td></td>
    <td><p>Relation entre le document actuel et le document lié. Les valeurs possibles incluent :</p>
<ul>
<li><code>alternate</code> : Version alternative du document actuel</li>
<li><code>author</code> : Auteur du document actuel ou de l&#39;article</li>
<li><code>bookmark</code> : Lien permanent vers la section ancêtre la plus proche</li>
<li><code>external</code> : Le document référencé n&#39;est pas sur le même site que le document actuel</li>
<li><code>help</code> : Lien vers un document d&#39;aide associé</li>
<li><code>license</code> : Le contenu principal du document actuel est couvert par la licence de droits d&#39;auteur du fichier référencé</li>
<li><code>me</code> : Le document actuel représente le propriétaire du contenu lié</li>
<li><code>next</code> : Le document actuel fait partie d&#39;une série, le document référencé est le suivant dans la série</li>
<li><code>nofollow</code> : L&#39;auteur ou l&#39;éditeur du document actuel n&#39;approuve pas le fichier référencé</li>
<li><code>noreferrer</code> : N&#39;inclut pas l&#39;en-tête <code>Referer</code>. Effet similaire à <code>noopener</code></li>
<li><code>opener</code> : Si l&#39;hyperlien crée un contexte de navigation de premier niveau (c&#39;est-à-dire que la valeur de l&#39;attribut <code>target</code> est <code>_blank</code>), crée un contexte de navigation auxiliaire</li>
<li><code>prev</code> : Le document actuel fait partie d&#39;une série, le document référencé est le précédent dans la série</li>
<li><code>search</code> : Fournit un lien vers une ressource pouvant être utilisée pour rechercher le fichier actuel et ses pages associées</li>
<li><code>tag</code> : Fournit une balise (identifiée par l&#39;adresse donnée) applicable au document actuel</li>
</ul>
<p><strong>Remarque</strong> : Disponible uniquement lorsque l&#39;attribut <code>href</code> est spécifié.</p>
</td>
  </tr>
  <tr>
    <td>autofocus</td>
    <td>autofocus</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Si le focus doit être automatiquement obtenu après le chargement de la page</p>
</td>
  </tr>
  <tr>
    <td>tabindex</td>
    <td>tabIndex</td>
    <td>false</td>
    <td>number</td>
    <td></td>
    <td><p>Ordre de l&#39;élément lors de la navigation au clavier avec la touche Tab</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Si le composant est désactivé</p>
</td>
  </tr>
  <tr>
    <td>loading</td>
    <td>loading</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Si le composant est en état de chargement</p>
</td>
  </tr>
  <tr>
    <td>name</td>
    <td>name</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>Nom du bouton, qui sera envoyé avec les données du formulaire.</p>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> n&#39;est pas défini.</p>
</td>
  </tr>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>Valeur initiale du bouton, qui sera envoyée avec les données du formulaire.</p>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> n&#39;est pas défini.</p>
</td>
  </tr>
  <tr>
    <td>type</td>
    <td>type</td>
    <td>true</td>
    <td>&#39;submit&#39; | &#39;reset&#39; | &#39;button&#39;</td>
    <td>'button'</td>
    <td><p>Type du bouton. Par défaut, il s&#39;agit de <code>button</code>. Les valeurs possibles incluent :</p>
<ul>
<li><code>submit</code> : Au clic sur le bouton, les données du formulaire sont envoyées au serveur</li>
<li><code>reset</code> : Au clic sur le bouton, tous les champs du formulaire sont réinitialisés à leurs valeurs initiales</li>
<li><code>button</code> : Ce type de bouton n&#39;a pas de comportement par défaut</li>
</ul>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> n&#39;est pas spécifié.</p>
</td>
  </tr>
  <tr>
    <td>form</td>
    <td>form</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Élément <code>&lt;form&gt;</code> associé. La valeur de cet attribut doit être l&#39;<code>id</code> d&#39;un élément <code>&lt;form&gt;</code> dans la même page.</p>
<p>Si cet attribut n&#39;est pas spécifié, l&#39;élément doit être un enfant de l&#39;élément <code>&lt;form&gt;</code>. Grâce à cet attribut, vous pouvez placer l&#39;élément n&#39;importe où sur la page, y compris hors de l&#39;élément <code>&lt;form&gt;</code>.</p>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> n&#39;est pas spécifié.</p>
</td>
  </tr>
  <tr>
    <td>formaction</td>
    <td>formAction</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Spécifie l&#39;URL de soumission du formulaire.</p>
<p>Si cet attribut est spécifié, il remplace l&#39;attribut <code>action</code> de l&#39;élément <code>&lt;form&gt;</code>.</p>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> n&#39;est pas spécifié et que <code>type=&quot;submit&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>formenctype</td>
    <td>formEnctype</td>
    <td>true</td>
    <td>&#39;application/x-www-form-urlencoded&#39; | &#39;multipart/form-data&#39; | &#39;text/plain&#39;</td>
    <td></td>
    <td><p>Spécifie le type de contenu à utiliser pour soumettre le formulaire au serveur. Les valeurs possibles incluent :</p>
<ul>
<li><code>application/x-www-form-urlencoded</code> : Valeur par défaut si l&#39;attribut n&#39;est pas spécifié</li>
<li><code>multipart/form-data</code> : À utiliser lorsque le formulaire contient un élément <code>&lt;input type=&quot;file&quot;&gt;</code></li>
<li><code>text/plain</code> : Nouveau dans HTML5, utilisé pour le débogage</li>
</ul>
<p>Si cet attribut est spécifié, il remplace l&#39;attribut <code>enctype</code> de l&#39;élément <code>&lt;form&gt;</code>.</p>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> n&#39;est pas spécifié et que <code>type=&quot;submit&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>formmethod</td>
    <td>formMethod</td>
    <td>true</td>
    <td>&#39;post&#39; | &#39;get&#39;</td>
    <td></td>
    <td><p>Spécifie la méthode HTTP à utiliser pour soumettre le formulaire. Les valeurs possibles incluent :</p>
<ul>
<li><code>post</code> : Les données du formulaire sont incluses dans le corps de la requête et envoyées au serveur</li>
<li><code>get</code> : Les données du formulaire sont ajoutées à l&#39;URI du formulaire avec <code>?</code> comme séparateur, et l&#39;URI résultante est envoyée au serveur. À utiliser lorsque le formulaire n&#39;a pas d&#39;effets secondaires et ne contient que des caractères ASCII</li>
</ul>
<p>Si cet attribut est défini, il remplace l&#39;attribut <code>method</code> de l&#39;élément <code>&lt;form&gt;</code>.</p>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> n&#39;est pas défini et que <code>type=&quot;submit&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>formnovalidate</td>
    <td>formNoValidate</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Quand il est activé, la validation du formulaire n&#39;est pas effectuée lors de la soumission.</p>
<p>Si cet attribut est défini, il remplace l&#39;attribut <code>novalidate</code> de l&#39;élément <code>&lt;form&gt;</code>.</p>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> n&#39;est pas défini et que <code>type=&quot;submit&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>formtarget</td>
    <td>formTarget</td>
    <td>true</td>
    <td>&#39;_self&#39; | &#39;_blank&#39; | &#39;_parent&#39; | &#39;_top&#39;</td>
    <td></td>
    <td><p>Où afficher la réponse après l&#39;envoi du formulaire. Les valeurs possibles incluent :</p>
<ul>
<li><code>_self</code> : Option par défaut, ouvre dans le contexte courant</li>
<li><code>_blank</code> : Ouvre dans une nouvelle fenêtre</li>
<li><code>_parent</code> : Ouvre dans le contexte parent</li>
<li><code>_top</code> : Ouvre dans toute la fenêtre</li>
</ul>
<p>Si cet attribut est défini, il remplace l&#39;attribut <code>target</code> de l&#39;élément <code>&lt;form&gt;</code>.</p>
<p><strong>Remarque</strong> : Cette propriété ne s&#39;applique que si l&#39;attribut <code>href</code> n&#39;est pas défini et que <code>type=&quot;submit&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validity</td>
    <td>false</td>
    <td>ValidityState</td>
    <td></td>
    <td><p>État de validation du formulaire, voir <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState" target="_blank" rel="noopener nofollow"><code>ValidityState</code></a> pour plus de détails</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validationMessage</td>
    <td>false</td>
    <td>string</td>
    <td></td>
    <td><p>Si la validation du formulaire échoue, cet attribut contient un message d&#39;erreur. Si la validation réussit, cet attribut est une chaîne vide</p>
</td>
  </tr>
</tbody>
</table>

### Méthodes

<table>
<thead>
  <tr>
    <th>Nom</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>click(): void</td>
    <td><p>Simule un clic sur l&#39;élément</p>
</td>
  </tr>
  <tr>
    <td>focus(options?: FocusOptions): void</td>
    <td><p>Place le focus sur l&#39;élément.</p>
<p>Vous pouvez passer un objet en paramètre, dont les propriétés incluent :</p>
<ul>
<li><code>preventScroll</code> : Par défaut, après la prise de focus, la page défile pour amener l&#39;élément à l&#39;écran. Si vous ne souhaitez pas que la page défile, vous pouvez définir cette propriété sur <code>true</code>.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>blur(): void</td>
    <td><p>Retire le focus de l&#39;élément</p>
</td>
  </tr>
  <tr>
    <td>checkValidity(): boolean</td>
    <td><p>Vérifie si le champ du formulaire est valide. Dans le cas contraire, renvoie <code>false</code> et déclenche l&#39;événement <code>invalid</code> ; sinon, renvoie <code>true</code>.</p>
</td>
  </tr>
  <tr>
    <td>reportValidity(): boolean</td>
    <td><p>Vérifie si le champ du formulaire est valide. Dans le cas contraire, renvoie <code>false</code> et déclenche l&#39;événement <code>invalid</code> ; sinon, renvoie <code>true</code>.</p>
<p>Si la validation échoue, un message d&#39;erreur s&#39;affiche également sur le composant.</p>
</td>
  </tr>
  <tr>
    <td>setCustomValidity(message: string): void</td>
    <td><p>Définit un message d&#39;erreur personnalisé. Tant qu&#39;il n&#39;est pas vide, le champ est considéré comme invalide.</p>
</td>
  </tr>
</tbody>
</table>

### Événements

<table>
<thead>
  <tr>
    <th>Nom</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>Se déclenche lorsque l&#39;élément obtient le focus</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Se déclenche lorsque l&#39;élément perd le focus</p>
</td>
  </tr>
  <tr>
    <td>invalid</td>
    <td><p>Se déclenche lorsque la validation du champ du formulaire échoue</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Nom</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>Défaut</td>
    <td><p>Texte du bouton</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Icône à gauche du bouton</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Icône à droite du bouton</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Nom</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>button</td>
    <td><p>Élément <code>&lt;button&gt;</code> ou <code>&lt;a&gt;</code> interne</p>
</td>
  </tr>
  <tr>
    <td>label</td>
    <td><p>Texte du bouton</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Icône à gauche du bouton</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Icône à droite du bouton</p>
</td>
  </tr>
  <tr>
    <td>loading</td>
    <td><p>Élément <code>&lt;mdui-circular-progress&gt;</code> en état de chargement</p>
</td>
  </tr>
</tbody>
</table>

### Propriétés CSS personnalisées

<table>
<thead>
  <tr>
    <th>Nom</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>Taille des coins arrondis du composant. Vous pouvez spécifier une valeur de pixel spécifique ; mais il est préférable de se référer au <a href="/fr/docs/2/styles/design-tokens#shape-corner">Design Tokens</a>.</p>
</td>
  </tr>
</tbody>
</table>