AMP

Działania i zdarzenia w poczcie elektronicznej AMP

Important: this documentation is not applicable to your currently selected format stories!

Dokumentacja ta przedstawia działania i zdarzenia dotyczące formatu wiadomości e-mail AMP. Przeczytaj artykuł Działania i zdarzenia dotyczący witryn internetowych, relacji i reklam AMP.

Atrybut on służy do instalowania programów obsługi zdarzeń w elementach. Obsługiwane zdarzenia zależą od danego elementu.

Wartość do składni jest prostym, zależnym od domeny językiem formularza:

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

Opisy poszczególnych części składni znajdują się w poniższej tabeli.

Składnia Wymagany? Opis
eventName tak Jest to nazwa zdarzenia, którą eksponuje dany element.
targetId tak Jest to identyfikator modelu DOM elementu lub predefiniowany cel specjalny, ktorego ma dotyczyc dzialanie wykonywane w odpowiedzi na zdarzenie. W nastepujacym przykladzie, targetId to identyfikator modelu DOM docelowego elementu skladnika amp-lightbox, photo-slides.
<amp-lightbox id="photo-slides"></amp-lightbox>
<button on="tap:photo-slides">Show Images</button>
methodName nie Do elementów z działaniami domyślnymi.

Jest to metoda, którą ujawnia element docelowy (określony za pomocą targetId), a ktora ma zostać wykonana po wyzwoleniu zdarzenia.

AMP ma koncepcję działania domyślnego, które mogą implementować elementy. W razie pominięcia methodName AMP wykona ową metodę domyślną.

arg=value nie Niektóre działania, jeśli są udokumentowane, mogą przyjmować argumenty. Argumenty są definiowane między nawiasami w notacji key=value. Przyjmowane są wartości:
  • proste ciągi znaków bez cudzysłowów: simple-value
  • ciągi znaków w cudzysłowach: "string value" lub 'string value'
  • wartości logiczne: true albo false
  • liczby: 11 lub 1.1
  • odniesienie o składni z kropką do danych dotyczących zdarzeń: event.someDataVariableName

Obsługa wielu zdarzeń

Możesz nasłuchiwać wielu zdarzeń w jednym elemencie, oddzielając zdarzenia średnikiem ;.

Przykład: on="submit-success:lightbox1;submit-error:lightbox2"

Wiele działań w przypadku jednego zdarzenia

Możesz wykonać wiele kolejnych działań dotyczących tego samego zdarzenia, oddzielając je przecinkiem „,”.

Przykład: on="tap:target1.actionA,target2.actionB"

Wydarzenia i działania definiowane globalnie

AMP definiuje globalnie zdarzenie tap, którego można nasłuchiwać w każdym elemencie HTML (włącznie z elementami AMP).

AMP definiuje globalnie również działania hide, show i toggleVisibility, które można wyzwalać w dowolnym elemencie HTML.

Element może być pokazany tylko wtedy, gdy wcześniej został ukryty za pomocą działania hide lub toggleVisibility, lub przy użyciu atrybutu hidden. Działanie show nie obsługuje elementów ukrytych przez CSS display:none lub AMP layout=nodisplay.

Na przykład w AMP możliwe jest:

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

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

Zdarzenia zależne od elementu

* - wszystkie elementy

Zdarzenie Opis
tap Uruchamiane po kliknięciu/dotknięciu elementu.

Elementy wejściowe

Zdarzenie Opis Elementy Dane
change Uruchamiane, gdy wartość elementu zostanie zmieniona i zatwierdzona.

Właściwości danych odzwierciedlają te w elementach HTMLInputElement i 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 Uruchamiane, gdy wartość elementu zostanie zmieniona. Jest podobne do standardowego zdarzenia change, ale jest uruchamiane dopiero po upływie 300 ms od momentu, gdy wartość wejściowa przestanie się zmieniać. Elementy uruchamiające zdarzenie input. Te same, co dane zdarzenia change.
input-throttled Uruchamiane, gdy wartość elementu zostanie zmieniona. Jest podobne do standardowego zdarzenia change, ale jego uruchomienie jest ograniczane do co najwyżej jednego razu na 100 ms podczas zmiany wartości wejściowej. Elementy uruchamiające zdarzenie input. Te same, co dane zdarzenia change.

amp-accordion > section

Zdarzenie Opis Dane
expand Uruchamiane, gdy sekcja accordion zostanie rozwinięta. Brak.
collapse Uruchamiane, gdy sekcja accordion zostanie zwinięta. Brak.

amp-carousel[type="slides"]

Zdarzenie Opis Dane
slideChange Uruchamiane, gdy zmienia się bieżący slajd karuzeli.
// Slide number.
event.index

amp-lightbox

Zdarzenie Opis Dane
lightboxOpen Uruchamiane, gdy lightbox jest w pełni widoczny. Brak.
lightboxClose Uruchamiane, gdy lightbox jest w pełni zamknięty. Brak.

amp-list

Zdarzenie Opis Dane
fetch-error(niskiego zaufania) Uruchamiane, gdy nie uda się pobrać danych. Brak.

amp-selector

Zdarzenie Opis Dane
select Uruchamiane, gdy opcja zostanie zaznaczona lub wyczyszczona.
// Target element's "option" attribute value.
event.targetOption
// Array of "option" attribute values of all selected elements.
event.selectedOptions

amp-sidebar

Zdarzenie Opis Dane
sidebarOpen Uruchamiane, gdy pasek boczny jest całkowicie otwarty po zakończeniu przejścia. Brak.
sidebarClose Uruchamiane, gdy pasek boczny jest całkowicie zamknięty po zakończeniu przejścia. Brak.

