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

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

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

Параметр	Описание
`url`	Событие, вызываемое по нажатию на карточку.
`log_id`	Идентификатор для логирования. Должен быть уникален в рамках одной карточки.

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

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

Типизированные экшены

Типизированные экшены отличаются от стандартных действий по формату. Их можно указать в JSON-объекте. В стандартных действиях все параметры должны быть указаны в поле url.

Пример действия

Пример типизированного экшена

"actions": [
  {
    "log_id": "set_2",
    "url": "div-action://set_variable?name=variable&value=123"
  }
]

"actions": [
  {
    "log_id": "set_2",
    "typed": {
      "type": "set_variable",
      "variable_name": "variable",
      "value": {
        "type": "integer",
        "value": 123
      }
    }
  }
]

Совет

Мы рекомендуем использовать типизированные экшены. Они позволяют не кодировать параметры и упрощают визуальное восприятие и валидацию верстки.

Название	Описание
div-action-animation-start	Запускает указанный аниматор.
div-action-animation-stop	Останавливает указанный аниматор.
div-action-array-insert-value	Добавляет значение в массив.
div-action-array-remove-value	Удаляет значение из массива.
div-action-array-set-value	Устанавливает значение в массиве по индексу.
div-action-focus-element	Запрашивает фокус для элемента.
div-action-clear-focus	Снимает фокус с элемента.
div-action-copy-to-clipboard	Копирует данные в буфер обмена.
div-action-dict-set-value	Задает значение в словаре по ключу.
div-action-download	Выполняет дозагрузку данных в формате `div-patch` и обновляет текущий элемент.
div-action-show-tooltip	Показывает тултип.
div-action-hide-tooltip	Скрывает тултип.
div-action-scroll-by	Пролистывает контейнер со скроллом от текущей позиции на заданное значение `item_count` или `offset`.
div-action-scroll-to	Выполняет скролл к позиции или переключает элемент в контейнере на указанное значение `destination`.
div-action-set-state	Устанавливает новый внешний вид контента в `div-state`.
div-action-set-stored-value	Временно сохраняет переменную в хранилище.
div-action-set-variable	Присваивает переменной значение.
div-action-submit	Отправляет переменные из контейнера по ссылке. Конфигурация отправки данных может определяться приложением-хостом. По умолчанию переменные передаются в теле запроса в виде JSON, метод запроса — POST.
div-action-timer	Управляет таймером.
div-action-update-structure	Устанавливает значение в переменной типа массив или словарь с разной вложенностью.
div-action-video	Управляет воспроизведением видео.

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

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

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

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

Действия на элементах div-state

Сам элемент div-state поддерживает все стандартные свойства действий, позволяя добавлять интерактивное поведение непосредственно к контейнеру состояний:

actions — действия, срабатывающие при нажатии на элемент состояния
longtap_actions — действия, срабатывающие при долгом нажатии на элемент состояния
doubletap_actions — действия, срабатывающие при двойном нажатии на элемент состояния
press_start_actions / press_end_actions — действия, срабатывающие в начале/конце нажатия
hover_start_actions / hover_end_actions — действия, срабатывающие при наведении на элемент

Пример: div-state с действиями

{
  "type": "state",
  "div_id": "interactive_state",
  "states": [
    {
      "state_id": "default",
      "div": {
        "type": "text",
        "text": "Нажмите, чтобы изменить состояние"
      }
    },
    {
      "state_id": "clicked",
      "div": {
        "type": "text",
        "text": "Состояние изменено!"
      }
    }
  ],
  "actions": [
    {
      "log_id": "state_click",
      "url": "div-action://set_state?state_id=0/interactive_state/clicked"
    }
  ],
  "longtap_actions": [
    {
      "log_id": "state_long_press",
      "url": "div-action://set_variable?name=long_pressed&value=true"
    }
  ]
}

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

Чтобы переключиться на другое состояние, используйте 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
  }
}

Примечание

Для того чтобы использовать патчи на Android вам необходимо передать реализацию DivDownloader в используемую DivConfiguration.

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

Для навигации внутри 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

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

div-action://scroll_to_start?id=<div_id>
div-action://scroll_to_end?id=<div_id>

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

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

Скролл gallery на несколько dp вперед или назад, а также до конкретного значения

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

div-action://scroll_forward?id=<div_id>&step=<dp_count>&overflow=<clamp|ring>
div-action://scroll_backward?id=<div_id>&step=<dp_count>&overflow=<clamp|ring>

Для скролла gallery к конкретному значению dp укажите действие:

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

Параметр	Описание
`id`	Идентификатор элемента, в котором нужно переключить текущий.
`step`	Позиция в единицах dp, до которой нужно прокрутить или на сколько нужно прокрутить галерею, в зависимости от действия.
`overflow`	Указывает, как будет происходить навигация при достижении граничных элементов: `clamp` — переход остановится на граничном элементе (значение по умолчанию); `ring` — произойдет переход в начало или конец в зависимости от текущего элемента.

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

Чтобы показать или скрыть тултипы, укажите действие 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>&lifetime=<lifetime_in_sec>

Параметр	Описание
`name`	Имя переменной.
`value`	Значение, которое будет сохранено.
`type`	Тип переменной. Должен быть одним из `string`, `number`, `integer`, `url`, `color`.
`lifetime`	Время жизни переменной в хранилище в секундах. При попытке достать переменную позже, она будет считаться устаревшей.

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

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

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

Порядок вычисления выражений в действиях

Когда в массиве указано несколько действий, существует два типа выражений с разным временем вычисления:

Выражения is_enabled - Все выражения is_enabled для всех действий в массиве вычисляются одновременно перед выполнением любых действий
Выражения параметров действий - Выражения параметров каждого действия вычисляются непосредственно перед выполнением этого действия

Это гарантирует, что изменения, внесенные предыдущими действиями в последовательности, правильно отражаются в параметрах последующих действий.

Например, в следующей последовательности действий:

"actions": [
  {
    "log_id": "1",
    "is_enabled": "@{enable_actions}",
    "typed": {
      "type": "set_variable",
      "variable_name": "counter",
      "value": {
        "type": "integer",
        "value": 5
      }
    }
  },
  {
    "log_id": "2",
    "is_enabled": "@{counter > 0}",
    "typed": {
      "type": "set_variable",
      "variable_name": "message",
      "value": {
        "type": "string",
        "value": "Done"
      }
    }
  },
  {
    "log_id": "3",
    "is_enabled": "@{message != ''}",
    "typed": {
      "type": "set_variable",
      "variable_name": "result",
      "value": {
        "type": "string",
        "value": "@{message}"
      }
    }
  }
]

Все выражения is_enabled (@{enable_actions}, @{counter > 0}, @{message != ''}) вычисляются одновременно в самом начале, до выполнения любых действий
Выражение @{message} в третьем действии вычисляется непосредственно перед выполнением третьего действия и будет отражать изменения, внесенные вторым действием

Это означает, что если переменная counter изначально равна 0, то выражения is_enabled для второго и третьего действий будут вычислены как false еще до выполнения первого действия, даже если первое действие должно было бы установить значение counter равное 5.

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

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

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

Была ли статья полезна?

Всплывающие подсказки

Шаблоны