SModal <s-modal>

Uma caixa de diálogo sobreposta para tarefas focadas e confirmações, aberta por um comando ou uma chamada de método. SModal é o wrapper de Vue 3 tipado do web component <s-modal> do Shopify Polaris.

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

Boas práticas

• Reserve os modais para decisões que exigem foco. Abra um quando os lojistas precisarem fazer uma escolha específica ou tomar ciência de algo crítico. Se a tarefa ou a ferramenta puder ficar diretamente na página, mantenha-a lá.
• Use-os com moderação. Todo modal interrompe o lojista, então trate-o como último recurso para momentos importantes, e não como um padrão.
• Destaque a ação principal. Dê ao modal uma única chamada para ação clara e em evidência no slot primary-action.
• Rotule as ações com verbos específicos. Botões como "Excluir", "Salvar" ou "Continuar" dizem aos lojistas o que vai acontecer; evite rótulos genéricos como "Sim", "OK" ou "Enviar".
• Deixe claras as consequências das ações destrutivas. Quando a ação exclui ou descarta algo, descreva no corpo do modal o que os lojistas vão perder.
• Não aninhe modais. Evite abrir um segundo modal de dentro de um que já está aberto.

<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>

Veja as boas práticas da Shopify para <s-modal> (em inglês) para todas as recomendações.

Exemplo

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	Tipo	Descrição
accessibilityLabel	string	Um rótulo que descreve a finalidade do modal. Quando definido, é anunciado aos usuários de tecnologias assistivas e oferece mais contexto a eles. Para leitores de tela, substitui a prop heading.
heading	string	Um título que descreve o conteúdo do modal.
padding	"base" | "none"	Ajusta o espaçamento interno (padding) ao redor do conteúdo do modal. base: aplica um espaçamento interno adequado ao elemento. none: remove todo o espaçamento interno do elemento. Isso pode ser útil quando elementos dentro do modal precisam se estender até a borda do modal, por exemplo, uma imagem de largura total. Nesse caso, use um box com padding de 'base' para restaurar o espaçamento interno desejado no restante do conteúdo.
size	"base" | "small-100" | "small" | "large" | "large-100"	O tamanho do componente de modal, que controla sua largura e altura. Tamanhos maiores oferecem mais espaço para o conteúdo, enquanto tamanhos menores são mais compactos.

Events

Event	Tipo
afterhide	CustomEvent
aftershow	CustomEvent
hide	CustomEvent
show	CustomEvent

Escute-os com listeners no estilo @afterhide em <SModal>.

Methods

<SModal> expõe os seguintes métodos no elemento DOM subjacente (acessíveis por meio de uma template ref tipada):

• hideOverlay() => void — Método para ocultar uma sobreposição.
• showOverlay() => void — Método para exibir uma sobreposição.
• toggleOverlay() => void — Método para alternar a visibilidade de uma sobreposição.

<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	Descrição
default	O conteúdo exibido dentro do componente de modal, que normalmente inclui campos de formulário, informações ou elementos interativos.
primary-action	O botão de ação principal exibido no rodapé do modal, que representa a ação principal que os usuários devem realizar. Aceita apenas um único componente de botão com variant igual a primary. Esta ação deve estar alinhada ao objetivo principal do modal.
secondary-actions	Botões de ação adicionais exibidos no rodapé do modal, oferecendo ações alternativas ou complementares. Aceita apenas componentes de botão com variant igual a secondary ou auto. Eles têm menos ênfase visual para estabelecer uma hierarquia clara.