AMP

Actions et événements

Cette documentation couvre les actions et événements pour les sites Web, les stories et les annonces AMP. Lisez la section Actions et événements dans les e-mails AMP pour le format d'e-mail AMP.

L'attribut on est utilisé pour installer des gestionnaires d'événements sur des éléments. Les événements pris en charge dépendent de l'élément.

La valeur de la syntaxe est un langage simple spécifique au domaine du formulaire:

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

Consultez le tableau ci-dessous pour une description détaillée de la syntaxe.

Syntaxe Requis? Description
eventName Oui C'est le nom de l'événement qu'un élément expose.
targetId Oui C'est l'identifiant du DOM de l'élément ou une cible spéciale prédéfinie sur laquelle vous souhaitez exécuter une action en réponse à l'événement. Dans l'exemple suivant, targetId représente l'identifiant du DOM de la cible amp-lightbox, photo-slides.
<amp-lightbox id="photo-slides"></amp-lightbox>
<button on="tap:photo-slides">Show Images</button>
methodName Non Pour les éléments qui ont des actions par défaut.

C'est la méthode que l'élément cible (référencé par targetId) expose et que vous souhaitez exécuter lorsque l'événement est déclenché.

AMP possède un concept d'action par défaut que les éléments peuvent implémenter. Ainsi, en omettant le methodName, AMP exécutera cette méthode par défaut.

arg=value Non Certaines actions, si elles sont documentées, peuvent accepter des arguments. Les arguments sont définis entre parenthèses dans la notation key=value . Les valeurs acceptées sont:
  • chaînes simples sans guillemets: simple-value
  • chaînes entre guillemets: "string value" ou 'string value'
  • valeurs booléennes: true ou false
  • nombres: 11 ou 1.1
  • référence de syntaxe de point aux données d'événement: event.someDataVariableName

Gérer plusieurs événements

Vous pouvez écouter plusieurs événements sur un élément en séparant les événements par un point-virgule ;.

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

Plusieurs actions pour un événement

Vous pouvez exécuter plusieurs actions en séquence pour le même événement en séparant les actions par une virgule «,».

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

Événements et actions définis de manière globale

AMP définit globalement un événement tap que vous pouvez écouter sur n'importe quel élément HTML (y compris les éléments AMP).

AMP définit également globalement les actions hide , show et toggleVisibility que vous pouvez déclencher sur n'importe quel élément HTML.

Un élément ne peut être affiché que s'il était d'abord masqué par une action hide ou toggleVisibility, ou à l'aide de l'attribut hidden. L'action show ne prend pas en charge les éléments masqués par l'attribut display:none de CSS ou l'attribut layout=nodisplay d'AMP.

L'exemple suivant est possible dans AMP:

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

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

Événements spécifiques aux éléments

* - tous les éléments

Événement Description
tap Se déclenche lorsque vous cliquez ou appuyez sur l'élément.

Éléments d'entrée

Événement Description Éléments Données
change Se déclenche lorsque la valeur de l'élément est modifié et envoyée.

Les propriétés des données les reflètent dans HTMLInputElement et 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 Se déclenche lorsque la valeur de l'élément est modifiée. Il est similaire à l'événement change standard, mais il ne se déclenche que lorsque 300ms se sont écoulés après la fin de la modification de la valeur de l'entrée. Éléments qui déclenchent l'événement input. Identique aux données de l'événement change.
input-throttled Se déclenche lorsque la valeur de l'élément est modifiée. Il est similaire à l'événement change standard, mais il est limité à se déclencher au plus une fois toutes les 100ms pendant la modification de la valeur de l'entrée. Éléments qui déclenchent l'événement input. Identique aux données de l'événement change.

amp-accordion > section

Événement Description Données
expand Se déclenche lorsqu'une section d'accordéon se développe. Aucune.
collapse Se déclenche lorsqu'une section d'accordéon se réduit. Aucune.

amp-carousel[type="slides"]

