Переменные

Чтобы использовать переменные, объявите их в отдельном блоке variables. При объявлении переменной укажите параметры:

• name — имя, может состоять из латинских букв разных регистров, цифр и символов _ и .. Не может начинаться с цифры или с точки.
• type — тип переменной. См. Типы данных.
• value — значение по умолчанию.

Например:

{
    "variables": [
        {
            "name": "subscribed",
            "type": "boolean",
            "value": true
        }
    ],
}

Типы данных

Поддерживаемые типы данных:

• логический: boolean
• строковый: string
• целочисленный: integer
• число с плавающей точкой: number
• цвет: color
• ссылка на ресурс: url (должен быть корректным URL)
• словарь: dict
• массив: array
• свойство: property, см. Свойства

{
    "variables": [
        {
            "name": "subscribed",
            "type": "boolean",
            "value": true
        },
        {
            "name": "likes",
            "type": "integer",
            "value": 0
        },
        {
            "name": "black",
            "type": "color",
            "value": "#f000"
        },
        {
            "name": "username",
            "type": "string",
            "value": "unknown"
        }
    ],
    "states": [ ... ]
}

Выражения при инициализации переменных

Переменные поддерживают выражения в значениях инициализации. Это позволяет ссылаться на другие переменные или использовать функции при определении начального значения переменной. Выражение вычисляется один раз в момент инициализации переменной. Порядок объявления имеет значение — переменная может ссылаться только на переменные, которые были объявлены до неё.

{
  "variables": [
    {
      "name": "margin",
      "type": "integer",
      "value": 8
    },
    {
      "name": "padding",
      "type": "integer",
      "value": "@{margin * 2}"
    },
    {
      "name": "total_spacing",
      "type": "integer",
      "value": "@{margin + padding}"
    }
  ]
}

Словари

В качестве переменной можно объявлять словари — произвольные JSON-объекты, внутри которых могут храниться любые другие типы переменных.
Например, их удобно использовать для объявления палитры и получать из нее значения в зависимости от темы приложения:

"variables": [
  {
    "name": "palette",
    "type": "dict",
    "value": {
      "light": {
        "text_color": "#ffffff",
        "text_background": "#0077FF"
      },
      "dark": {
        "text_color": "#000000",
        "text_background": "#0077FF"
      },
      "big": {
        "text_size": 20
      },
      "small": {
        "text_size": 16
      }
    }
  },
  {
    "name": "app_theme",
    "type": "string",
    "value": "light"
  },
  {
    "name": "font_size",
    "type": "string",
    "value": "small"
  }
]

Словарь не может самостоятельно определять типы, поэтому нужно правильно выбирать функции для того, чтобы получить переменную из словаря:

getIntegerFromDict(dict_name, path_to_value)
getNumberFromDict(dict_name, path_to_value)
getStringFromDict(dict_name, path_to_value)
getColorFromDict(dict_name, path_to_value)
getUrlFromDict(dict_name, path_to_value)
getBooleanFromDict(dict_name, path_to_value)
getOptIntegerFromDict(fallback, dict_name, path_to_value)
getOptNumberFromDict(fallback, dict_name, path_to_value)
getOptStringFromDict(fallback, dict_name, path_to_value)
getOptColorFromDict(fallback, dict_name, path_to_value)
getOptUrlFromDict(fallback, dict_name, path_to_value)
getOptBooleanFromDict(fallback, dict_name, path_to_value)

В объявленном словаре из примера значения цветов и размера шрифта можно использовать так:

"background": [
  {
    "type": "solid",
    "color": "@{getColorFromDict(palette, app_theme, 'text_background')}"
  }
],
"font_size": "@{getIntegerFromDict(palette, font_size, 'text_size')}",
"text_color": "@{getColorFromDict(palette, app_theme, 'text_color')}"

Массивы

Массивы содержат произвольные JSON-объекты.

