Действия с элементами
Когда пользователь нажимает на элемент, срабатывает действие.
{
"actions": [{
"log_id": "<unique_id>",
"url": "div-action://<action_description>?other/parameters"
}]
}
|
Параметр |
Описание |
|
|
Ссылка, которая открывается при срабатывании действия: обычный URL или действие DivKit в формате |
|
|
Опциональный идентификатор для логирования. Должен быть уникален в рамках одной карточки. |
|
|
Типизированное действие. Подробнее — в разделе Типизированные экшены. |
|
|
Включает или отключает действие. Отключенное действие не реагирует на связанное с ним событие. Значение по умолчанию — |
|
|
Дополнительные параметры, которые передаются приложению-хосту. |
|
|
Идентификатор элемента, в области видимости которого действие изменяет значения переменных. |
|
|
Контекстное меню. |
|
|
Ссылка для логирования. |
|
|
Referer-ссылка для логирования. Поддерживается на Android и iOS. |
|
|
Действия, которые выполняются после дозагрузки данных. |
|
|
Вкладка, в которой открывается ссылка: |
Примечание
Старые версии клиентов 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.
|
Пример действия |
Пример типизированного экшена |
|
|
Совет
Мы рекомендуем использовать типизированные экшены. Они позволяют не кодировать параметры и упрощают визуальное восприятие и валидацию верстки.
|
Название |
Описание |
|
Запускает указанный аниматор. |
|
|
Останавливает указанный аниматор. |
|
|
Добавляет значение в массив. |
|
|
Удаляет значение из массива. |
|
|
Устанавливает значение в массиве по индексу. |
|
|
Запрашивает фокус для элемента. Для текстовых полей ввода при повторном вызове на уже сфокусированном поле курсор перемещается в конец текста. |
|
|
Снимает фокус с элемента. |
|
|
Устанавливает позицию курсора в поле ввода. |
|
|
Копирует данные в буфер обмена. |
|
|
Задает значение в словаре по ключу. |
|
|
Выполняет дозагрузку данных в формате |
|
|
Показывает тултип. |
|
|
Скрывает тултип. |
|
|
Пролистывает контейнер со скроллом от текущей позиции на заданное значение |
|
|
Выполняет скролл к позиции или переключает элемент в контейнере на указанное значение |
|
|
Устанавливает новый внешний вид контента в |
|
|
Временно сохраняет переменную в хранилище. |
|
|
Присваивает переменной значение. |
|
|
Отправляет переменные из контейнера по ссылке. Конфигурация отправки данных может определяться приложением-хостом. По умолчанию переменные передаются в теле запроса в виде JSON, метод запроса — POST. |
|
|
Управляет таймером. |
|
|
Устанавливает значение в переменной типа массив или словарь с разной вложенностью. |
|
|
Управляет воспроизведением видео. |
|
|
Выполняет кастомное действие с пользовательскими данными. |
|
|
Воспроизводит тактильный отклик на устройствах Android и iOS. |
|
|
Отправляет команду расширению элемента. См. команды Lottie. |
Тактильный отклик
Действие haptic воспроизводит тактильный отклик (вибрацию) на устройстве пользователя. Поддерживается на Android (Views и Compose) и iOS.
Пример: тактильный отклик
{
"log_id": "haptic_feedback",
"typed": {
"type": "haptic",
"feedback": "success"
}
}
|
Параметр |
Описание |
|
|
Тип действия. Должен иметь значение |
|
|
Тип тактильного отклика. Опциональный параметр, по умолчанию используется |
Примечание
Работа тактильного отклика зависит от аппаратных возможностей устройства и системных настроек. Если тактильный отклик выключен в настройках операционной системы или недоступен на устройстве, действие будет пропущено без прерывания выполнения цепочки действий.
Кастомные действия
Кастомные действия позволяют выполнять пользовательскую логику, которая не покрывается стандартными действиями 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 приложении необходимо:
- Реализовать протокол
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
}
}
}
}
- Передать обработчик в конфигурацию 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
}
});
Параметры кастомного действия
|
Параметр |
Описание |
|
|
Произвольный словарь данных, который передается в приложение-хост для обработки. Может содержать любые пользовательские поля. |
Совет
Кастомные действия полезны для реализации специфичной бизнес-логики, которая не входит в стандартный набор действий 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.