Documentation
Composants UI

Composant Composer

Le composant Composer fournit une API déclarative (booléens show-*) et des modèles v-model:* pour construire des interfaces de saisie d'e-mail ou de commentaire.

Composer

Le composant Composer fournit une API déclarative permettant de construire des interfaces de saisie d'e-mail ou de commentaire. Il expose deux sous-composants prêts à l'emploi : EmailComposer pour rédiger des e-mails (champs De / À / Cc / Cci, sujet, pièces jointes) et CommentComposer pour rédiger des commentaires. Chaque sous-composant gère lui-même sa barre de formatage, la sélection des destinataires sous forme de jetons, le glisser-déposer des destinataires d'une ligne à l'autre et les interactions clavier.

Bon à savoir

Ce composant Vue fait partie du paquet @framework/ui. Il sert aux applications Vue et aux vues personnalisées (portail, page sur mesure). La fenêtre d'e-mail des formulaires du bureau est un autre composant.

API commune

Les deux sous-composants (EmailComposer et CommentComposer) partagent une API commune :

  • extensions : permet de fournir des extensions Tiptap additionnelles. Les extensions hôtes sont ajoutées après le kit de texte riche intégré, ce qui permet de surcharger ses valeurs par défaut.
  • max-attachments : nombre maximal de pièces jointes autorisées (10 par défaut).

EmailComposer

EmailComposer gère la rédaction d'un e-mail complet : champs d'en-tête, sujet, corps du message et pièces jointes.

Visibilité des champs d'en-tête

Chaque champ d'en-tête dispose d'un prop booléen pour afficher ou masquer sa ligne. Les champs À, Cc et Cci sont visibles par défaut ; les champs De et Sujet sont masqués par défaut.

<EmailComposer
  show-from
  show-subject
  :show-bcc="false"
  v-model:to="to"
  v-model:cc="cc"
  @submit="onSend"
/>

Modèles de données pour les destinataires

Les destinataires sont liés individuellement via trois modèles distincts : v-model:to, v-model:cc et v-model:bcc. Chacun attend un tableau d'objets Recipient.

Le payload émis lors de l'événement @submit est aplati : lisez payload.to, payload.cc et payload.bcc directement (il n'existe plus de clé payload.recipients).

function onSend(payload) {
  // payload.to -> array de destinataires principaux
  // payload.cc -> array de destinataires en copie
  // payload.bcc -> array de destinataires en copie cachée
}

Slot #header

Le slot #header permet de remplacer entièrement la zone d'en-tête. Lorsqu'il est utilisé, les props show-* n'ont plus d'effet. Ce slot est utile pour insérer des champs personnalisés ou une mise en page spécifique.

CommentComposer

CommentComposer est une variante simplifiée du EmailComposer : il n'expose ni champs d'en-tête, ni sujet, ni destinataires. Il gère uniquement la saisie d'un texte riche et la gestion des pièces jointes. Utilisez-le dans les fils de commentaires ou les zones de réponse rapide.

Sélection des destinataires

Les destinataires apparaissent sous forme de jetons (chips) dans chaque champ. Le composant gère lui-même la sélection par clavier et l'alignement sur plusieurs lignes. Glissez un jeton vers une autre ligne (par exemple de À à Cc) pour déplacer le destinataire.

Pièces jointes

Le composant permet de joindre des fichiers avec le bouton trombone de la barre d'outils. Les pièces jointes s'affichent sur des lignes qui s'enroulent, et chaque fichier est accompagné d'une icône correspondant à son type. Le nombre maximal de pièces jointes est contrôlé par le prop max-attachments (10 par défaut).

Interactions clavier

  • Backspace sur un champ vide sélectionne le dernier jeton de destinataire.
  • Backspace sur un jeton sélectionné le supprime.
  • Échap vide le compositeur (reset()), sauf si une liste ouverte l'a déjà utilisée.

État d'envoi

Le compositeur ne sait pas de lui-même si un message est en cours d'envoi : c'est l'application qui l'héberge qui déclenche l'envoi. Pour offrir à l'utilisateur une indication visuelle claire, vous pouvez passer un booléen submitting au compositeur.

Tant que ce booléen vaut true :

  • Le bouton d'envoi affiche un indicateur de chargement (un petit cercle qui tourne) après son libellé.
  • Le bouton devient inactif : il ignore les clics et le raccourci clavier de soumission.
  • L'attribut aria-busy est positionné sur le bouton, ce qui permet aux lecteurs d'écran d'indiquer qu'une action est en cours.

Cela évite les doubles envois et rassure l'utilisateur : le message est parti, le système travaille.

:::dokos Astuce Associez l'activation de submitting à un libellé plus court. Par exemple, au lieu d'afficher « Envoyer l'e-mail », basculez le libellé sur « Envoi » pendant la soumission, puis réinitialisez le compositeur une fois l'envoi terminé. :::

Exemple d'utilisation

// Dans votre composant Vue qui héberge le compositeur
import { EmailComposer } from '@framework/ui'

export default {
  components: { EmailComposer },
  data() {
    return {
      submitting: false
    }
  },
  methods: {
    async handleSend() {
      this.submitting = true
      try {
        await this.envoyerMessage()
      } finally {
        this.submitting = false
      }
    }
  }
}

<EmailComposer :submitting="submitting" @submit="handleSend" />

Emplacement de pied de page

Le compositeur expose un emplacement nommé #footer disponible entre le corps du message (après la zone des pièces jointes) et la barre d'outils inférieure.

Cet emplacement est conçu pour recevoir des actions que vous souhaitez voir apparaître au-dessus de la barre d'outils, par exemple un panneau de réponses enregistrées, des modèles de message, ou un aperçu des destinataires.

<EmailComposer>
  <template #footer>
    <div class="mes-actions-supplementaires">
      <!-- Vos actions ici -->
    </div>
  </template>
</EmailComposer>