AMP

Azioni ed eventi nelle e-mail AMP

Questa documentazione descrive azioni ed eventi relativi al formato delle e-mail AMP. Leggi anche il documento Azioni ed eventi per siti web, storie e annunci.

L'attributo on viene utilizzato per installare i gestori di eventi sugli elementi. Gli eventi supportati dipendono dall'elemento.

Il valore per la sintassi è un semplice linguaggio specifico del dominio del modulo:

eventName:targetId[.methodName[(arg1=value, arg2=value)]]

Consultare la tabella seguente per le descrizioni di ciascun elemento della sintassi.

Sintassi Obbligatorio? Descrizione
eventName Questo è il nome dell'evento esposto da un elemento.
targetId Questo è l'id DOM dell'elemento, oppure un target speciale predefinito su cui occorre eseguire un'azione in risposta all'evento. Nel seguente esempio, il targetId è l'id DOM del target amp-lightbox, photo-slides.
 
methodName no Questo si riferisce ad elementi con azioni predefinite.

Si tratta del metodo esposto dall'elemento target (referenziato da targetId) che deve essere eseguito all'attivazione dell'evento.

L'AMP prevede il concetto di azioni predefinite che possono essere implementate dagli elementi. Perciò omettendo methodName, l'AMP eseguirà il metodo predefinito.

arg=value no Alcune azioni, se documentate, possono accettare argomenti. Gli argomenti sono definiti tra parentesi nella notazione key=value. I valori accettati sono:
  • stringhe semplici senza virgolette: simple-value
  • stringhe con virgolette: "string value" oppure 'string value'
  • valori booleani: true o false
  • numeri: 11 o 1.1
  • dati con sintassi puntata riferiti ad eventi: event.someDataVariableName

Gestione di più eventi

Si possono leggere più eventi su un elemento separando gli eventi con un punto e virgola ;.

Esempio: on="submit-success:lightbox1;submit-error:lightbox2"

Azioni multiple per un evento

È possibile eseguire più azioni in sequenza per lo stesso evento separando le azioni con una virgola ",".

Esempio: on="tap:target1.actionA,target2.actionB"

Eventi e azioni definiti a livello globale

AMP permette di definire un evento tap globale che può essere ricevuto su qualsiasi elemento HTML (inclusi gli elementi AMP).

AMP permette inoltre di definire le azioni globali hide, show e toggleVisibility che possono essere attivate su qualsiasi elemento HTML.

Un elemento può essere mostrato solo se in precedenza era stato nascosto da un'azione hide o toggleVisibility, oppure usando l'attributo hidden. L'azione show non supporta elementi nascosti dall'attributo CSS display:none o dall'attributo AMP layout=nodisplay.

Ad esempio, in AMP è possibile la seguente struttura:

<div id="warning-message">Warning...</div>

<button on="tap:warning-message.hide">Cool, thanks!</button>

Eventi specifici di un elemento

* - tutti gli elementi

Evento Descrizione
tap Attivazione facendo clic o toccando l'elemento.

Elementi di input

Evento Descrizione Elementi Dati
change Attivazione quando il valore dell'elemento viene modificato e confermato.

Le proprietà dei dati rispecchiano quelle in HTMLInputElement e HTMLSelectElement.

input
event.min
event.max
event.value
event.valueAsNumber
input[type="radio"],
input[type="checkbox"]
event.checked
select
event.min
event.max
event.value
input-debounced Attivazione quando il valore dell'elemento viene modificato. È simile all'evento change standard, ma si attiva solo quando sono trascorsi 300 ms senza che il valore dell'input subisca variazioni. Elementi che attivano l'evento input. Gli stessi dati dell'evento change.
input-throttled Attivazione quando il valore dell'elemento viene modificato. È simile all'evento change standard, ma può essere attivato al massimo una volta ogni 100 ms mentre il valore dell'input cambia. Elementi che attivano l'evento input. Gli stessi dati dell'evento change.

amp-accordion > section

Evento Descrizione Dati
expand Attivazione all'espansione di una sezione a soffietto. Nessuno.
collapse Attivazione alla compressione di una sezione a soffietto. Nessuno.

amp-carousel[type="slides"]

Evento Descrizione Dati
slideChange Attivazione quando cambia la diapositiva corrente di una sequenza.
// Numero diapositiva.
event.index

amp-lightbox

Evento Descrizione Dati
lightboxOpen Attivazione quando il lightbox è completamente visibile. Nessuno
lightboxClose Attivazione quando il lightbox è completamente chiuso. Nessuno

amp-list

Evento Descrizione Dati
fetch-error(bassa affidabilità) Attivazione quando il recupero dei dati non riesce. Nessuno

amp-selector

Evento Descrizione Dati
select Attivazione quando un'opzione è selezionata o deselezionata.
// Valore dell'attributo "option" dell'elemento target. event.targetOption
// Array di valori degli attributi "option" di tutti gli elementi selezionati. event.selectedOptions

amp-sidebar

Evento Descrizione Dati
sidebarOpen Attivazione quando la barra laterale è completamente aperta al termine della transizione. Nessuno
sidebarClose Attivazione quando la barra laterale è completamente chiusa al termine della transizione. Nessuno

amp-state

