AMP

Działania i zdarzenia

Dokumentacja ta przedstawia działania i zdarzenia dotyczące witryn internetowych, relacji i reklam AMP. Artykuł Działania i zdarzenia w poczcie elektronicznej AMP opisuje format poczty elektronicznej 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 Wymagane? 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
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

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.

amp-video, amp-youtube

Zdarzenie Opis Dane
firstPlay (niskiego zaufania) Uruchamiane przy pierwszym odtworzeniu filmu przez użytkownika. W przypadku filmów z autoodtwarzaniem jest ono uruchamiane w momencie, gdy użytkownik wchodzi w interakcję z filmem. Jest to zdarzenie niskiego zaufania, czyli nie może wyzwolić większości działań; można uruchamiać tylko działania niskiego zaufania, takie jak amp-animation.
timeUpdate (niskiego zaufania) Uruchamiane po zmianie pozycji odtwarzania filmu. Częstotliwość zdarzenia jest kontrolowana przez AMP i jest aktualnie ustawiana na 1-sekundowe odstępy czasu. Jest to zdarzenie niskiego zaufania, czyli nie może wyzwolić większości działań; można uruchamiać tylko działania niskiego zaufania, takie jak amp-animation. {time, percent}time wskazuje bieżący czas w sekundach, percent jest liczbą z zakresu od 0 do 1 i wskazuje aktualną pozycję jako procent czasu całkowitego.

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.
scrollTo(duration=INTEGER, position=STRING) Przewija element do widoku z płynną animacją.
Parametr duration jest opcjonalny. Określa długość animacji w milisekundach. Jeśli nie jest określony, używana jest wartość względna różnicy przewijania, równa 500 milisekundom lub mniejsza.
Atrybut position jest opcjonalny. Jeden z następujących: top, center lub bottom. (domyślnie top)). Określa pozycję elementu po przewinięciu względem okienka ekranu.
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-audio

Działanie Opis
play Odtwarza dźwięk. Jest pusta, jeśli element <amp-audio> jest elementem potomnym elementu <amp-story>.
pause Wstrzymuje dźwięk. Jest pusta, jeśli element <amp-audio> jest elementem potomnym elementu <amp-story>.

amp-bodymovin-animation

Działanie Opis
play Odtwarza animację.
pause Wstrzymuje animację.
stop Zatrzymuje animację.
seekTo(time=INTEGER) Ustawia currentTime animacji na określoną wartość i wstrzymuje animację.
seekTo(percent=[0,1]) Używa podanej wartości procentowej do określenia currentTime animacji jako podanej wartości i wstrzymuje animację

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

amp-carousel[type="slides"]

Działanie Opis
goToSlide(index=INTEGER) Przesuwa karuzelę do określonego wskaźnika slajdu.
toggleAutoplay(toggleOn=true|false) Przełącza status autoodtwarzania karuzeli. toggleOn jest opcjonalny.

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.
Działanie Opis
open Otwiera lightbox-gallery. Może być wyzwalane przez dotknięcie innego elementu, jeśli określisz identyfikator obrazu: `on="tap:amp-lightbox-gallery.open(id='image-id')"`.

amp-list

Działanie Opis
refresh Odświeża dane z src i ponownie renderuje listę.

amp-live-list

Działanie Opis
update (default) Aktualizuje elementy modelu DOM, aby wyświetlić zaktualizowaną zawartość.

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.

amp-state

Działanie Opis
refresh Ponownie pobiera dane w atrybucie „src”, ignorując jednocześnie pamięć podręczną przeglądarki.

amp-user-notification

Działanie Opis
dismiss (default) Ukrywa element powiadomienia użytkownika, do którego odnosi się odwołanie.

Elementy wideo

Poniższe działania są obsługiwane w następujących elementach wideo AMP: amp-video, amp-youtube, amp-3q-player, amp-brid-player, amp-dailymotion, amp-delight-player, amp-ima-video.

Działanie Opis
play Odtwarza wideo.
pause Wstrzymuje wideo.
mute Wycisza wideo.
unmute Cofa wyciszenie wideo.
fullscreencenter Przenosi wideo na pełny ekran.

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
navigateTo(url=STRING, target=STRING, opener=BOOLEAN)

Kieruje bieżące okno do podanego adresu URL, do opcjonalnie podanego celu (aktualnie obsługiwane są tylko _top oraz _blank ). Opcjonalny parametr opener można określić podczas używania celu _blank, aby umożliwić nowo otwartej stronie dostęp do window.opener. Obsługuje standardowe podstawienia adresów URL.

Zastrzeżenie: w miarę możliwości zalecane jest używanie zwykłych linków <a>, ponieważ element AMP.navigateTo nie jest rozpoznawany przez internetowe roboty indeksujące.

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

Próbuje zamknąć okno, jeśli jest to dozwolone, w przeciwnym razie nawiguje podobnie jak działanie navigateTo. Przydatne w przypadkach, gdy przycisk Wstecz może wymagać zamknięcia okna, jeśli zostało ono otwarte w nowym oknie z poprzedniej strony lub nawigacji, jeśli nie zostało ono otwarte.

Zastrzeżenie: w miarę możliwości zalecane jest używanie zwykłych linków <a>, ponieważ element AMP.navigateTo nie jest rozpoznawany przez internetowe roboty indeksujące.

goBack Przechodzi wstecz w historii.
print Otwiera okno dialogowe drukowania, aby wydrukować bieżącą stronę.
scrollTo(id=STRING, duration=INTEGER, position=STRING) Przewija do podanego identyfikatora elementu na bieżącej stronie.
optoutOfCid Wyłącza opcję generowania identyfikatora klienta dla wszystkich zakresów.
setState({foo: 'bar'})1

Wymaga składnika amp-bind.

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

pushState({foo: 'bar'})1

Wymaga składnika amp-bind.

Scala literał obiektu w stan umożliwiający wiązanie i przesuwa nowy wpis do stosu historii przeglądarki. Przetworzenie wpisu przywróci poprzednie wartości zmiennych (w tym przykładzie foo).

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

Cel: amp-access

Cel amp-access jest dostarczany przez składnik amp-access.

Cel amp-access jest specjalny z następujących powodów:

  1. Nie można nadać temu celowi dowolnego identyfikatora. Celem jest zawsze amp-access.
  2. Działania amp-access są dynamiczne w zależności od struktury konfiguracji składnika AMP Access.

Zobacz szczegóły dotyczące stosowania celu amp-access.