SModal <s-modal>

Une boîte de dialogue en superposition pour les tâches ciblées et les confirmations, ouverte par une commande ou un appel de méthode. SModal est le wrapper Vue 3 typé du web component <s-modal> de Shopify Polaris.

import { SModal } from 'polaris-vue-elements'

Bonnes pratiques

• Réservez les modales aux décisions qui demandent de la concentration. Ouvrez-en une lorsque les marchands doivent faire un choix précis ou prendre connaissance d'une information critique. Si la tâche ou l'outil peut figurer directement sur la page, laissez-le plutôt là.
• Utilisez-les avec parcimonie. Chaque modale interrompt le marchand : traitez-la comme un dernier recours pour les moments importants plutôt que comme un modèle par défaut.
• Faites ressortir l'action principale. Donnez à la modale un appel à l'action clair et bien visible dans le slot primary-action.
• Utilisez des verbes précis pour les actions. Des boutons comme "Delete", "Save" ou "Continue" disent aux marchands ce qui va se passer ; évitez les libellés génériques comme "Yes", "OK" ou "Submit".
• Explicitez les conséquences des actions destructives. Lorsque l'action supprime ou abandonne quelque chose, décrivez dans le corps de la modale ce que les marchands vont perdre.
• N'imbriquez pas les modales. Évitez d'ouvrir une seconde modale depuis une modale déjà ouverte.

<SModal id="delete-product" heading="Delete product?">
  <SParagraph>This permanently deletes the product and its variants. You can't undo this.</SParagraph>
  <SButton slot="primary-action" tone="critical">Delete product</SButton>
  <SButton slot="secondary-actions">Cancel</SButton>
</SModal>

Consultez les bonnes pratiques de Shopify pour <s-modal> (en anglais) pour l'ensemble des recommandations.

Exemple

Open modal

Modal body content goes here.

SaveCancel

<script setup>
import { SButton, SModal } from 'polaris-vue-elements'
</script>

<template>
  <SButton commandFor="example-modal" command="--show">Open modal</SButton>

  <SModal id="example-modal" heading="Example modal">
    <p>Modal body content goes here.</p>

    <!-- The runtime only accepts a primary-action button with variant="primary",
         and secondary-actions buttons with variant="secondary" (or "auto"). -->
    <template #primary-action>
      <SButton variant="primary">Save</SButton>
    </template>
    <template #secondary-actions>
      <SButton variant="secondary">Cancel</SButton>
    </template>
  </SModal>
</template>

Props

Prop	Type	Description
accessibilityLabel	string	Un libellé qui décrit l'objectif de la modale. Lorsqu'il est défini, il est annoncé aux utilisateurs de technologies d'assistance et leur apporte davantage de contexte. Il remplace la prop heading pour les lecteurs d'écran.
heading	string	Un titre qui décrit le contenu de la modale.
padding	"base" | "none"	Ajuste le padding autour du contenu de la modale. base : applique un padding adapté à l'élément. none : supprime tout padding de l'élément. Cela peut être utile lorsque des éléments de la modale doivent s'étendre jusqu'à ses bords, par exemple une image pleine largeur. Dans ce cas, utilisez une box avec un padding 'base' pour rétablir le padding souhaité pour le reste du contenu.
size	"base" | "small-100" | "small" | "large" | "large-100"	La taille du composant modal, qui contrôle sa largeur et sa hauteur. Les grandes tailles offrent plus d'espace pour le contenu, tandis que les petites sont plus compactes.

Events

Event	Type
afterhide	CustomEvent
aftershow	CustomEvent
hide	CustomEvent
show	CustomEvent

Écoutez-les avec des listeners de la forme @afterhide sur <SModal>.

Methods

<SModal> expose les méthodes suivantes sur son élément DOM sous-jacent (accessibles via une template ref typée) :

• hideOverlay() => void — Méthode pour masquer un overlay.
• showOverlay() => void — Méthode pour afficher un overlay.
• toggleOverlay() => void — Méthode pour basculer la visibilité d'un overlay.

<script setup>
import { useTemplateRef } from 'vue'
import { SModal } from 'polaris-vue-elements'

const modal = useTemplateRef<InstanceType<typeof SModal>>('modal')

function callHideOverlay() {
  modal.value?.$el.hideOverlay()
}
</script>

<template>
  <SModal ref="modal" />
</template>

Slots

Slot	Description
default	Le contenu affiché dans le composant modal, comprenant généralement des champs de formulaire, des informations ou des éléments interactifs.
primary-action	Le bouton d'action principale affiché dans le pied du modal, représentant l'action principale que les utilisateurs doivent effectuer. N'accepte qu'un seul composant button avec un variant primary. Cette action doit correspondre à l'objectif principal du modal.
secondary-actions	Boutons d'action supplémentaires affichés dans le pied de la modale, proposant des actions alternatives ou complémentaires. N'accepte que des composants bouton avec une variant égale à secondary ou auto. Ils sont visuellement atténués afin d'établir une hiérarchie claire.