Uso dell'API DModal per renderizzare finestre modali (aka popup/dialoghi) in Discourse

Discourse 3.1.0.beta6 include una nuova API basata su componenti <DModal>. DModal fa parte dell’UI kit e viene importato da discourse/ui-kit/d-modal.

:information_source: Questo sostituisce la vecchia API basata su controller, ora deprecata. Se disponi di modali esistenti che utilizzano le vecchie API, consulta la guida alla migrazione qui.

Rendering di una Modal

Le modali vengono renderizzate includendo il componente <DModal> in un template handlebars. Se non hai già un template adatto, consulta Using Plugin Outlet Connectors from a Theme or Plugin.

Una modale semplice apparirebbe così:

<DButton
  @translatedLabel="Show Modal"
  @action={{fn (mut this.modalIsVisible) true}}
/>

{{#if this.modalIsVisible}}
  <DModal @title="My Modal" @closeModal={{fn (mut this.modalIsVisible) false}}>
    Hello world, this is some content in a modal
  </DModal>
{{/if}}

:information_source: L’helper mut viene utilizzato qui come metodo esclusivamente hbs per impostare un valore. Puoi anche impostare modalIsVisible utilizzando qualsiasi altro metodo standard Ember.

Questo esempio creerà una Modale semplice come questa:

Wrapping in un componente

Prima di introdurre ulteriore complessità, di solito è consigliabile incapsulare la tua nuova Modale in una definizione di Componente dedicata. Spostiamo il codice di <DModal> all’interno di un nuovo componente <MyModal />

// components/my-modal.gjs
<template>
  <DModal @title="My Modal" @closeModal={{@closeModal}}>
    Hello world, this is some content in a modal
  </DModal>
</template>

Aggiornando questo file .gjs a un componente basato su classi, potrai introdurre logica e stato più complessi.

Per utilizzare il nuovo componente, aggiorna il punto di chiamata per riferirlo, assicurandoti di passare l’argomento @closeModal.

<DButton
  @translatedLabel="Show Modal"
  @action={{fn (mut this.modalIsVisible) true}}
/>

{{#if this.modalIsVisible}}
  <MyModal @closeModal={{fn (mut this.modalIsVisible) false}} />
{{/if}}

Aggiunta di un footer

Molte modali hanno qualche tipo di call-to-action. In Discourse, queste tendono ad essere posizionate in fondo alla modale. Per rendere ciò possibile, DModal ha diversi “named blocks” nei quali è possibile renderizzare contenuti. Ecco l’esempio aggiornato per includere due pulsanti nel footer, uno dei quali è il nostro pulsante standard DModalCancel

<DModal @title="My Modal" @closeModal={{@closeModal}}>
  <:body>
    Hello world, this is some content in a modal
  </:body>
  <:footer>
    <DButton class="btn-primary" @translatedLabel="Submit" />
    <DModalCancel @close={{@closeModal}} />
  </:footer>
</DModal>

Renderizzare una modale da un contesto non-hbs

Idealmente, le istanze di <DModal> dovrebbero essere renderizzate all’interno di un template Ember utilizzando la tecnica dichiarativa dimostrata sopra. Se ciò non è fattibile per il tuo caso d’uso, è possibile farlo iniettando il servizio modal e chiamando modal.show().

Assicurati di aver incapsulato la tua modale nel proprio componente come descritto sopra. Quindi, attiva la modale passando un riferimento alla classe del tuo componente a showModal:

import MyModal from "discourse/components/my-modal";

// (inietta il servizio modal nel posto rilevante)

// Aggiungi questa chiamata ogni volta che vuoi aprire la modale.
// Un argomento `@closeModal` verrà passato automaticamente al tuo componente.
this.modal.show(MyModal);

// Facoltativamente, passa un parametro '`model`'. Passato come `@model` al tuo componente.
// Può includere dati, oltre ad azioni/callback per l'uso nella tua Modale.
this.modal.show(MyModal, {
  model: { topic: this.topic, someAction: this.someAction },
});

// `modal.show()` restituisce una promise, quindi puoi attendere che venga chiusa
// Si risolve con i dati passati all'azione `@closeModal`
const result = await this.modal.show(MyModal);

Maggiore personalizzabilità!

<DModal> ha diversi named blocks e argomenti.

Argomenti

Arg Scopo
@closeModal Necessario affinché l’interfaccia di chiusura appaia.
@title Renderizza <h1 id="discourse-modal-title">; collega aria-labelledby.
@subtitle Testo piccolo sotto il titolo.
@flash / @flashType Alert inline nella parte superiore della modale (DFlashMessage).
@hideHeader, @hideFooter Nasconde le intere regioni.
@headerClass, @bodyClass Classe extra sui wrapper di intestazione/corpo.
@dismissable Vero di default quando è impostato @closeModal. Disabilita Esc / clic sul backdrop / X.
@autofocus Vero di default. Autoseleziona il primo elemento focalizzabile tramite dTrapTab.
@submitOnEnter Vero di default. Invio clicca .d-modal__footer .btn-primary a meno che il focus non sia in un form / textarea / select-kit.
@beforeClose async ({ initiatedBy }) => boolean. Restituisci false per annullare la chiusura (es. conferma form sporco).
@hidden Mette in pausa la gestione della tastiera; usato quando una modale annidata è in primo piano.
@tagName "div" (default) o "form". Usa "form" per i moduli in modo che l’invio nativo funzioni.

Blocchi

Blocco Posizione Quando usare
default / :body Area dei contenuti principale Area predefinita
:aboveHeader In cima, prima dell’intestazione Raramente necessario; per contenuti che devono stare sopra la barra del titolo (es. un banner).
:headerAboveTitle Dentro l’intestazione, prima del titolo Presente ma inutilizzato. Raramente necessario.
:belowModalTitle Dentro .d-modal__title, dopo l’

Ottima posizione per informazioni supplementari.
:headerBelowTitle Dentro l’intestazione, dopo il blocco titolo Tab, sottomenu o campo di ricerca che fa parte dell’intestazione.
:headerPrimaryAction Lato destro dell’intestazione solo su mobile Sostituisce il pulsante di chiusura X con un’azione primaria (es. “Salva”). Inoltre, renderizza automaticamente un pulsante “Annulla” a sinistra e aggiunge .--has-primary-action all’intestazione.
:belowHeader Tra intestazione e corpo Contenuto persistente del sotto-intestazione (es. barra di ricerca) che si trova fuori dal corpo scorrevole, quindi visualizzazione sticky.
:aboveFooter Tra corpo e footer Soppresso quando @hideFooter è impostato. Usa per contenuti legati al footer ma al di fuori di esso. Anche raro.
:footer Barra delle azioni in fondo Pulsanti primari + secondari. Il primo .btn-primary qui è ciò che Invio attiva.
:belowFooter Dopo il footer Raramente necessario; ignora @hideFooter. Utile per testi di stato all’esterno dell’area del footer con bordo.

Fonti: la guida di stile interattiva per gli argomenti, e l’implementazione del template d-modal per i named blocks.

CSS

Usa le classi .d-modal come ancoraggio per sovrascrivere il core, ed evita il selettore legacy .modal.

Sono disponibili 4 modificatori:

  • .--large imposta la larghezza massima a 800px (solo desktop)
  • .--max imposta la larghezza massima a 90vw (solo desktop)
  • .--has-search imposta l’altezza fissa (80vh): destinato alle modali con sistema di ricerca/filtro per evitare variazioni di altezza in base alla lunghezza dei risultati (solo desktop)
  • .--stacked imposta i pulsanti del footer in impilamento (solo mobile)

Questo documento è controllato in versione - suggerisci modifiche su github.

17 Mi Piace

Un post è stato diviso in un nuovo argomento: Posso mostrare una modale da head_tag