--- metadata: - name: generator content: Diplodoc Platform v5.50.3 alternate: - https://divkit.tech/docs/en/concepts/interaction.md - https://divkit.tech/docs/ru/concepts/interaction.md --- > **Documentation Index:** Fetch the complete configuration index at https://divkit.tech/docs/ru/llms.txt # Действия с элементами Когда пользователь нажимает на элемент, срабатывает [действие](https://divkit.tech/docs/ru/concepts/divs/2/div-action.md). ```json translate=no { "actions": [{ "log_id": "", "url": "div-action://?other/parameters" }] } ``` #| || **Параметр** | **Описание** || || `url` | Событие, вызываемое по нажатию на карточку. || || `log_id` | Идентификатор для логирования. Должен быть уникален в рамках одной карточки. || |# С помощью специального параметра `menu_items` можно по нажатию открывать меню. Если хотя бы одно действие в массиве имеет поле `menu_items`, то при нажатии на элемент будет показано меню, а все остальные поля будут проигнорированы. {% note info %} Элементы меню с `is_enabled: false` или без активных действий не отображаются в меню. Отображаются только те элементы меню, у которых есть хотя бы одно включенное действие. {% endnote %} Действия могут быть привязаны к различным типам жестов: - `actions` — срабатывают при обычном нажатии - `longtap_actions` — срабатывают при долгом нажатии - `doubletap_actions` — срабатывают при двойном нажатии - `press_start_actions` — срабатывают в начале нажатия (например, при нажатии на ползунок слайдера) - `press_end_actions` — срабатывают в конце нажатия (например, при отпускании ползунка слайдера) {% note info %} При нажатии на дочерний элемент с действиями, действия контейнера не срабатывают. Действия дочерних элементов имеют приоритет над действиями контейнера. {% endnote %} ## Типизированные экшены {#typed-actions} Типизированные экшены отличаются от стандартных действий по формату. Их можно указать в JSON-объекте. В стандартных действиях все параметры должны быть указаны в поле `url`. #| || **Пример действия** | **Пример типизированного экшена** || || ```json "actions": [ { "log_id": "set_2", "url": "div-action://set_variable?name=variable&value=123" } ] ``` | ```json "actions": [ { "log_id": "set_2", "typed": { "type": "set_variable", "variable_name": "variable", "value": { "type": "integer", "value": 123 } } } ] ``` || |# {% note tip %} Мы рекомендуем использовать типизированные экшены. Они позволяют не кодировать параметры и упрощают визуальное восприятие и валидацию верстки. {% endnote %} #| || **Название** | **Описание** || || [div-action-animation-start](https://divkit.tech/docs/ru/concepts/divs/2/div-action-animator-start.md) | Запускает указанный аниматор. || || [div-action-animation-stop](https://divkit.tech/docs/ru/concepts/divs/2/div-action-animator-stop.md) | Останавливает указанный аниматор. || || [div-action-array-insert-value](https://divkit.tech/docs/ru/concepts/divs/2/div-action-array-insert-value.md) | Добавляет значение в массив. || || [div-action-array-remove-value](https://divkit.tech/docs/ru/concepts/divs/2/div-action-array-remove-value.md) | Удаляет значение из массива. || || [div-action-array-set-value](https://divkit.tech/docs/ru/concepts/divs/2/div-action-array-set-value.md)| Устанавливает значение в массиве по индексу. || || [div-action-focus-element](https://divkit.tech/docs/ru/concepts/divs/2/div-action-focus-element.md) | Запрашивает фокус для элемента. Для текстовых полей ввода при повторном вызове на уже сфокусированном поле курсор перемещается в конец текста. || || [div-action-clear-focus](https://divkit.tech/docs/ru/concepts/divs/2/div-action-clear-focus.md) | Снимает фокус с элемента. || || [div-action-set-cursor-position](https://divkit.tech/docs/ru/concepts/divs/2/div-action-set-cursor-position.md) | Устанавливает позицию курсора в поле ввода. || || [div-action-copy-to-clipboard](https://divkit.tech/docs/ru/concepts/divs/2/div-action-copy-to-clipboard.md) | Копирует данные в буфер обмена. || || [div-action-dict-set-value](https://divkit.tech/docs/ru/concepts/divs/2/div-action-dict-set-value.md) | Задает значение в словаре по ключу. || || [div-action-download](https://divkit.tech/docs/ru/concepts/divs/2/div-action-download.md) | Выполняет дозагрузку данных в формате `div-patch` и обновляет текущий элемент. || || [div-action-show-tooltip](https://divkit.tech/docs/ru/concepts/divs/2/div-action-show-tooltip.md) | Показывает тултип. || || [div-action-hide-tooltip](https://divkit.tech/docs/ru/concepts/divs/2/div-action-hide-tooltip.md) | Скрывает тултип. || || [div-action-scroll-by](https://divkit.tech/docs/ru/concepts/divs/2/div-action-scroll-by.md) | Пролистывает контейнер со скроллом от текущей позиции на заданное значение `item_count` или `offset`. || || [div-action-scroll-to](https://divkit.tech/docs/ru/concepts/divs/2/div-action-scroll-to.md) | Выполняет скролл к позиции или переключает элемент в контейнере на указанное значение `destination`. Поддерживает назначение `item_id` для прокрутки к элементу по его идентификатору. || || [div-action-set-state](https://divkit.tech/docs/ru/concepts/divs/2/div-action-set-state.md) | Устанавливает новый внешний вид контента в `div-state`. || || [div-action-set-stored-value](https://divkit.tech/docs/ru/concepts/divs/2/div-action-set-stored-value.md) | Временно сохраняет переменную в хранилище. || || [div-action-set-variable](https://divkit.tech/docs/ru/concepts/divs/2/div-action-set-variable.md) | Присваивает переменной значение. || || [div-action-submit](https://divkit.tech/docs/ru/concepts/divs/2/div-action-submit.md) | Отправляет переменные из контейнера по ссылке. Конфигурация отправки данных может определяться приложением-хостом. По умолчанию переменные передаются в теле запроса в виде JSON, метод запроса — POST. || || [div-action-timer](https://divkit.tech/docs/ru/concepts/divs/2/div-action-timer.md) | Управляет таймером. || || [div-action-update-structure](https://divkit.tech/docs/ru/concepts/divs/2/div-action-update-structure.md) | Устанавливает значение в переменной типа массив или словарь с разной вложенностью. || || [div-action-video](https://divkit.tech/docs/ru/concepts/divs/2/div-action-video.md) | Управляет воспроизведением видео. || || [div-action-custom](https://divkit.tech/docs/ru/concepts/divs/2/div-action-custom.md) | Выполняет кастомное действие с пользовательскими данными. || |# ## Наборы состояний {#states} Элемент [state](https://divkit.tech/docs/ru/concepts/divs/2/div-state.md) переключает внешний вид контента. С его помощью можно добавлять: - кнопки, которые меняют свое состояние (например, значок лайка при нажатии); - раскрываемый контент (например, карточку мостов или геоблок). На самом деле одна картинка меняется на другую, но пользователю кажется, что это интерактивное взаимодействие. ### Действия на элементах div-state {#state-actions} Сам элемент `div-state` поддерживает все стандартные свойства действий, позволяя добавлять интерактивное поведение непосредственно к контейнеру состояний: - `actions` — действия, срабатывающие при нажатии на элемент состояния - `longtap_actions` — действия, срабатывающие при долгом нажатии на элемент состояния - `doubletap_actions` — действия, срабатывающие при двойном нажатии на элемент состояния - `press_start_actions` / `press_end_actions` — действия, срабатывающие в начале/конце нажатия - `hover_start_actions` / `hover_end_actions` — действия, срабатывающие при наведении на элемент {% note info %} Свойства `press_start_actions` и `press_end_actions` особенно полезны для компонентов с непрерывным взаимодействием, таких как слайдеры, где важно отслеживать начало и конец жеста перетаскивания. {% endnote %} {% cut "Пример: div-state с действиями" %} ```json { "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" } ] } ``` {% endcut %} Это позволяет создавать более сложное интерактивное поведение, когда сам контейнер состояний реагирует на взаимодействия пользователя, в дополнение к отдельным элементам внутри каждого состояния. Чтобы переключиться на другое состояние, используйте `url`: ```translate=no div-action://set_state?state_id=&temporary= ``` Путь формируется от корня иерархии: #| || **Параметр** | **Описание** || || `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](https://divkit.tech/docs/ru/concepts/divs/2/div-data.md); - `div_id` — значение `div_id` объекта `state`; - `state_id` — значение `state_id` объекта ``state`` в [state](https://divkit.tech/docs/ru/concepts/divs/2/div-state.md). || || `temporary` | Указывает на изменение состояния: - `true` — изменение временное и при пересоздании элемента состояние изменится на исходное (значение по умолчанию); - `false` — изменение состояния является постоянным. || |# {% cut "Посмотреть интерактивный пример" %} {% endcut %} ### Пустое состояние {#empty} Если нужно скрыть какой-то блок, то можно не добавлять поле `div`, а указать `"state_id": "empty"`. ![](../_images/create-card/empty-state-anim.gif =360x) {% cut "Посмотреть интерактивный пример" %} {% endcut %} ### Вложенные состояния {#nested} Если несколько состояний вложено друг в друга, то для переключения напишите полный путь от корня: ```translate=no div-action://set_state?state_id=[id корневого состояния]/[div_id элемента]/[state_id состояния] ``` {% cut "Посмотреть интерактивный пример" %} {% endcut %} ## Действия при появлении {#visibility} Элементы [visibility](https://divkit.tech/docs/ru/concepts/divs/2/div-visibility-action.md) срабатывают, когда элемент показывается на экране. ```json translate=no { "visibility_actions": [ { "log_id":"content_01_visibility", "visibility_percentage": 100, "visibility_duration": 1000, "url": "div-action://none" } ] } ``` #| || **Параметр** | **Описание** || || `visibility_percentage` | Процент видимой площади элемента. || || `visibility_duration` | Минимальное время его видимости. || |# ## Дозагрузка данных {#loading-data} Для дозагрузки данных в виде [patch](https://divkit.tech/docs/ru/concepts/divs/2/div-patch.md) и обновления текущего элемента укажите действие `download`: ```translate=no div-action://download?url= ``` #| || **Параметр** | **Описание** || || `url` | Ссылка для получения патча. || |# Формат ответа: ```json translate=no { "patch": { // данные в формате patch }, "templates": { // шаблоны, которые могут быть использованы в секции patch } } ``` {% note info %} Для того чтобы использовать патчи на Android вам необходимо передать реализацию `DivDownloader` в используемую `DivConfiguration`. {% endnote %} ## Переключение элементов {#switch-elements} Для навигации внутри [gallery](https://divkit.tech/docs/ru/concepts/divs/2/div-gallery.md), [pager](https://divkit.tech/docs/ru/concepts/divs/2/div-pager.md) и [tabs](https://divkit.tech/docs/ru/concepts/divs/2/div-tabs.md) укажите действие: - `set_current_item` — для текущего элемента; - `set_next_item` — для следующего элемента; - `set_previous_item` — для предыдущего элемента. ```translate=no div-action://set_current_item?id=&item= div-action://set_next_item?id=&overflow= div-action://set_previous_item?id=&overflow= ``` #| || **Параметр** | **Описание** || || `id` | Идентификатор элемента, в котором нужно переключить текущий. || || `item` | Номер элемента, до которого необходимо проскроллить. || || `overflow` | Указывает, как будет происходить навигация при достижении граничных элементов: - `clamp` — переход остановится на граничном элементе (значение по умолчанию); - `ring` — произойдет переход в начало или конец в зависимости от текущего элемента. || |# ### Переход в начало или конец gallery Для перехода в начало или конец [gallery](https://divkit.tech/docs/ru/concepts/divs/2/div-gallery.md) укажите действие: ```translate=no div-action://scroll_to_start?id= div-action://scroll_to_end?id= ``` #| || **Параметр** | **Описание** || || `id` | Идентификатор элемента, в котором нужно переключить текущий. || |# Если элементы внутри `gallery` будут больше, чем размер галлереи, то действие `scroll_to_end` прокрутит ее до конца последнего элемента. ### Скролл gallery на несколько dp вперед или назад, а также до конкретного значения Для скролла [gallery](https://divkit.tech/docs/ru/concepts/divs/2/div-gallery.md) вперед или назад укажите действие: ```translate=no div-action://scroll_forward?id=&step=&overflow= div-action://scroll_backward?id=&step=&overflow= ``` Для скролла [gallery](https://divkit.tech/docs/ru/concepts/divs/2/div-gallery.md) к конкретному значению dp укажите действие: ```translate=no div-action://scroll_to_position?id=&step= ``` #| || **Параметр** | **Описание** || || `id` | Идентификатор элемента, в котором нужно переключить текущий. || || `step` | Позиция в единицах [dp](https://en.wikipedia.org/wiki/Device-independent_pixel), до которой нужно прокрутить или на сколько нужно прокрутить галерею, в зависимости от действия. || || `overflow` | Указывает, как будет происходить навигация при достижении граничных элементов: - `clamp` — переход остановится на граничном элементе (значение по умолчанию); - `ring` — произойдет переход в начало или конец в зависимости от текущего элемента. || |# ## Установка позиции курсора {#set-cursor-position} Чтобы установить позицию курсора в поле ввода, используйте типизированный экшен `set_cursor_position`: {% cut "Посмотреть пример" %} ```json translate=no { "log_id": "set_cursor", "typed": { "type": "set_cursor_position", "id": "input_1", "position": { "type": "absolute", "start": 0, "end": -1 } } } ``` {% endcut %} #| || **Параметр** | **Описание** || || `id` | Идентификатор поля ввода. || || `position` | Объект с параметрами позиции: - `type`: `"absolute"` (единственный поддерживаемый тип) - `start`: начальная позиция (обязательный, число) - `end`: конечная позиция (опциональный, число) Если `end` не задан или равен `start` - устанавливается позиция курсора. Если `end` отличается от `start` - выделяется текст. Значение `-1` указывает на конец текста. || |# ## Управление тултипами {#managing-tooltips} Чтобы показать или скрыть тултипы, укажите действие `show_tooltip` или `hide_tooltip`: ```translate=no div-action://show_tooltip?id= div-action://hide_tooltip?id= ``` #| || **Параметр** | **Описание** || || `id` | Идентификатор тултипа. || |# ## Управление видео {#video} Для управления [видео](https://divkit.tech/docs/ru/concepts/video.md) используйте действие `video`: ```translate=no div-action://video?id=video_id&action= ``` #| || **Параметр** | **Описание** || || `id` | Идентификатор элемента с видео. || || `action` | Действие с видео: - `start` — продолжить воспроизведение; - `pause` — поставить на паузу. || |# ## Управление таймерами {#timer} Для управления [таймерами](https://divkit.tech/docs/ru/concepts/timer.md) используйте действие `timer`: ```translate=no div-action://timer?action=&id= ``` #| || **Параметр** | **Описание** || || `id` | Идентификатор таймера. || || `action` | Действие с таймером: - `start` — запустить таймер; - `stop` — остановить таймер; - `pause` — приостановить отсчет; - `resume` — продолжить отсчет; - `cancel` — остановить таймер; - `reset` — перезапустить таймер. || |# ## Изменение значений переменных {#variables-values } Чтобы изменить значение [переменных](https://divkit.tech/docs/ru/concepts/variables.md), укажите действие `set_variable`: ```translate=no div-action://set_variable?name=&value= ``` #| || **Параметр** | **Описание** || || `name` | Имя переменной. || || `value` | Новое значение. || |# ## Сохранение переменных во временное хранилищe Чтобы временно сохранить значение переменных в хранилище, укажите действие `set_stored_value`: ```translate=no div-action://set_stored_value?name=&value=&type=&lifetime= ``` #| || **Параметр** | **Описание** || || `name` | Имя переменной. || || `value` | Значение, которое будет сохранено. || || `type` | Тип переменной. Должен быть одним из `string`, `number`, `integer`, `url`, `color`. || || `lifetime` | Время жизни переменной в хранилище в секундах. При попытке достать переменную позже, она будет считаться устаревшей. || |# Для того чтобы достать значение сохраненной переменной необходимо использовать вычисляемые выражения: ```translate=no @{getStoredStringValue(name, default)} @{getStoredNumberValue(name, default)} @{getStoredIntegerValue(name, default)} @{getStoredUrlValue(name, default)} @{getStoredColorValue(name, default)} ``` Параметр `name` все также является именем сохраненной переменной, `default` - значение по-умолчанию, которое вернется, если переменная не найдена или устарела. ## Кастомные действия {#custom-actions} Кастомные действия позволяют выполнять пользовательскую логику, которая не покрывается стандартными действиями DivKit. Они передают произвольные данные (payload) в приложение-хост для обработки. ### Использование кастомных действий Для создания кастомного действия укажите тип `"custom"` и передайте необходимые данные в поле `payload`: ```json "actions": [ { "log_id": "custom_action_1", "typed": { "type": "custom" }, "payload": { "action_type": "open_profile", "user_id": "12345", "additional_data": "custom_value" } } ] ``` ### Обработка кастомных действий в iOS Для обработки кастомных действий в iOS приложении необходимо: 1. Реализовать протокол `DivCustomActionHandling`: ```swift class MyCustomActionHandler: DivCustomActionHandling { func handle( payload: DivDictionary, context: DivActionHandlingContext, sender: AnyObject? ) { // Обработка кастомного действия if let actionType = payload["action_type"] as? String { switch actionType { case "open_profile": if let userId = payload["user_id"] as? String { // Открыть профиль пользователя openUserProfile(userId: userId) } default: break } } } } ``` 2. Передать обработчик в конфигурацию DivKit: ```swift let divKitComponents = DivKitComponents( customActionHandler: MyCustomActionHandler(), // ... другие параметры ) ``` ### Параметры кастомного действия #| || **Параметр** | **Описание** || || `payload` | Произвольный словарь данных, который передается в приложение-хост для обработки. Может содержать любые пользовательские поля. || |# {% note tip %} Кастомные действия полезны для реализации специфичной бизнес-логики, которая не входит в стандартный набор действий DivKit, такой как навигация между экранами приложения, вызов специфичных API или интеграция с нативными модулями. {% endnote %} ## Порядок вычисления выражений в действиях {#evaluation-order} Выражения `is_enabled` и параметров действий вычисляются непосредственно перед выполнением каждого действия. {% cut "Пример" %} ```json translate=no "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}" } } } ] ``` Если переменная `counter` изначально равна `0`, но первое действие устанавливает значение `counter` равное `5`, то второе действие будет выполнено, так как его `is_enabled` проверяется после выполнения первого действия. {% endcut %} ## Узнать больше {#troubleshooting} Вы можете обсуждать интересующие вас темы в сообществе пользователей DivKit в Telegram: [https://t.me/divkit_community_ru](https://t.me/divkit_community_ru). [Репозиторий DivKit](https://github.com/divkit/divkit)