Événement Description Données
slideChange Se déclenche lorsque la diapositive actuelle du carrousel change.
// Slide number.
event.index

amp-lightbox

Événement Description Données
lightboxOpen Se déclenche lorsque la lightbox est entièrement visible. Aucune
lightboxClose Se déclenche lorsque la lightbox est complètement fermée. Aucune

amp-list

Événement Description Données
changeToLayoutContainer Met à jour la disposition de amp-list vers layout="CONTAINTER" pour permettre le redimensionnement dynamique.
fetch-error (confiance basse) Se déclenche lorsque la récupération des données échoue. Aucune

amp-selector

Événement Description Données
select Se déclenche lorsqu'une option est sélectionnée ou désélectionnée.
// Target element's "option" attribute value.
event.targetOption
// Array of "option" attribute values of all selected elements.
event.selectedOptions

amp-sidebar

Événement Description Données
sidebarOpen Se déclenche lorsque la barre latérale est complètement ouverte après la fin de la transition. Aucune
sidebarClose Se déclenche lorsque la barre latérale est complètement fermée après la fin de la transition. Aucune

amp-state

Événement Description Données
fetch-error (confiance basse) Se déclenche lorsque la récupération des données échoue. Aucune

amp-video, amp-youtube

Événement Description Données
firstPlay (faible confiance) Se déclenche quand l'utilisateur lit la vidéo pour la première fois. Sur les vidéos en lecture automatique, il se déclenche dès que l'utilisateur interagit avec la vidéo. Cet événement a un niveau de confiance bas, ce qui signifie qu'il ne peut pas déclencher la plupart des actions; seules les actions ayant un niveau de confiance bas telles que les actions amp-animation peuvent être exécutées.
timeUpdate (faible confiance) Se déclenche lorsque la position de lecture d'une vidéo a changé. La fréquence de l'événement est contrôlée par AMP et est actuellement réglée à 1 seconde d'intervalle. Cet événement a un niveau de confiance bas, ce qui signifie qu'il ne peut pas déclencher la plupart des actions; seules les actions ayant un niveau de confiance bas telles que les actions amp-animation peuvent être exécutées. {time, percent} time indique l'heure actuelle en secondes, percent est un nombre compris entre 0 et 1 et indique la position actuelle en pourcentage du temps total.

form

Événement Description Données
submit Se déclenche lorsque le formulaire est soumis.
submit-success Se déclenche lorsque le formulaire affiche une réponse d'envoi réussie.
// Response JSON.
event.response
submit-error Se déclenche lorsque le formulaire marque une erreur d'envoi.
// Response JSON.
event.response
valid Se déclenche lorsque le formulaire est valide.
invalid Se déclenche lorsque le formulaire n'est pas valide.

Actions spécifiques aux éléments

* (tous les éléments)

Action Description
hide Masque l'élément cible.
show Affiche l'élément cible. Si un élément élément de autofocus devient visible en conséquence, il obtient la mise au point.
toggleVisibility Active / désactive la visibilité de l'élément cible. Si un élément de autofocus devient visible en conséquence, il obtient la mise au point.
toggleClass(class=STRING, force=BOOLEAN) Change la classe de l'élément cible. L'élément force est facultatif, et si défini, il garantit que la classe sera uniquement ajoutée et pas supprimée si elle est définie sur true, et inversement si elle est définie sur false.
scrollTo(duration=INTEGER, position=STRING) Fait défiler un élément dans la vue avec une animation fluide.
duration est facultative. Spécifie la durée de l'animation en millisecondes. S'il n'est pas spécifié, un montant relatif à la différence de défilement inférieur ou égal à 500 millisecondes est utilisé.
position est facultative. L'un de top , center ou bottom ( top par défaut). Spécifie la position de l'élément par rapport à la fenêtre après le défilement.
Une bonne pratique en matière d'accessibilité consiste à associer cela à un appel à focus() pour se focaliser sur l'élément en cours de défilement
focus Rend l'élément cible gagnant le focus. Pour perdre le focus, focus sur un autre élément (généralement l'élément parent). Nous déconseillons fortement de perdre le focus en nous concentrant sur body / documentElement pour des raisons d'accessibilité.