"variables": [
  {
    "type": "array",
    "name": "array",
    "value": [
      "string",
       123,
      "@{expression}"
    ]
  }
]

Массив, как и словарь, не может автоматически определять типы переменных, которые хранятся внутри него, поэтому нужно правильно выбирать функции для того, чтобы получить значение из массива:

getIntegerFromArray(array, index)
getNumberFromArray(array, index)
getStringFromArray(array, index)
getColorFromArray(array, index)
getUrlFromArray(array, index)
getBooleanFromArray(array, index)
getArrayFromArray(array, index)
getDictFromArray(array, index)
getOptIntegerFromArray(array, index, fallback)
getOptNumberFromArray(array, index, fallback)
getOptStringFromArray(array, index, fallback)
getOptColorFromArray(array, index, fallback)
getOptUrlFromArray(array, index, fallback)
getOptBooleanFromArray(array, index, fallback)
getOptArrayFromArray(array, index, fallback)
getOptDictFromArray(array, index, fallback)

len(array)

Если тип функции выбран неправильно или произошел выход за границы массива, возникнет ошибка. В этом случае можно использовать функцию getOpt* вместо get*, тогда вместо ошибки возвратится fallback значение.

Методы

Для работы с массивами и словарями удобно применять методы. В отличие от функций, они вызываются непосредственно из массива или словаря и возвращают требуемое значение.

Доступные методы

Полные описания полей методов и примеры использования доступны в репозитории DivKit:

• toString: поля, примеры;

• методы для массивов: поля, примеры;

• методы для словарей: поля, примеры.

Свойства

Переменная с типом property не хранит значение сама. При чтении вычисляется выражение из get, а при изменении значения выполняются действия из set.

• value_type — тип возвращаемого значения свойства. Обязательный параметр.
• get — значение свойства. Поддерживает выражения. Обязательный параметр.
• set — действия, которые выполняются при установке значения свойства.
• new_value_variable_name — имя, по которому в действиях set доступно новое значение. По умолчанию — new_value.

{
  "variables": [
    {
      "name": "source",
      "type": "dict",
      "value": {
        "color_key": "#AABBCC"
      }
    },
    {
      "name": "color_prop",
      "type": "property",
      "value_type": "color",
      "get": "@{getColorFromDict(source, 'color_key')}",
      "set": [
        {
          "log_id": "set_action_color",
          "typed": {
            "type": "dict_set_value",
            "variable_name": "source",
            "key": "color_key",
            "value": {
              "type": "string",
              "value": "@{new_value}"
            }
          }
        }
      ]
    }
  ]
}

Изменение значений переменных

Для изменения значения переменной доступно действиеset_variable. Например:

div-action://set_variable?name=common_text_size&value=17

Чтобы задать значение переменной, можно использовать вычисляемые выражения и встроенные функции.

div-action://set_variable?name=result&value=@{local_value}

Примеры:

• изменить значение переменной с плавающей точкой:

  div-action://set_variable?name=price&value=3.889
  

• изменить значение логической переменной:

  • значение true: div-action://set_variable?name=is_liked&value=1 или div-action://set_variable?name=is_liked&value=true
  • значение false: div-action://set_variable?name=is_liked&value=0 или div-action://set_variable?name=is_liked&value=false

• изменить значение переменной типа color на зеленый цвет:

  div-action://set_variable?name=color_variable&value=@{encodeUri('#ff00ff00')}
  

• Установка словарных переменных с выражениями:

  div-action://set_variable?name=result_dict&value=@{source_dict}
  

  Или с использованием типизированного формата:

  {
    "type": "set_variable",
    "variable_name": "result_dict",
    "value": {
      "type": "dict",
      "value": "@{source_dict}"
    }
  }
  

  Примечание

  Выражение словаря должно возвращать валидное значение словаря, соответствующее типу целевой переменной.

