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

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

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

Параметр

Описание

url

Ссылка, которая открывается при срабатывании действия: обычный URL или действие DivKit в формате div-action://.

log_id

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

typed

Типизированное действие. Подробнее — в разделе Типизированные экшены.

is_enabled

Включает или отключает действие. Отключенное действие не реагирует на связанное с ним событие. Значение по умолчанию — true.

payload

Дополнительные параметры, которые передаются приложению-хосту.

scope_id

Идентификатор элемента, в области видимости которого действие изменяет значения переменных.

menu_items

Контекстное меню.

log_url

Ссылка для логирования.

referer

Referer-ссылка для логирования. Поддерживается на Android и iOS.

download_callbacks

Действия, которые выполняются после дозагрузки данных.

target

Вкладка, в которой открывается ссылка: _self или _blank. Поддерживается только в Web.

Примечание

Старые версии клиентов DivKit игнорируют действия без log_id. Если карточку получают и такие клиенты, передавайте log_id в каждом действии.

Пример: действие без log_id
{
  "actions": [
    {
      "url": "div-action://set_variable?name=counter&value=1"
    }
  ]
}

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

Примечание

Элементы меню с is_enabled: false или без активных действий не отображаются в меню. Отображаются только те элементы меню, у которых есть хотя бы одно включенное действие.

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

  • actions — срабатывают при обычном нажатии
  • longtap_actions — срабатывают при долгом нажатии
  • doubletap_actions — срабатывают при двойном нажатии
  • press_start_actions — срабатывают в начале нажатия (например, при нажатии на ползунок слайдера)
  • press_end_actions — срабатывают в конце нажатия (например, при отпускании ползунка слайдера)
  • hover_start_actions и hover_end_actions — срабатывают, когда указатель наводится на элемент и когда уходит с него. Работают на платформах с указывающими устройствами (мышь, стилус)

Примечание

При нажатии на дочерний элемент с действиями, действия контейнера не срабатывают. Действия дочерних элементов имеют приоритет над действиями контейнера.

Свойство capture_focus_on_action определяет, что происходит с фокусом при срабатывании действия элемента: при значении true фокус переносится на этот элемент, при false остается на текущем сфокусированном элементе. Значение по умолчанию — true.

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

Типизированные экшены отличаются от стандартных действий по формату. Их можно указать в 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-animator-start

Запускает указанный аниматор.

div-action-animator-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-set-cursor-position

Устанавливает позицию курсора в поле ввода.

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. Поддерживает параметр duration для управления длительностью анимации.

div-action-scroll-to

Выполняет скролл к позиции или переключает элемент в контейнере на указанное значение destination. Поддерживает назначение item_id для прокрутки к элементу по его идентификатору (Android и веб) и параметр duration для управления длительностью анимации.

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

Управляет воспроизведением видео.

div-action-custom

Выполняет кастомное действие с пользовательскими данными.

div-action-haptic

Воспроизводит тактильный отклик на устройствах Android и iOS.

div-action-extension-action

Отправляет команду расширению элемента. См. команды Lottie.

Тактильный отклик

Действие haptic воспроизводит тактильный отклик (вибрацию) на устройстве пользователя. Поддерживается на Android (Views и Compose) и iOS.

Пример: тактильный отклик
{
  "log_id": "haptic_feedback",
  "typed": {
    "type": "haptic",
    "feedback": "success"
  }
}

Параметр

Описание

type

Тип действия. Должен иметь значение "haptic".

feedback

Тип тактильного отклика. Опциональный параметр, по умолчанию используется "light". Возможные значения:
- "light" — легкий отклик;
- "medium" — средний отклик;
- "heavy" — сильный отклик;
- "success" — отклик успеха;
- "error" — отклик ошибки.

Примечание

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

Кастомные действия

Кастомные действия позволяют выполнять пользовательскую логику, которая не покрывается стандартными действиями DivKit. Они передают произвольные данные (payload) в приложение-хост для обработки.

Использование кастомных действий

Для создания кастомного действия укажите тип "custom" и передайте необходимые данные в поле payload:

"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:
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
      }
    }
  }
}
  1. Передать обработчик в конфигурацию DivKit:
let divKitComponents = DivKitComponents(
  customActionHandler: MyCustomActionHandler(),
  // ... другие параметры
)

Обработка кастомных действий в Android

Переопределите метод handleCustomTypedAction в своем DivActionHandler и передайте обработчик в DivConfiguration:

class MyActionHandler : DivActionHandler() {
    override fun handleCustomTypedAction(
        action: DivActionTyped,
        scopeId: String?,
        view: DivViewFacade,
        actionUid: String?,
        reason: String?,
        evaluatedPayload: DictEvaluator?
    ) {
        // Обработка кастомного действия
    }
}

val configuration = DivConfiguration.Builder(imageLoader)
    .actionHandler(MyActionHandler())
    .build()

В параметре evaluatedPayload приходит payload действия с вычисленными выражениями. Если payload в действии не задан, параметр равен null.

Обработка кастомных действий в Web

Передайте в функцию render обработчик onCustomAction. Он вызывается для действий с "typed": {"type": "custom"} и для ссылок с нестандартной схемой:

render({
    id: 'smth',
    target: document.querySelector('#root'),
    json: {
        card: {},
        templates: {}
    },
    onCustomAction(action) {
        // Обработка кастомного действия, данные лежат в action.payload
    }
});

Параметры кастомного действия

Параметр

Описание

payload

Произвольный словарь данных, который передается в приложение-хост для обработки. Может содержать любые пользовательские поля.

Совет

Кастомные действия полезны для реализации специфичной бизнес-логики, которая не входит в стандартный набор действий DivKit, такой как навигация между экранами приложения, вызов специфичных API или интеграция с нативными модулями.

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

Выражения 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}"
      }
    }
  }
]

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

Другие возможности действий

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

Переключение внешнего вида контента в элементе state и действие set_state описаны на странице Наборы состояний.

Действия видимости

Действия, которые срабатывают без нажатия, когда элемент появляется на экране или исчезает с него, описаны на странице Действия видимости.

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

Действие download и формат патчей описаны на странице Дозагрузка данных и патчи.

Навигация по коллекциям и скролл

Переключение элементов и скролл в gallery, pager и tabs описаны на странице Навигация по коллекциям и скролл.

Управление элементами и данными

Действия, которые управляют конкретным элементом или данными, описаны на страницах этих элементов:

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

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

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