Действия с элементами

Когда пользователь нажимает на карточку, action вызывает указанное в url событие.

{
  "actions": [{
    "log_id": "<unique_id>",
    "url": "div-action://<action_description>?other/parameters"
  }]
}

Параметр

Описание

url

Событие, вызываемое по нажатию на карточку.

log_id

Идентификатор для логирования. Должен быть уникален в рамках одной карточки.

С помощью специального параметра menu_items можно по нажатию открывать меню. Если хотя бы одно действие в массиве имеет поле menu_items, то при нажатии на элемент будет показано меню, а все остальные поля будут проигнорированы.

Отдельный тип действий — действия, которые срабатывают только на долгое нажатие (longtap-actions).

Наборы состояний

Элемент state переключает внешний вид контента. С его помощью можно добавлять:

  • кнопки, которые меняют свое состояние (например, значок лайка при нажатии);
  • раскрываемый контент (например, карточку мостов или геоблок).

На самом деле одна картинка меняется на другую, но пользователю кажется, что это интерактивное взаимодействие.

Чтобы переключиться на другое состояние, используйте url:

div-action://set_state?state_id=<div_data_state_id/div_id/state_id>&temporary=<bool>

Путь формируется от корня иерархии:

Параметр

Описание

state_id

Путь состояния внутри state, которое нужно активировать. Задается в формате div_data_state_id/div_id/state_id.

Может быть иерархическим: div_data_state_id/div_id_1/state_id_1/../div_id_n/state_id_n
Состоит из:

  • div_data_state_id — числовое значение state_id объекта state в data;
  • div_id — значение div_id объекта state;
  • state_id — значение state_id объекта state в state.

temporary

Указывает на изменение состояния:

  • true — изменение временное и при пересоздании элемента состояние изменится на исходное (значение по умолчанию);
  • false — изменение состояния является постоянным.
Посмотреть интерактивный пример

Пустое состояние

Если нужно скрыть какой-то блок, то можно не добавлять поле div, а указать "state_id": "empty".

Посмотреть интерактивный пример

Вложенные состояния

Если несколько состояний вложено друг в друга, то для переключения напишите полный путь от корня:

div-action://set_state?state_id=[id корневого состояния]/[div_id элемента]/[state_id состояния]
Посмотреть интерактивный пример

Действия при появлении

Элементы visibility срабатывают, когда элемент показывается на экране.

{
  "visibility_actions": [
    {
      "log_id":"content_01_visibility",
      "visibility_percentage": 100,
      "visibility_duration": 1000,
      "url": "div-action://none"
    }
  ]
}

Параметр

Описание

visibility_percentage

Процент видимой площади элемента.

visibility_duration

Минимальное время его видимости.

Дозагрузка данных

Для дозагрузки данных в виде patch и обновления текущего элемента укажите действие download:

div-action://download?url=<patch_url>

Параметр

Описание

url

Ссылка для получения патча.

Формат ответа:

{
  "patch": {
    // данные в формате patch
  },
  "templates": {
    // шаблоны, которые могут быть использованы в секции patch
  }
}

Переключение элементов

Для навигации внутри gallery, pager и tabs укажите действие:

  • set_current_item — для текущего элемента;
  • set_next_item — для следующего элемента;
  • set_previous_item — для предыдущего элемента.
div-action://set_current_item?id=<div_id>&item=<item_index>
div-action://set_next_item?id=<div_id>&overflow=<clamp|ring>
div-action://set_previous_item?id=<div_id>&overflow=<clamp|ring>

Параметр

Описание

id

Идентификатор элемента, в котором нужно переключить текущий.

item

Минимальное время его видимости.

overflow

Указывает, как будет происходить навигация при достижении граничных элементов:

  • clamp — переход остановится на граничном элементе (значение по умолчанию);
  • ring — произойдет переход в начало или конец в зависимости от текущего элемента.

Для перехода в начало или конец gallery укажите действие:

div-action://scroll_to_start?id=<div_id>&overflow=<clamp|ring>
div-action://scroll_to_end?id=<div_id>&overflow=<clamp|ring>

Параметр

Описание

id

Идентификатор элемента, в котором нужно переключить текущий.

overflow

Указывает, как будет происходить навигация при достижении граничных элементов:

  • clamp — переход остановится на граничном элементе (значение по умолчанию);
  • ring — произойдет переход в начало или конец в зависимости от текущего элемента.

Если элементы внутри gallery будут больше, чем размер галлереи, то действие scroll_to_end прокрутит ее до конца последнего элемента.

Для перехода в начало или конец gallery укажите действие:

div-action://scroll_forward?id=<div_id>&item=<dp_count>
div-action://scroll_backward?id=<div_id>&step=<dp_count>
div-action://scroll_to_position?id=<div_id>&step=<dp_count>

Параметр

Описание

id

Идентификатор элемента, в котором нужно переключить текущий.

step

Позиция в единицах dp, до которой нужно прокрутить или на сколько нужно прокрутить галерею, в зависимости от действия.

Если элементы внутри gallery будут больше, чем размер галлереи, то действие scroll_to_end прокрутит ее до конца последнего элемента.

Управление тултипами

Чтобы показать или скрыть тултипы, укажите действие show_tooltip или hide_tooltip:

div-action://show_tooltip?id=<tooltip_id>
div-action://hide_tooltip?id=<tooltip_id>

Параметр

Описание

id

Идентификатор тултипа.

Управление видео

Для управления видео используйте действие video:

div-action://video?id=video_id&action=<start|pause>

Параметр

Описание

id

Идентификатор элемента с видео.

action

Действие с видео:

  • start — продолжить воспроизведение;
  • pause — поставить на паузу.

Управление таймерами

Для управления таймерами используйте действие timer:

div-action://timer?action=<action>&id=<id>

Параметр

Описание

id

Идентификатор таймера.

action

Действие с таймером:

  • start — запустить таймер;
  • stop — остановить таймер;
  • pause — приостановить отсчет;
  • resume — продолжить отсчет;
  • cancel — остановить таймер;
  • reset — перезапустить таймер.

Изменение значений переменных

Чтобы изменить значение переменных, укажите действие set_variable:

div-action://set_variable?name=<variable_name>&value=<new_value>

Параметр

Описание

name

Имя переменной.

value

Новое значение.

Сохранение переменных во временное хранилищe

Чтобы временно сохранить значение переменных в хранилище, укажите действие set_stored_value:

div-action://set_stored_value?name=<variable_name>&value=<new_value>&type=<variable_type>&lifetyme=<lifetime_in_sec>

Параметр

Описание

name

Имя переменной.

value

Значение, которое будет сохранено.

type

Тип переменной. Должен быть одним из string, number, integer, url, color.

lifetyme

Время жизни переменной в хранилище в секундах. При попытке достать переменную позже, она будет считаться устаревшей.

Для того чтобы достать значение сохраненной переменной необходимо использовать вычисляемые выражения:

@{getStoredStringValue(name, default)}
@{getStoredNumberValue(name, default)}
@{getStoredIntegerValue(name, default)}
@{getStoredUrlValue(name, default)}
@{getStoredColorValue(name, default)}

Параметр name всё также является именем сохраненной переменной, default - значение по-умолчанию, которое вернется, если переменная не найдена или устарела.

Узнать больше

Следите за новостями DivKit в Telegram-канале: http://t.me/divkit_news

Также вы можете обсуждать интересующие вас темы в сообществе пользователей DivKit в Telegram: https://t.me/divkit_community_ru

Репозиторий DivKit

Предыдущая
Видео
Следующая
Шаблоны