amp-state

Zdarzenie Opis Dane
fetch-error(niskiego zaufania) Uruchamiane, gdy nie uda się pobrać danych. Brak.

form

Zdarzenie Opis Dane
submit Uruchamiane po przesłaniu formularza.
submit-success Uruchamiane, gdy odpowiedź na przesłanie formularza to „success”.
// Response JSON.
event.response
submit-error Uruchamiane, gdy odpowiedź na przesłanie formularza to „error”.
// Response JSON.
event.response
valid Uruchamiane, gdy formularz jest prawidłowy.
invalid Uruchamiane, gdy formularz jest nieprawidłowy.

Działania zależne od elementu

* - wszystkie elementy

Działanie Opis
hide Ukrywa element docelowy.
show Pokazuje element docelowy. Jeśli w wyniku tego element autofocus stanie się widoczny, zyska fokus.
toggleVisibility Przełącza widoczność elementu docelowego. Jeśli w wyniku tego element autofocus stanie się widoczny, zyska fokus.
toggleClass(class=STRING, force=BOOLEAN) Przełącza klasę elementu docelowego. Instrukcja force jest opcjonalna i jeśli została zdefiniowana, zapewnia, że klasa zostanie dodana, ale nie zostanie usunięta, jeśli zostanie ustawiona na true, a tylko usunięta, ale nie dodana, jeśli zostanie ustawiona na false.
focus Sprawia, że element docelowy zyskuje fokus. Aby stracił fokus, ustaw focus na inny element (zwykle element nadrzędny). Ze względów dostępności zdecydowanie odradzamy usuwanie fokusu poprzez ustawienie go na body/documentElement.

amp-accordion

Działanie Opis
toggle(section=STRING) Przełącza stany expanded i collapsed sekcji elementu amp-accordion. W razie wywołania bez argumentów przełącza wszystkie sekcje akordeonu. Aby wyzwolić w żądanej sekcji, należy podać identyfikator sekcji: on="tap:myAccordion.toggle(section=id')"
expand(section=STRING) Rozwija sekcje akordeonu. Jeśli sekcja jest już rozwinięta, pozostaje rozwinięta. W razie wywołania bez argumentów rozwija wszystkie sekcje akordeonu. Aby wyzwolić w żądanej sekcji, należy podać identyfikator sekcji: on="tap:myAccordion.expand(section='section-id')".
collapse(section=STRING) Zwija sekcje akordeonu. Jeśli jakaś sekcja jest już zwinięta, pozostaje zwinięta. Gdy jest wywoływany bez argumentów, zwija wszystkie sekcje akordeonu. Aby wyzwolić w żądanej sekcji, należy podać identyfikator sekcji: on="tap:myAccordion.collapse(section=

amp-carousel[type="slides"]

Działanie Opis
goToSlide(index=INTEGER) Przesuwa karuzelę do określonego wskaźnika slajdu.

amp-image-lightbox

Działanie Opis
open (default) Otwiera element lightbox obrazu z obrazem źródłowym, który wyzwolił działanie.

amp-lightbox

Działanie Opis
open (default) Otwiera lightbox.
close Zamyka lightbox.

amp-list

Zdarzenie Opis Dane
changeToLayoutContainer Aktualizuje układ elementu amp-list do layout="CONTAINTER", aby umożliwić dynamiczną zmianę rozmiarów.
fetch-error(niskiego zaufania) Uruchamiane, gdy nie uda się pobrać danych. Brak.

amp-selector

Działanie Opis
clear Usuwa wszystkie wybory z określonego elementu amp-selector.
selectUp(delta=INTEGER) Przesuwa wybór w górę o wartość „delta”. Domyślna wartość „delta” jest ustawiona na -1. Jeśli nie wybrano żadnych opcji, wybrany stan staje się wartością ostatniej opcji.
selectDown(delta=INTEGER) Przesuwa wybór w dół o wartość „delta”. Domyślna wartość „delta” jest ustawiona na 1. Jeśli nie wybrano żadnych opcji, wybrany stan staje się wartością ostatniej opcji.
toggle(index=INTEGER, value=BOOLEAN) Przełącza stosowanie atrybutu „selected”. Jeśli atrybut select jest nieobecny, działanie dodaje go. Jeśli atrybut select jest obecny, działanie usuwa go. Można wymusić i zachować dodanie lub usunięcie poprzez włączenie wartości boolean do argumentu „value”. Wartość „true” wymusi dodanie atrybutu „selected” i nie usunie go, jeśli jest już obecny. Wartość „false” poskutkuje usunięciem atrybutu, ale nie doda go, jeśli go nie ma.

amp-sidebar

Działanie Opis
open (default) Otwiera pasek boczny.
close Zamyka pasek boczny.
toggle Przełącza stan paska bocznego.

form

Działanie Opis
clear Czyści wszelkie wartości w polach wprowadzania formularza.
submit Przesyła formularz.

Cele specjalne

Poniżej przedstawione są cele systemu AMP, które mają specjalne wymagania:

Cel: AMP

Cel AMP jest dostarczany przez środowisko uruchomieniowe AMP i implementuje działania najwyższego poziomu, stosowane do całego dokumentu.

Działanie Opis
setState({foo: 'bar'})1

Wymaga składnika amp-bind.

Scala literał obiektu w stan umożliwiający wiązanie.

1Jeśli używane jest z wieloma działaniami, kolejne działania będą przed wywołaniem czekać na wykonanie działań setState(). Na jedno zdarzenie dozwolone jest tylko jedno działanie setState().