Actions with elements
When the user taps the card, action calls the event specified in url
.
{
"actions": [{
"log_id": "<unique_id>",
"url": "div-action://<action_description>?other/parameters"
}]
}
Parameter |
Description |
|
An event that is triggered by tapping the card. |
|
Logging ID. It must be unique within a single card. |
You can open the menu by tapping using the special menu_items
parameter. If at least one action in the array has a menu_items
field, tapping the element will show a menu, and all other fields will be ignored.
A separate type of action are actions that are triggered only by a long tap (longtap-actions
).
Typed actions
Typed actions differ from standard actions in format. They can be specified in a JSON object. In standard actions, all parameters must be specified in the url
field.
Action example |
Typed action example |
|
|
Tip
We recommend using typed actions. They allow you to avoid encoding parameters and simplify visual perception and layout validation.
Name |
Description |
Starts the specified animator. |
|
Stops the specified animator. |
|
Adds a value to an array. |
|
Removes a value from an array. |
|
Sets a value in an array by index. |
|
Requests focus for an element. |
|
Removes focus from an element. |
|
Copies data to the clipboard. |
|
Sets a value in a dictionary by key. |
|
Downloads additional data in |
|
Shows a tooltip. |
|
Hides a tooltip. |
|
Scrolls a scrollable container from the current position by the specified |
|
Scrolls to a position or switches an element in a container to the specified |
|
Sets a new appearance for content in |
|
Temporarily stores a variable in storage. |
|
Assigns a value to a variable. |
|
Sends variables from a container via a link. Data sending configuration can be determined by the host application. By default, variables are passed in the request body as JSON, request method is POST. |
|
Controls a timer. |
|
Controls video playback. |
Sets of states
The state element switches the appearance of content. You can use it to add:
- Buttons that change their state (for example, the like icon when tapped).
- Content that can be expanded (for example, a bridge card or a geo block).
One picture changes to another, but the user sees it as an interaction.
To switch to a different state, use url
:
div-action://set_state?state_id=<div_data_state_id/div_id/state_id>&temporary=<bool>
The path is formed from the hierarchy root:
Parameter |
Description |
|
The path of the state inside Can be hierarchical: |
|
Indicates a state change:
|
View an interactive example
Empty state
If you need to hide a block, don't add a div
field, but specify "state_id": "empty"
.
View an interactive example
Nested states
If multiple states are nested in each other, write the full path from the root in order to switch:
div-action://set_state?state_id=[root state id]/[element's div_id]/[state's state_id]
View an interactive example
Actions when appearing
visibility elements are triggered when an element is shown on the screen.
{
"visibility_actions": [
{
"log_id":"content_01_visibility",
"visibility_percentage": 100,
"visibility_duration": 1000,
"url": "div-action://none"
}
]
}
Parameter |
Description |
|
Percentage of the element's visible area. |
|
The minimum time of its visibility. |
Loading more data
To load more data in the form of a patch and update the current element, specify the download
action:
div-action://download?url=<patch_url>
Parameter |
Description |
|
URL to get the patch. |
Response format:
{
"patch": {
// data in patch format
},
"templates": {
// templates that can be used in the patch section
}
}
Note
To use patches on Android, pass a DivDownloader
implementation to your DivConfiguration
.
Switching elements
To navigate inside gallery, pager, and tabs, specify an action:
set_current_item
: For the current element.set_next_item
: For the next element.set_previous_item
: For the previous element.
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>
Parameter |
Description |
|
ID of the element in which the current one must be switched. |
|
Index of the element to scroll to. |
|
Specifies how navigation will occur when the boundary elements are reached:
|
Jump to the start or end of the gallery
To jump to the start or end of the gallery, specify the following action:
div-action://scroll_to_start?id=<div_id>
div-action://scroll_to_end?id=<div_id>
Parameter |
Description |
|
ID of the element in which the current one must be switched. |
If the elements inside gallery
are bigger than the gallery itself, the scroll_to_end
action scrolls it to the end of the last element.
Scroll the gallery several dp forward or backward, or to a specific value
To scroll the gallery forward or backward, specify the following action:
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>
To scroll the gallery to a specific value, specify the following action:
div-action://scroll_to_position?id=<div_id>&step=<dp_count>
Parameter |
Description |
|
ID of the element in which the current one must be switched. |
|
Value in dp representing either the position to scroll the gallery to or the scroll step, depending on the action. |
|
Specifies how navigation will occur when the boundary elements are reached:
|
Managing tooltips
To show or hide tooltips, specify the show_tooltip
or hide_tooltip
action:
div-action://show_tooltip?id=<tooltip_id>
div-action://hide_tooltip?id=<tooltip_id>
Parameter |
Description |
|
Tooltip ID. |
Video controls
To control a video, use the video
action:
div-action://video?id=video_id&action=<start|pause>
Parameter |
Description |
|
ID of an element with a video. |
|
Actions with videos:
|
Timer controls
To control a timer, use the timer
action:
div-action://timer?action=<action>&id=<id>
Parameter |
Description |
|
Timer ID. |
|
Actions with timers:
|
Changing the values of variables
To change the value of variables, specify the set_variable
action:
div-action://set_variable?name=<variable_name>&value=<new_value>
Parameter |
Description |
|
Variable name. |
|
New value. |
Saving variables to temporary storage
To temporarily store variable values, specify the set_stored_value
action:
div-action://set_stored_value?name=<variable_name>&value=<new_value>&type=<variable_type>&lifetime=<lifetime_in_sec>
Parameter |
Description |
|
Variable name. |
|
Value to save. |
|
Variable type. Must be |
|
Variable's storage lifetime in seconds. If you attempt to retrieve the variable after this time, it will be considered expired. |
To get the value of a stored variable, use calculated expressions:
@{getStoredStringValue(name, default)}
@{getStoredNumberValue(name, default)}
@{getStoredIntegerValue(name, default)}
@{getStoredUrlValue(name, default)}
@{getStoredColorValue(name, default)}
The name
parameter still represents the name of the stored variable, and default
is the value to return if the variable can't be found or has expired.
Order of evaluation of expressions in actions
When multiple actions are specified in an array, there are two types of expressions with different evaluation timing:
is_enabled
expressions - Allis_enabled
expressions for all actions in the array are evaluated at once before any actions are executed- Action parameter expressions - Each action's parameter expressions are evaluated just before that action is executed
This ensures that changes made by previous actions in the sequence are properly reflected in subsequent action parameters.
For example, in the following sequence of actions:
"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}"
}
}
}
]
- All
is_enabled
expressions (@{enable_actions}
,@{counter > 0}
,@{message != ''}
) are evaluated simultaneously at the very beginning, before executing any actions - The expression
@{message}
in the third action is evaluated just before executing the third action and will reflect the changes made by the second action
This means that if the counter
variable is initially 0
, then the is_enabled
expressions for the second and third actions will be evaluated as false
even before the first action is executed, even though the first action should have set the counter
value to 5
.
Learn more
Follow DivKit news in the Telegram channel: http://t.me/divkit_news
You can also discuss topics of interest in the DivKit user community in Telegram: https://t.me/divkit_community_ru