AMP

Ações e eventos no e-mail AMP

Esta documentação cobre ações e eventos para o formato de e-mail AMP. Leia Ações e eventos para sites AMP, histórias e anúncios.

O atributo on é usado para instalar handlers de eventos em elementos. Os eventos que são suportados dependem do elemento.

O valor para a sintaxe é uma simples linguagem de domínio específica da forma:

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

Veja a tabela abaixo para descrições de cada parte da sintaxe.

Sintaxe Obrigatório? Descrição
eventName sim Este é o nome do evento que um elemento expõe.
targetId sim Este é a id do DOM para o elemento, ou um alvo especial predefinido sobre o qual você gostaria de executar uma ação em resposta ao evento. No exemplo a seguir, o targetId é o id do DOM para o alvo amp-lightbox, photo-slides.
<amp-lightbox id="photo-slides"></amp-lightbox> <button on="tap:photo-slides">Mostrar Imagens</button>
methodName não Isto é para elementos com ações default.

Este é o método que o elemento alvo (referenciado por targetId) expõe e que você gostaria de executar quando o evento for disparado.

AMP possui um conceito de ação default que elementos podem implementar. Portanto, ao omitir o methodName, o AMP irá executar esse método default.

arg=value não Algumas ações, se documentadas, podem aceitar argumentos. Os argumentos são definidos entre parênteses na notação chave=valor. Os valores aceitos são:
  • cadeias de caracteres simples sem aspas: simple-value
  • cadeias de caracteres com aspas: "string value" ou 'string value'
  • valores booleanos: true ou false
  • números: 11 ou 1.1
  • referência para dados do evento usando sintaxe-ponto: event.someDataVariableName

Lidando com múltiplos eventos

Você pode escutar múltiplos eventos em um elemento separando os eventos com um ponto-e-vírgula ;.

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

Múltiplas ações para um evento

Você pode executar múltiplas ações em sequência para o mesmo evento, separando as ações com uma vírgula

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

Eventos e ações definidos globalmente

O AMP define um evento tap no escopo global que você pode escutar em qualquer elemento HTML (inclusive elementos AMP).

O AMP também define as ações hide, show e toggleVisibility globalmente, que você pode ativar em qualquer elemento HTML.

Um elemento só pode ser mostrado se estiver anteriormente oculto por uma ação hide ou toggleVisibility ou usando o atributo hidden. A ação show não suporta elementos ocultos pela propriedade display:none do CSS ou pelo layout=nodisplay do AMP.

Por exemplo, o seguinte é possível em AMP:

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

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

Eventos específicos por elemento

* - todos os elementos

Evento Descrição
tap Disparado quando o elemento recebe um clique/toque.

Elementos de entrada

Evento Descrição Elementos Dados
change Disparado quando o valor do elemento é alterado e confirmado.

As propriedades de dados espelham as do HTMLInputElement e do 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 Disparado quando o valor do elemento é alterado. Isto é semelhante ao evento change padrão, mas só dispara depois que se passaram 300ms desde que o valor da entrada parou de mudar. Elementos que disparam o evento input. Mesmos dados do evento change.
input-throttled Disparado quando o valor do elemento é alterado. Isto é semelhante ao evento change padrão, mas disparar no máximo uma vez a cada 100ms enquanto o valor da entrada está mudando. Elementos que disparam o evento input. Mesmos dados do evento change.

amp-accordion > section

Evento Descrição Dados
expand Disparado quando uma seção do acordeon expande. Nenhum.
collapse Disparado quando uma seção do acordeon fecha. Nenhum.

amp-carousel[type="slides"]

Evento Descrição Dados
slideChange Disparado quando o carrossel muda de slide.
// Slide number.
event.index

amp-lightbox

Evento Descrição Dados
lightboxOpen Disparado quando a lightbox estiver totalmente visível. Nenhum.
lightboxClose Disparado quando a lightbox estiver totalmente fechada. Nenhum.

amp-list

Evento Descrição Dados
fetch-error (baixa confiança) Disparado quando a recuperação de dados falha. Nenhum.

amp-selector

Evento Descrição Dados
select Disparado quando uma opção é selecionada ou deselecionada.
// Target element's "option" attribute value.
event.targetOption
// Array of "option" attribute values of all selected elements.
event.selectedOptions

amp-sidebar

Evento Descrição Dados
sidebarOpen Disparado quando a barra lateral estiver totalmente aberta depois que uma transição é finalizada. Nenhum.
sidebarClose Disparado quando a barra lateral estiver totalmente fechada depois que uma transição é finalizada. Nenhum.

amp-state

