--- metadata: - name: generator content: Diplodoc Platform v5.50.3 alternate: - https://divkit.tech/docs/en/concepts/expressions.md - https://divkit.tech/docs/ru/concepts/expressions.md --- > **Documentation Index:** Fetch the complete configuration index at https://divkit.tech/docs/ru/llms.txt # Вычисляемые выражения ## Что такое вычисляемое выражение {#about} Практически любое свойство карточки с примитивным [типом](https://divkit.tech/docs/ru/concepts/variables.md#types) (строки, числа, логическое значение) может ссылаться на вычисляемое выражение. Вычисляемая часть выражения записывается с помощью конструкции `@{}` и может содержать [переменные](https://divkit.tech/docs/ru/concepts/variables.md), [операторы](#syntax) и функции. Список поддерживаемых функций см. в разделе [Встроенные функции](https://divkit.tech/docs/ru/concepts/functions.md). Например: - Выражение `"font_size": "@{common_text_size}"` означает, что свойство размера шрифта карточки будет вычисляться на основе значения переменной `common_text_size`. - Чтобы увеличить размер шрифта только для некоторых карточек относительно той же переменной `common_text_size`, выражение можно записать так: ```translate=no "font_size": "@{sum(common_text_size, extra_size}" ``` Теперь выражение с помощью встроенной функции `sum` будет складывать значения двух переменных. То же самое выражение можно записать и с помощью оператора `+`: ```translate=no "font_size": "@{common_text_size + extra_size}" ``` {% note alert "Ограничение" %} Выражения нельзя использовать в свойствах типов карточек, в id [состояний](https://divkit.tech/docs/ru/concepts/interaction.md), а так же в блоке объявления [переменных](https://divkit.tech/docs/ru/concepts/variables.md) `variables`. {% endnote %} ## Синтаксис вычисляемых выражений {#syntax} В вычисляемых выражениях поддерживаются конструкции: - Логические операторы: `==`, `!=`, `!`, `>`, `>=`, `<`, `<=`, `&&`, `||`. - Арифметические операторы: `+`, `-`, `*`, `/`, `%`. - Тернарный оператор: `counter > 0 ? true : 17`. - Оператор `!:`: `undefined_var !: fallback`. В случае, когда вычисление левой части не удалось, вычисляется правая. - Группировка логических выражений: `logging_enabled && (user_name == 'John' || user_email != '')`. - Вызов [функций](https://divkit.tech/docs/ru/concepts/functions.md): `mult(total_price, .83)`. - Использование вычисляемых частей внутри строк и вычисляемых выражений строчного типа: `"mail: @{'@{username}@ya.ru'}"` преобразуется в `mail: john@ya.ru`. ### Приоритет операторов {#operator-priority} Операторы вычисляются в следующем порядке приоритета (от высшего к низшему): 1. `!` (логическое отрицание) 2. `*`, `/`, `%` (умножение, деление, остаток от деления) 3. `+`, `-` (сложение, вычитание) 4. `>`, `>=`, `<`, `<=` (сравнение) 5. `!:` (оператор безопасного доступа/fallback) 6. `==`, `!=` (равенство, неравенство) 7. `&&` (логическое И) 8. `||` (логическое ИЛИ) 9. `? :` (тернарный оператор) #### Примеры приоритета оператора `!:` ```translate=no @{undefined_var !: true || false} → true @{undefined_var !: 8 > 4} → true @{undefined_var !: 8 + 4} → 12 @{undefined_var !: 8 + 4 > 2} → true ``` ## Шаблонные строки {#string_template} Строковые параметры, в отличие от остальных, могут содержать несколько вычисляемых частей, значения которых будут конвертироваться в строку и подставляться в указанные места. Например: ```translate=no "url": "https://marketplace.yandex.ru/profile/@{user_name}/orders/@{order_id}" ``` Внутри вычисляемого выражения можно использовать шаблонные строки, которые содержат постоянную часть и вложенные вычисляемые выражения: ```translate=no "url": "@{'https://marketplace.yandex.ru/profile/@{user_name}/orders/@{order_id}'}" ``` ## Как вычисляется значение выражения {#calculate} Значение вычисляемого выражения должно иметь тот же тип, что свойство карточки, в котором используется выражение. Поэтому при вычислении выражения может потребоваться дополнительная конвертация типов данных. **Вычисление в строковых параметрах** Допустим, значение параметра задано выражением: `"text": "@{sum(var_a, 50)}"`. Сначала будут вычислены значения аргументов функции `sum`, а затем будет вычислен результат этой функции. Первый аргумент является ссылкой на переменную, и для получения ее значения будет выполнен поиск переменной сначала в локальных переменных карточки, а затем в [общем контексте для нескольких карточек](https://divkit.tech/docs/ru/concepts/variables.md#global). Допустим, что `var_a` это целочисленная переменная со значением `25`. Полученное число будет сложено с другим аргументом, и результатом функции будет число `75`. Далее этот результат в соответствии с контекстом свойства `text` будет приведен к строке, и в верстке отобразится текст "75". **Сериализация словарей и массивов в строку** При преобразовании словарей и массивов в строку (например, с помощью функции `toString()` или интерполяции `@{dict}`) используется JSON-подобная сериализация с правильным экранированием специальных символов: - Кавычки `"` экранируются как `\"` - Обратные слеши `\` экранируются как `\\` - Специальные символы: `\b`, `\f`, `\n`, `\r`, `\t` - Слэши `/` экранируются как `\/` Пример: ```translate=no "text": "@{toString({'key': 'value with \"quotes\"'})}" ``` Результат: `{"key":"value with \"quotes\""}` **Вычисление в строковых параметрах, имеющих строгий формат** Значение цвета можно задать строкой определенного формата: `"text_color": "#@{str_var}"`. Для таких параметров строка преобразуется в тип параметра: результат вычисляемого выражения будет сначала приведен к строке, а затем переведен к типу параметра. **Вычисление в полях с числовыми значениями** Параметры числового типа, например `text_size`, не поддерживают конвертацию строк в числа. Поэтому в таких параметрах необходимо использовать вычисляемые выражения, результат которых совпадает с типом параметра. Например: - Некорректно: `"text_size": "10"`, `"text_size": "@{str_var}"`. - Корректно: `"text_size": "@{10}"`, `"text_size": "@{int_var}"`. **Вычисление некорректных выражений** Допустим, параметр `height` имеет числовой тип. Значение параметра задано с помощью выражения `@{toInteger('@{var_a}@{var_b}')}`, где используется [шаблонная строка](#string_template) с двумя переменными, результат вычисления которой будет преобразован в число с помощью [функции](https://divkit.tech/docs/ru/concepts/expressions.md) `toInteger`. Возможные ошибки при использовании такого выражения: 1. Переменные не существуют; 1. Функция `toInteger` не существует; 1. Функция не поддерживает аргумент типа `String`; 1. Возвращаемое функцией значение имеет некорректный тип или нарушает контракт, который ожидает поле `height`. Во всех вышеперечисленных ситуациях значение `height` не может быть вычислено корректно, и система попытается обойти ошибки в следующей последовательности: 1. Попытка вычислить выражение со значениями переменных по умолчанию (например, если значение переменной `var_a` изменилось с `1` на `one`, и функция `toInteger` перестала работать корректно); 1. Попытка переиспользовать последнее успешно вычисленное значение; 1. Если успешно вычисленного значения нет, то выражение примет значение параметра по умолчанию (в данном случае `0`). ## Типы данных в выражениях {#types} Если переменные используются в вычисляемых выражениях, то в зависимости от ситуации их значения могут приводиться к внутренним типам вычисляемых выражений. В каких ситуациях значение переменной преобразуется во внутренний тип: - Переменная используется внутри шаблонной строки. - Переменная сравнивается со значением внутреннего типа (выражение `@{subscribed == true}` вернет `true`). В каких ситуациях значение переменной **не преобразуется** во внутренний тип: - Выражение состоит только из ссылки на переменную: `"color": "@{color_var}"`. - Сравнение двух переменных одного типа: `@{color_var1 == color_var2}`. Пример: ```json translate=no { "variables": [ { "name": "is_delivered", "type": "boolean", "value": true }, { "name": "order_id", "type": "integer", "value": 17 }, { "name": "sum", "type": "number", "value": 381.3 } ], "states": [ ... { ... "text": "Order#@{order_id} delivered: @{is_delivered} total: @{sum}" } ... ] } ``` В этом примере выражения с переменными не строковых типов используются внутри строки. В этом случае значения переменных будут преобразованы в строки. Параметр `text` после вычисления значений переменных будет выглядеть так: `Order#17 delivered: true total: 381.3`. **Внутренние типы вычисляемых выражений** - `Integer`: целочисленный тип. Диапазон: `-9223372036854775808..9223372036854775807`. - `Number`: число с плавающей точкой. Диапазон: `4.9E-324..1.7976931348623157E308` (значения `Nan` и `Infinite` не поддерживаются). - `Boolean`: логический тип. Возможные значения: `true`, `false`. - `String`: строка. - `DateTime`: дата и время. - `Dict`: словарь (ассоциативный массив). - `Array`: массив. {% note info %} Функции работы с датами (например, `dateToString`) возвращают значения в локальном времени системы. Формат строки даты: `YYYY-MM-DD HH:MM:SS`. {% endnote %} **Правила приведения к внутренним типам** Значения переменных строковых и числовых типов преобразуются в аналогичные им внутренние типы. Для остальных переменных применяются такие правила: - тип `color` преобразуется в строку фиксированной длины формата `#ff001122`; - тип `url` преобразуется в аналогичную строку; - тип `dict` преобразуется в словарь `Dict`; - тип `array` преобразуется в массив `Array`. **Операции над типами** - Все значения одного типа можно проверять на равенство между собой (`==`, `!=`). - Для числовых типов и для типа `DateTime` доступны операции сравнения (`>`, `>=`, `<`, `<=`). - Числовые типы поддерживают все арифметические операторы, но следует помнить, что операции над разными типами будут приводить к ошибкам. Например, выражение `@{3.81 + 5}` не может быть вычислено. ## Узнать больше {#troubleshooting} Вы можете обсуждать интересующие вас темы в сообществе пользователей DivKit в Telegram: [https://t.me/divkit_community_ru](https://t.me/divkit_community_ru). [Репозиторий DivKit](https://github.com/divkit/divkit)