AMP

Действия и события в AMP-письмах

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

В этой документации описаны действия и события для формата «AMP-письма». Чтобы узнать о действиях и событиях для AMP-сайтов, историй и рекламы, прочтите эту статью.

Атрибут on используется для установки обработчиков событий на элементы. То, какие события поддерживаются, зависит от элемента.

Синтаксис представляет собой простой предметно-ориентированный язык следующего вида:

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

Описание каждой части синтаксиса приведено в таблице ниже.

Синтаксис Обязательно? Описание
eventName да Наименование события, предусмотренного элементом.
targetId да Это DOM-идентификатор элемента или предустановленная специальная цель , над которой вы бы хотели осуществить действие в ответ на событие. В следующем примере targetId является DOM-идентификатором цели amp-lightbox, photo-slides.
<amp-lightbox id="photo-slides"></amp-lightbox>
<button on="tap:photo-slides">Показать изображения</button>
methodName нет Предназначено для элементов с действиями по умолчанию.

Это метод, доступный в целевом элементе (на который указывает targetId) и который вы хотите выполнить при срабатывании события.

В AMP есть концепция «действия по умолчанию»; такое действие могут устанавливать элементы. Поэтому, если methodName опущен, AMP выполнит метод по умолчанию.

arg=value нет Некоторые действия, если это задокументировано, могут принимать аргументы. Аргументы указываются в скобках в нотации ключ=значение. Допустимые значения:
  • простые строки без кавычек: simple-value
  • строки в кавычках: "string value" или 'string value'
  • логические значения: true или false
  • числа: 11 или 1.1
  • ссылка на данные события (синтаксис «через точку»): event.someDataVariableName

Обработка нескольких событий

Чтобы элемент «слушал» несколько событий, разделяйте события точкой с запятой ;.

Пример: on="submit-success:lightbox1;submit-error:lightbox2"

Несколько действий на одно событие

Чтобы в ответ на одно событие последовательно выполнить несколько действий, разделяйте действия запятой ','.

Пример: on="tap:target1.actionA,target2.actionB"

Глобально определенные события и действия

AMP определяет событие tap глобально, что позволяет вам слушать касание на любом HTML-элементе (включая AMP-элементы).

AMP также определяет глобальные действия hide, show и toggleVisibility, которые можно применять к любому элементу HTML.

Тип: примечание

Элемент может быть показан («show») только в том случае, если он ранее был скрыт действием hide или toggleVisibility, или атрибутом hidden. Действие show несовместимо с элементами, скрытыми с помощью CSS: display:none или AMP: layout=nodisplay.

Например, в AMP возможно следующее:

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

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

События конкретных элементов

* — все элементы

Событие Описание
tap Срабатывает только при нажатии/касании элемента.

Элементы input

Событие Описание Элементы Данные
change Происходит при изменении и фиксации элемента.

Свойства данных являются повторением свойств HTMLInputElement и 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 Срабатывает при изменении значения элемента. Похоже на стандартное событие change, но срабатывает только через 300 мс после того, как значение элемента input перестало меняться. Элементы, которые инициируют событие input. Совпадают с данными события change.
input-throttled Срабатывает при изменении значения элемента. Похоже на стандартное событие change, но срабатывает не чаще чем раз в 100 мс до тех пор, пока значение элемента input не прекратит меняться. Элементы, которые инициируют событие input. Совпадают с данными события change.

amp-accordion > section

Событие Описание Данные
expand Срабатывает при развороте раздела accordion. Нет
collapse Срабатывает при свертывании раздела accordion. Нет

amp-carousel[type="slides"]

Событие Описание Данные
slideChange Срабатывает при смене текущего слайда карусели.
// Номер слайда.
event.index

amp-lightbox

Событие Описание Данные
lightboxOpen Срабатывает, когда лайтбокс полностью виден. Нет
lightboxClose Срабатывает, когда лайтбокс полностью закрыт. Нет

amp-list

Событие Описание Данные
fetch-error (низкий уровень доверия) Срабатывает при сбое загрузки данных. Нет

amp-selector

Событие Описание Данные
select Срабатывает при выборе и снятии выбора с одного из вариантов.
// Значение атрибута "option" целевого элемента.
event.targetOption
// Массив значений атрибутов "option" всех выбранных элементов.
event.selectedOptions

amp-sidebar

Событие Описание Данные
sidebarOpen Срабатывает, когда боковая панель полностью открыта (после завершения перехода). Нет
sidebarClose Срабатывает, когда боковая панель полностью закрыта (после завершения перехода). Нет

amp-state