amp-audio

Action Description
play Lit l'audio. Prend la valeur no-op si l'élément <amp-audio> est un élément enfant de <amp-story>.
pause Met l'audio en pause. Prend la valeur no-op si l'élément <amp-audio> est un élément enfant de <amp-story>.

amp-bodymovin-animation

Action Description
play Lit l'animation.
pause Met l'animation en pause.
stop Arrête l'animation.
seekTo(time=INTEGER) Définit la durée actuelle de l'animation sur la valeur spécifiée et interrompt l'animation.
seekTo(percent=[0,1]) Utilise la valeur de pourcentage donnée pour déterminer le la durée actuelle de l'animation sur la valeur spécifiée et met l'animation en pause.

amp-accordion

Action Description
toggle(section=STRING) Change les états expanded et collapsed des sections amp-accordion. Lorsque l'action est appelée sans argument, elle fait basculer toutes les sections de l'accordéon. Déclenchez sur une section spécifique en fournissant l'ID de section: on="tap:myAccordion.toggle(section='section-id')".
expand(section=STRING) Développe les sections de l'accordéon. Si une section est déjà développée, elle reste développée. Lorsque l'action est appelée sans argument, elle développe toutes les sections de l'accordéon. Déclenchez sur une section spécifique en fournissant l'ID de section: on="tap:myAccordion.expand(section='section-id')".
collapse(section=STRING) Réduit les sections de l'accordéon. Si une section est déjà réduite, elle reste réduite. Lorsque l'action est appelée sans argument, elle réduit toutes les sections de l'accordéon. Déclenchez une section spécifique en fournissant l'ID de section: on="tap:myAccordion.collapse(section='section-id')".

amp-carousel[type="slides"]

Action Description
goToSlide(index=INTEGER) Fait avancer le carrousel jusqu'à un index de diapositive spécifié.
toggleAutoplay(toggleOn=true|false) Change l'état de lecture automatique du carrousel. L'élément toggleOn est facultatif.

amp-image-lightbox

Action Description
open (default) Ouvre la lightbox d'image avec l'image source étant celle qui a déclenché l'action.

amp-lightbox

Action Description
open (default) Ouvre la lightbox.
close Ferme la lightbox.

amp-lightbox-galerie

Action Description
open Ouvre la galerie lightbox. Peut être déclenché en appuyant sur un autre élément, si vous spécifiez l'identifiant de l'image: `on ="tap: amp-lightbox-gallery.open (id = 'image-id')"`.

amp-list

Action Description
refresh Actualise les données de l'attribut src et restitue la liste.

amp-live-list

Action Description
update (default) Met à jour les éléments DOM pour afficher le contenu mis à jour.

amp-selector

Action Description
clear Efface toutes les sélections d'un amp-selector défini.
selectUp(delta=INTEGER) Déplace la sélection vers le haut, à la valeur de `delta`. La valeur `delta` par défaut est définie sur -1. Si aucune option n'est sélectionnée, l'état sélectionné deviendra la valeur de la dernière option.
selectDown(delta=INTEGER) Déplace la sélection vers le bas, à la valeur de `delta`. La valeur `delta` par défaut est définie sur 1. Si aucune option n'est sélectionnée, l'état sélectionné deviendra la valeur de la première option.
toggle(index=INTEGER, value=BOOLEAN) Change l'application de `selected`. Si l'attribut de sélection est absent, cette action l'ajoute. Si l'attribut de sélection est présent, cette action le supprime. Vous pouvez forcer la conservation d'un ajout ou d'une suppression en incluant une valeur booléenne dans l'argument `value`. Une valeur `true` forcera l'ajout de l'attribut `selected` et ne le supprimera pas s'il est déjà présent. Une valeur de `false` supprimera l'attribut, mais ne l'ajoutera pas s'il est absent.

