Działania i zdarzenia
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ą AMP ma koncepcję działania domyślnego, które mogą implementować elementy. W razie pominięcia |
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:
|
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 |
input[type="radio"],input[type="checkbox"]
| event.checked | ||
select | event.min | ||
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. |
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. |
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. |
submit-error | Uruchamiane, gdy odpowiedź na przesłanie formularza to „error”. | // Response JSON. |
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. |
amp-lightbox-gallery
| 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 Zastrzeżenie: w miarę możliwości zalecane jest używanie zwykłych linków |
closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN) | Próbuje zamknąć okno, jeśli jest to dozwolone, w przeciwnym razie nawiguje podobnie jak działanie Zastrzeżenie: w miarę możliwości zalecane jest używanie zwykłych linków |
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 |
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:
- Nie można nadać temu celowi dowolnego identyfikatora. Celem jest zawsze
amp-access. - Działania
amp-accesssą dynamiczne w zależności od struktury konfiguracji składnika AMP Access.
Zobacz szczegóły dotyczące stosowania celu amp-access.