Событие Описание Данные
fetch-error (низкий уровень доверия) Срабатывает при сбое загрузки данных. Нет

form

Событие Описание Данные
submit Срабатывает при отправке формы.
submit-success Срабатывает, когда на отправку формы получен ответ «Успешно».
// JSON ответа.
event.response
submit-error Срабатывает, когда на отправку формы получен ответ «Ошибка».
// JSON ответа.
event.response
valid Срабатывает, когда форма действительна.
invalid Срабатывает, когда форма недействительна.

События конкретных элементов

* — все элементы

Действие Описание
hide Скрывает целевой элемент.
show Показывает целевой элемент. Если в результате становится видимым элемент с атрибутом autofocus, он приобретает фокус.
toggleVisibility Переключает видимость целевого элемента. Если в результате становится видимым элемент с атрибутом autofocus, он приобретает фокус.
toggleClass(class=STRING, force=BOOLEAN) Переключает класс целевого элемента. Атрибут force является необязательным — он позволяет гарантировать, что: класс будет добавлен, но не удален (если задано значение true) или только удален, но не добавлен (если задано значение false).
focus Передает фокус целевому элементу. Чтобы убрать фокус, выполните focus на другом элементе (обычно родительском элементе). Мы настоятельно рекомендуем не убирать фокус путем назначения фокуса элементу body/documentElement во избежание некорректной работы возможностей универсального доступа.

amp-accordion

Действие Описание
toggle(section=STRING) Переключает разделы amp-accordion между состояниями expanded и collapsed. При вызове без аргументов переключает состояние всех разделов accordion. Чтобы применить к определенному разделу, укажите идентификатор раздела on="tap:myAccordion.toggle(section='section-id')".
expand(section=STRING) Разворачивает разделы accordion. Если раздел уже развернут, он остается развернутым. При вызове без аргументов разворачиваются все разделы accordion. Чтобы применить к определенному разделу, укажите идентификатор раздела: on="tap:myAccordion.expand(section='section-id')".
collapse(section=STRING) Сворачивает разделы accordion. Если раздел уже свернут, он остается свернутым. При вызове без аргументов сворачиваются все разделы accordion. Чтобы применить к определенному разделу, укажите идентификатор раздела: on="tap:myAccordion.collapse(section='section-id')".

amp-carousel[type="slides"]

Действие Описание
goToSlide(index=INTEGER) Прокручивает карусель до слайда с указанной позицией.

amp-image-lightbox

Действие Описание
open (default) Открывает лайтбокс, источником изображения в котором является изображение-инициатор действия.

amp-lightbox

Действие Описание
open (default) Открывает лайтбокс.
close Закрывает лайтбокс.

amp-list

Событие Описание Данные
changeToLayoutContainer Обновляет макет amp-list до layout="CONTAINTER", чтобы разрешить динамическое изменение размера.
fetch-error (низкий уровень доверия) Срабатывает при сбое загрузки данных. Нет

amp-selector

Действие Описание
clear Снимает выбор со всех пунктов меню определенного amp-selector.
selectUp(delta=INTEGER) Перемещает область выбора вверх на значение `delta`. По умолчанию `delta` имеет значение -1. Если не выбран ни один из пунктов меню, выбранным станет значение первого пункта.
selectDown(delta=INTEGER) Перемещает область выбора вниз на значение `delta`. По умолчанию `delta` имеет значение 1. Если не выбран ни один из пунктов меню, выбранным станет значение первого пункта.
toggle(index=INTEGER, value=BOOLEAN) Переключает атрибут 'selected'. Если атрибут отсутствует, это действие добавляет его. Если атрибут присутствует, он удаляется. Вы можете форсированно добавить или удалить атрибут, указав логическое значение в аргументе `value`. Значение `true` форсированно добавит атрибут `selected` и не удалит его, если он уже присутствует. Значение `false` удалит атрибут, но не добавит его, если он отсутствует.

amp-sidebar

Действие Описание
open (default) Открывает боковую панель.
close Закрывает боковую панель.
toggle Переключает состояние боковой панели.

form

Действие Описание
clear Удаляет все данные, введенные в форму.
submit Отправляет форму.

Особые цели

Система AMP предоставляет ряд целей, предъявляющих особые требования:

Цель: AMP

Цель AMP обеспечивается средой выполнения AMP; в ней реализованы действия верхнего уровня, которые применяются ко всему документу.

Действие Описание
setState({foo: 'bar'})1

Требует amp-bind.

Объединяет объектный литерал с привязываемым состоянием.

1 При использовании с несколькими действиями последующие действия будут ожидать setState() перед вызовом. Только одно setState() допускается для каждого события.