amp-sidebar

Action Description
open (default) Ouvre la barre latérale.
close Ferme la barre latérale.
toggle Change l'état de la barre latérale.

amp-state

Action Description
refresh Récupère les données de l'attribut `src` tout en ignorant le cache du navigateur.

amp-user-notification

Action Description
dismiss (default) Masque l'élément de notification utilisateur référencé.

Éléments vidéo

Les actions ci-dessous sont prises en charge dans les éléments vidéo AMP suivants: amp-video , amp-youtube , amp-3q-player , amp-brid-player , amp-dailymotion , amp-delight-player , amp-ima-video .

Action Description
play Lit la vidéo.
pause Met la vidéo en pause.
mute Coupe le son de la vidéo.
unmute Active le son de la vidéo.
fullscreencenter Met la vidéo en plein écran.

form

Action Description
clear Efface toutes les valeurs dans les entrées du formulaire.
submit Envoie le formulaire.

Cibles spéciales

Les cibles suivantes sont fournies par le système AMP et ont des exigences particulières:

Cible: AMP

La cible AMP est fournie par le runtime AMP et implémente des actions de niveau supérieur qui s'appliquent à l'ensemble du document.

Action Description
navigateTo(url=STRING, target=STRING, opener=BOOLEAN)

Dirige la fenêtre actuelle vers une URL donnée si elle est spécifiée (prend actuellement uniquement en charge _top et _blank ). Le paramètre facultatif opener peut être spécifié si vous utilisez une cible de _blank pour permettre à la page nouvellement ouverte d'accéder à window.opener. Prend en charge substitutions d'URL standard.

Mise en garde: l'utlisation de liens normaux <a> est recommandée dans la mesure du possible car AMP.navigateTo n'est pas reconnu par les robots d'exploration.

closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN)

Tente de fermer la fenêtre si cela est autorisé, sinon l'action dirige de la même manière que l'action navigateTo. Utile pour les cas d'utilisation où un bouton « Retour » peut avoir besoin de fermer la fenêtre si elle a été ouverte dans une nouvelle fenêtre de la page précédente ou de diriger vers elle si elle n'a pas été ouverte.

Mise en garde: l'utlisation de liens normaux <a> est recommandée dans la mesure du possible car AMP.closeOrNavigateTo n'est pas reconnu par les robots d'exploration.

goBack Permet de rentrer en arrière dans l'historique.
print Ouvre la boîte de dialogue Imprimer pour imprimer la page actuelle.
scrollTo (id = STRING, durée = INTEGER, position = STRING) Fait défiler jusqu'à l'ID d'élément fourni sur la page actuelle.
optoutOfCid Désactive la génération d'ID client à tous les niveaux.
setState({foo: 'bar'})1

Nécessite amp-bind.

Fusionne un littéral d'objet dans l'état pouvant être lié.

pushState({foo: 'bar'})1

Nécessite amp-bind.

Fusionne un littéral d'objet dans l'état pouvant être lié et pousse une nouvelle entrée dans la pile d'historique du navigateur. Faire sauter l'entrée restaurera les valeurs précédentes des variables (dans cet exemple, foo).

1 Lorsqu'elles sont utilisées avec plusieurs actions, les actions suivantes attendront que setState() ou pushState() se termine avant l'appel. Un seul setState() ou pushState() est autorisé par événement.

Cible: amp-access

La cible amp-access est fournie par le composant amp-access.

La cible amp-access est spéciale pour les raisons suivantes:

  1. Vous ne pouvez pas attribuer un ID arbitraire à cette cible. La cible est toujours amp-access.
  2. Les actions de amp-access sont dynamiques en fonction de la structure de la configuration d'accès AMP.

Voir les détails sur l'utilisation de la cible amp-access.