Evento Descrizione Dati
fetch-error(bassa affidabilità) Attivazione quando il recupero dei dati non riesce. Nessuno

form

Evento Descrizione Dati
submit Attivazione all'invio del modulo.
submit-success Attivazione quando la risposta all'invio del modulo ha successo.
// Response JSON.
event.response
submit-error Attivazione quando la risposta all'invio del modulo è un errore.
// Response JSON.
event.response
valid Attivazione quando il modulo è valido.
invalid Attivazione quando il modulo non è valido.

Azioni specifiche di un elemento

* (tutti gli elementi)

Azione Descrizione
hide Nasconde l'elemento target.
show Mostra l'elemento target. Se un elemento autofocus diventa visibile di conseguenza, la sua messa a fuoco aumenta.
toggleVisibility Attiva e disattiva la visibilità dell'elemento target. Se un elemento autofocus diventa visibile di conseguenza, esso diventa attivo.
toggleClass(class=STRING, force=BOOLEAN) Alterna le classi dell'elemento target. L'attributo force è opzionale e, se definito, garantisce che la classe sia solo aggiunta ma non rimossa, se l'opzione è impostata su true, e che essa sia solo rimossa ma non aggiunta, se l'opzione è impostata su false.
focus Aumenta la messa a fuoco dell'elemento target. Per ridurre la messa a fuoco, attivare il focus su un altro elemento (di solito l'elemento genitore). Sconsigliamo di ridurre la messa a fuoco di un elemento, attivando il focus sull'elemento body/documentElement per motivi di accessibilità.

amp-accordion

Azione Descrizione
toggle(section=STRING) Alterna gli stati expanded e collapsed delle sezioni amp-accordion. Quando l'azione è richiamata senza argomenti, essa alterna tutte le sezioni del pannello a soffietto. Per attivare una sezione specifica occorre fornire l'id della sezione: on="tap:myAccordion.toggle(section='section-id')".
expand(section=STRING) Espande le sezioni del pannello a soffietto. Se una sezione è già espansa, rimane espansa. Quando l'azione è richiamata senza argomenti, essa espande tutte le sezioni del pannello a soffietto. Per attivare una sezione specifica occorre fornire l'id della sezione: on="tap:myAccordion.expand(section='section-id')".
collapse(section=STRING) Comprime le sezioni del pannello a soffietto. Se una sezione è già compressa, rimane compressa. Quando l'azione è richiamata senza argomenti, essa comprime tutte le sezioni del pannello a soffietto. Per attivare una sezione specifica occorre fornire l'id della sezione: on="tap:myAccordion.collapse(section='section-id')".

amp-carousel[type="slides"]

Azione Descrizione
goToSlide(index=INTEGER) Avanza nella sequenza fino alla diapositiva che occupa la posizione dell'indice specificato.

amp-image-lightbox

Azione Descrizione
open (default) Apre il lightbox dell'immagine con l'immagine sorgente che ha attivato l'azione.

amp-lightbox

Azione Descrizione
open (default) Apre il lightbox.
close Chiude il lightbox.

amp-list

Evento Descrizione Dati
changeToLayoutContainer Aggiorna il layout di amp-list a layout="CONTAINTER" per consentire il ridimensionamento dinamico.
fetch-error(bassa affidabilità) Attivazione quando il recupero dei dati non riesce. None

amp-selector

Azione Descrizione
clear Cancella tutte le selezioni da un elemento amp-selector definito.
selectUp(delta=INTEGER) Sposta la selezione verso l'alto del valore indicato dal parametro 'delta'. Il valore predefinito di 'delta' è -1. Se non sono selezionate opzioni, lo stato selezionato diventerà il valore dell'ultima opzione.
selectDown(delta=INTEGER) Sposta la selezione verso il basso del valore indicato dal parametro 'delta'. Il valore predefinito di 'delta' è -1. Se non sono selezionate opzioni, lo stato selezionato diventerà il valore della prima opzione.
toggle(index=INTEGER, value=BOOLEAN) Attiva o disattiva l'applicazione dell'elemento 'selezionato'. Se l'attributo select è assente, questa azione lo aggiunge. Se l'attributo select è presente, questa azione lo rimuove. Per forzare un'aggiunta o una rimozione, occorre includere un valore booleano nell'argomento 'value'. Un valore "true" forzerà l'aggiunta dell'attributo 'selected' e non lo rimuoverà se già presente. Un valore 'false' rimuoverà l'attributo, ma non lo aggiungerà se è assente.

amp-sidebar

Azione Descrizione
open (default) Apre la barra laterale.
close Chiude la barra laterale.
toggle Alterna gli stati della barra laterale.

form

Azione Descrizione
clear Cancella tutti i valori nei campi di input del modulo.
submit Invia il modulo.

Target speciali

Di seguito sono riportati i target forniti dal sistema AMP con requisiti speciali:

Target: AMP

Il target AMP è fornito dal sistema di runtime AMP e implementa azioni di primo livello che si applicano all'intero documento.

Azione Descrizione
setState({foo: 'bar'})1

Richiede amp-bind.

Aggiunge il valore letterale di un oggetto allo stato associabile.

1In caso di utilizzo con azioni multiple, le azioni successive attenderanno il completamento di setState() prima della chiamata. Per ogni evento è consentita una sola chiamata di setState().