Evento Descrição Dados
fetch-error (baixa confiança) Disparado quando a recuperação de dados falha. Nenhum.

form

Evento Descrição Dados
submit Disparado quando o formulário é enviado.
submit-success Disparado quando a resposta ao formulário for bem sucedida.
// Response JSON.
event.response
submit-error Disparado quando a resposta ao formulário for um erro.
// Response JSON.
event.response
valid Disparado quando o formulário é válido.
invalid Disparado quando o formulário é inválido.

Element-specific actions

* (all elements)

Ação Descrição
hide Oculta o elemento-alvo
show Exibe o elemento-alvo. Se um elemento autofocus se torna visível como resultado, ele ganha foco.
toggleVisibility Alterna a visibilidade do elemento alvo. Se um elemento autofocus se torna visível como resultado, ele ganha foco.
toggleClass(class=STRING, force=BOOLEAN) Alterna a classe do elemento-alvo. force é opcional e, se definido, garante que a classe seja apenas adicionada, mas não removida, se configurada como true e removida, mas não adicionada, se configurada como false.
focus Faz o elemento alvo ganhar foco. Para perder o foco, aplique focus em outro elemento (geralmente no elemento pai). Aconselhamos fortemente contra perder o foco ao focar no body/documentElement por razões de acessibilidade.

amp-accordion

Ação Descrição
toggle(section=STRING) Alterna os estados expanded e collapsed das seções amp-accordion. Quando chamado sem argumentos, ele alterna todas as seções do acordeon. Dispare numa seção específica fornecendo o id da seção: on="tap:myAccordion.toggle(section=id')".
expand(section=STRING) Abre as seções do acordeon. Se uma seção já estiver aberta, ela permanece aberta. Quando chamado sem argumentos, ele alterna todas as seções do acordeon. Dispare numa seção específica fornecendo o id da seção: on="tap:myAccordion.expand(section=
collapse(section=STRING) Fecha as seções do acordeon. Se uma seção já estiver fechada, ela permanece fechada. Quando chamado sem argumentos, ele alterna todas as seções do acordeon. Dispare numa seção específica fornecendo o id da seção: on="tap:myAccordion.collapse(section=

amp-carousel[type="slides"]

Ação Descrição
goToSlide(index=INTEGER) Avança o carrossel para um índice de slide especificado.

amp-image-lightbox

Ação Descrição
open (default) Abre a lightbox da imagem, com a imagem-fonte sendo a que disparou a ação.

amp-lightbox

Ação Descrição
open (default) Abre a lightbox.
close Fecha a lightbox.

amp-list

Evento Descrição Dados
changeToLayoutContainer Atualiza o layout de amp-list para layout="CONTAINTER" para permitir redimensionamento dinâmico.
fetch-error (baixa confiança) Disparado quando a recuperação de dados falha. Nenhum.

amp-selector

Ação Descrição
clear Limpa todas as seleções de um amp-selector definido.
selectUp(delta=INTEGER) Move a seleção para cima pelo valor `delta`. O `delta` default é definido como -1. Se nenhuma opção for selecionada, o estado selecionado será o valor da última opção.
selectDown(delta=INTEGER) Move a seleção para baixo pelo valor `delta`. O `delta` default é definido como 1. Se nenhuma opção for selecionada, o estado selecionado será o valor da primeira opção.
toggle(index=INTEGER, value=BOOLEAN) Alterna a aplicação do `selected`. Se o atributo select estiver ausente, esta ação o adiciona. Se o atributo select estiver presente, esta ação o remove. Você pode forçar e manter uma adição ou remoção incluindo um valor booleano no argumento `value`. Um valor `true` forçará a adição do atributo `selected` e não o removerá se ele já estiver presente. Um valor `false` removerá o atributo, mas não o adicionará se ausente.

amp-sidebar

Ação Descrição
open (default) Abre a barra lateral.
close Fecha a barra lateral.
toggle Alterna o estado da barra lateral.

form

Ação Descrição
clear Limpa quaisquer valores nas entradas do formulário.
submit Envia o formulário.

Alvos especiais

A seguir, estão listados os alvos fornecidos pelo sistema AMP que possuem requisitos especiais:

Alvo: AMP

O alvo AMP é fornecido pelo runtime do AMP e implementa ações top-level que se aplicam a todo o documento.

Ação Descrição
setState({foo: 'bar'})1

Requer amp-bind.

Funde um literal de objeto para o estado bindable.

1Quando usado com múltiplas ações, ações subsequentes irão aguardar a conclusão de setState() antes da chamada. Apenas um único setState() é permitido por evento.