• Установка словарных переменных из объектов JSON:

  Словарные переменные можно обновлять с помощью типизированных действий, передавая значение словаря напрямую:

  {
    "log_id": "set_palette",
    "typed": {
      "type": "set_variable",
      "variable_name": "palette",
      "value": {
        "type": "dict",
        "value": {
          "light": {
            "text_color": "#e0bae3"
          }
        }
      }
    }
  }
  
  Пример с URL-кодированием

  Словарные переменные также можно обновлять, предоставляя правильно URL-кодированное строковое представление JSON:

  div-action://set_variable?name=palette&value=%7B%22light%22%3A%7B%22text_color%22%3A%22%23e0bae3%22%7D%7D
  

  Это соответствует следующей структуре JSON:

  {
    "light": {
      "text_color": "#e0bae3"
    }
  }
  

Внешние переменные

Переменные, которые объявляются в верстке, являются переменными уровня карточки и недоступны извне. Для совместного использования переменных между разными верстками нужно использовать внешние переменные.

Для этого объявите DivVariableController на клиенте и передайте в него переменные, к которым нужно обращаться из верстки.

val variableController = DivVariableController()
val configuration = DivConfiguration.Builder(imageLoader)
    .divVariableController(variableController)
    .build()

val theme = Variable.StringVariable("app_theme", "light")
variableController.putOrUpdate(theme)

let applicationStorage = DivVariableStorage()
let variablesStorage = DivVariablesStorage(outerStorage: applicationStorage)
let divkitComponents = DivKitComponents(variablesStorage: variablesStorage)

let themeVariable: DivVariables = [
  DivVariableName(rawValue: "palette"): .dict([
    "text_color": "#ffffff",
    "text_background": "#0077FF"
  ])
]
applicationStorage.put(themeVariable)

import {createVariable, createGlobalVariablesController} from '@divkitframework/divkit';

const controller = createGlobalVariablesController();

const palette = createVariable('palette', 'dict', {
  "text_color": "#ffffff",
  "text_background": "#0077FF"
});
controller.setVariable(palette);

Переменные уровня элемента

Переменные уровня элемента объявляются в верстке внутри элемента, который они характеризуют.

Переменные для отслеживания состояния элементов

Некоторые элементы DivKit предоставляют специальные переменные для отслеживания своего состояния. Например, элемент div-pager позволяет отслеживать количество видимых элементов через переменную:

Отслеживание количества элементов в пейджере

Элемент div-pager поддерживает свойство item_count_variable, которое позволяет задать имя переменной для хранения количества видимых элементов пейджера.

{
  "type": "pager",
  "item_count_variable": "pager_item_count",
  "items": [
    {
      "type": "text",
      "text": "Страница 1"
    },
    {
      "type": "text",
      "text": "Страница 2"
    }
  ]
}

Значение переменной обновляется динамически при:

• Изменении количества элементов в пейджере
• Изменении видимости отдельных элементов
• Добавлении или удалении элементов

Это полезно для создания индикаторов прогресса, отображения общего количества страниц или условного показа элементов интерфейса:

{
  "log_id": "pager_item_count_example",
  "variables": [
    {
      "name": "pager_item_count",
      "type": "integer",
      "value": 0
    }
  ],
  "states": [
    {
      "state_id": 0,
      "div": {
        "type": "container",
        "items": [
          {
            "type": "text",
            "text": "Всего страниц: @{pager_item_count}"
          },
          {
            "type": "pager",
            "item_count_variable": "pager_item_count",
            "items": [
              {
                "type": "text",
                "text": "Страница 1"
              },
              {
                "type": "text",
                "text": "Страница 2"
              },
              {
                "type": "text",
                "text": "Страница 3"
              }
            ]
          }
        ]
      }
    }
  ]
}

Хранимые значения

Значения, которые сохраняются на устройстве и доступны после перезапуска приложения, описаны на странице Хранимые значения.

Триггеры

Выполнение действий при изменении значений переменных описано на странице Триггеры.

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

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

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