AMP
PT
English Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Русский Türkçe 中文 Polski Tiếng việt

Ações e eventos

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

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.

O 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 abre. 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
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

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.

amp-video, amp-youtube

Evento Descrição Dados
firstPlay (baixa confiança) Disparado na primeira vez que o vídeo for executado pelo usuário. Em videos autoplay, este evento é disparado assim que o usuário interage com o vídeo. Este evento é de baixa confiança, o que significa que ele não pode desencadear a maioria das ações; apenas ações de baixa confiança, como ações amp-animation podem ser executadas.
timeUpdate (baixa confiança) Disparado quando a posição de reprodução de um vídeo é alterada. A frequência do evento é controlada pelo AMP e está definida atualmente em intervalos de 1 segundo. Este evento é de baixa confiança, o que significa que ele não pode desencadear a maioria das ações; apenas ações de baixa confiança, como ações amp-animation podem ser executadas. {time, percent}time time indica o tempo atual em segundos, percent é um número entre 0 e 1 e indica a posição atual como uma porcentagem do tempo total.

form

Evento Descrição Dados
submit Disparado quando o formulário é enviado.
submit-success Fired when the form submission response is success. 
// 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.

Ações específicas por elemento

* (todos os elementos)

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.
scrollTo(duration=INTEGER, position=STRING) Rola um elemento para a visualização com uma animação suave.

duration é opcional. Especifica a duração da animação em milissegundos. Se não for especificado, um valor relativo à diferença de rolagem menor ou igual a 500 milissegundos é usado.

position é opcional. Um dentre top, center ou bottom (padrão top). Especifica a posição do elemento em relação à janela de visualização após a rolagem.

Como prática recomendada de acessibilidade, junte isto com uma chamada para focus() para focar no elemento que está sendo rolado.
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-audio

Ação Descrição
play Executa o áudio. É um no-op se o elemento <amp-audio> for um descendente de <amp-story>.
pause Pausa o áudio. É um no-op se o elemento <amp-audio> for um descendente de <amp-story>.

amp-bodymovin-animation

Ação Descrição
play Executa a animação.
pause Pausa a animação.
stop Interrompe a animação.
seekTo(time=INTEGER) Define o currentTime da animação para o valor especificado e pausa a animação.
seekTo(percent=[0,1]) Usa o valor percentual fornecido para determinar o currentTime da animação para o valor especificado e pausa a animação.

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='section-id')".
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='section-id')".

amp-carousel[type="slides"]

Ação Descrição
goToSlide(index=INTEGER) Avança o carrossel para um índice de slide especificado.
toggleAutoplay(toggleOn=true|false) Alterna o status de reprodução automática do carrossel. toggleOn é opcional.

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.
Ação Descrição
open Abre a galeria lightbox. Pode ser disparado tocando em outro elemento, se você especificar o ID da imagem: `on="tap:amp-lightbox-gallery.open(id='image-id')"`.

amp-list

Ação Descrição
refresh Atualiza os dados do src e renderiza novamente a lista.

amp-live-list

Ação Descrição
update (default) Atualiza os itens do DOM para mostrar o conteúdo atualizado.

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.

amp-state

Ação Descrição
refresh Atualiza os dados vinculados ao atributo `src` enquanto ignora o cache do navegador.

amp-user-notification

Ação Descrição
dismiss (default) Oculta o elemento de notificação do usuário referenciado.

Elementos de vídeo

As ações abaixo são suportadas nos seguintes elementos de vídeo AMP: amp-video, amp-youtube, amp-3q-player, amp-brid-player, amp-dailymotion, amp-delight-player, amp-ima-video.

Ação Descrição
play Executa o vídeo.
pause Pausa o vídeo.
mute Silencia o vídeo.
unmute Ativa o som do vídeo.
fullscreencenter Coloca o vídeo em tela cheia.

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 AMP e implementa ações top-level que se aplicam a todo o documento.

Ação Descrição
navigateTo(url=STRING, target=STRING, opener=BOOLEAN)

Navega a janela atual para a URL fornecida, para o alvo opcional especificado, se fornecido (atualmente, suporta apenas _top r _blank ). O parâmetro opcional opener parameter can be specified when using a target of _blank para permitir que a página recém-aberta acesse window.opener. Suporta substituições de URL padrão.

Advertência: o uso de links <a> normais é recomendado sempre que possível, já que AMP.navigateTo não é reconhecido por rastreadores da web.
closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN)

Tenta fechar a janela se permitido, caso contrário, navega de forma semelhante à ação navigateTo. Útil para casos de uso em que um botão "Voltar" poderá precisar fechar a janela se ela foi aberta numa nova janela da página anterior ou navegar, se não foi aberta.

Advertência: o uso de links <a> normais é recomendado sempre que possível, já que AMP.closeOrNavigateTo não é reconhecido por rastreadores da web.
goBack Navega para trás no histórico.
print Abre o Diálogo de Impressão para imprimir a página atual.
scrollTo(id=STRING, duration=INTEGER, position=STRING) Rola para o ID do elemento fornecido na página atual.
optoutOfCid Desativa a geração de ID do cliente para todos os escopos.
setState({foo: 'bar'})1

Requer amp-bind.

Funde um literal de objeto para o estado bindable.
pushState({foo: 'bar'})1

Requer amp-bind.

Funde um literal de objeto para o estado bindable insere um novo dado na pilha do histórico do navegador. A extração do dado irá restaurar valores anteriores das variáveis (neste exemplo, foo).

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

Alvo: amp-access

O alvo amp-access é fornecido pelo componente amp-access component.

O alvo amp-access é especial pelas razões a seguir:

  1. Você não pode fornecer um ID arbitrário para este alvo. O alvo é sempre amp-access.
  2. As ações para amp-access são dinâmicas dependendo da estrutura da Configuração de Acesso AMP.

Veja detalhes sobre o uso do alvo amp-access target.