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

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

Примечание

В Web хранимые значения работают, только если в функцию render передано внешнее хранилище в параметре store, см. Параметры функции render. Без него действие set_stored_value завершается ошибкой.

Области видимости хранимых значений

Хранимые значения поддерживают разные области видимости:

  • global — значения доступны во всех карточках приложения
  • card — значения доступны только в текущей карточке

Если область видимости не указана, используется global.

Действие set_stored_value

Для сохранения значений используется типизированное действие set_stored_value:

{
  "log_id": "save_theme",
  "typed": {
    "type": "set_stored_value",
    "name": "user_theme",
    "value": {
      "type": "string",
      "value": "dark"
    },
    "lifetime": 86400,
    "scope": "global"
  }
}

Параметры действия:

  • name — имя хранимого значения. Обязательный параметр.
  • value — типизированное значение: объект с полями type (string, integer, number, boolean, color, url, array, dict) и value. Обязательный параметр.
  • lifetime — время жизни значения в секундах. Обязательный параметр.
  • scope — область видимости: global или card.

То же действие в формате url:

div-action://set_stored_value?name=<name>&value=<value>&type=<type>&lifetime=<lifetime_in_sec>&scope=<global|card>

Параметр

Описание

name

Имя хранимого значения. Обязательный параметр.

value

Значение, которое будет сохранено. Обязательный параметр.

type

Тип значения: string, integer, number, boolean, color, url, array или dict. Обязательный параметр.

lifetime

Время жизни значения в секундах. По истечении этого времени значение считается устаревшим. Обязательный параметр.

scope

Область видимости: global или card. Необязательный параметр.

Функции для чтения хранимых значений

Для чтения хранимых значений используются функции вида getStored<Тип>Value:

  • getStoredStringValue(name, fallback) — чтение строкового значения; fallback возвращается, если значение не найдено;
  • getStoredStringValue(name, scope, fallback) — чтение из указанной области видимости ('global' или 'card');
  • getStoredArrayValue(name), getStoredArrayValue(name, scope), getStoredDictValue(name), getStoredDictValue(name, scope) — чтение массива и словаря. У этих функций нет fallback: если значение не найдено, вычисление выражения завершится ошибкой.

Аналогичные функции есть для типов integer, number, boolean, color и url.

Полный список функций с сигнатурами — на странице Встроенные функции.

Пример использования хранимых значений
{
  "log_id": "stored_values_example",
  "variables": [
    {
      "name": "theme",
      "type": "string",
      "value": "@{getStoredStringValue('user_theme', 'light')}"
    }
  ],
  "states": [
    {
      "state_id": 0,
      "div": {
        "type": "container",
        "items": [
          {
            "type": "text",
            "text": "Текущая тема: @{theme}",
            "actions": [
              {
                "log_id": "switch_theme",
                "typed": {
                  "type": "set_stored_value",
                  "name": "user_theme",
                  "value": {
                    "type": "string",
                    "value": "@{theme == 'light' ? 'dark' : 'light'}"
                  },
                  "lifetime": 2592000,
                  "scope": "global"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Пример с различными областями видимости
{
  "log_id": "stored_values_scopes",
  "variables": [
    {
      "name": "global_setting",
      "type": "string",
      "value": "@{getStoredStringValue('global_setting', 'global', 'default_value')}"
    },
    {
      "name": "card_setting",
      "type": "string",
      "value": "@{getStoredStringValue('card_setting', 'card', 'card_default')}"
    }
  ],
  "states": [
    {
      "state_id": 0,
      "div": {
        "type": "container",
        "items": [
          {
            "type": "text",
            "text": "Глобальная настройка: @{global_setting}",
            "actions": [
              {
                "log_id": "set_global",
                "typed": {
                  "type": "set_stored_value",
                  "name": "global_setting",
                  "value": {
                    "type": "string",
                    "value": "new_global_value"
                  },
                  "lifetime": 2592000,
                  "scope": "global"
                }
              }
            ]
          },
          {
            "type": "text",
            "text": "Настройка карточки: @{card_setting}",
            "actions": [
              {
                "log_id": "set_card",
                "typed": {
                  "type": "set_stored_value",
                  "name": "card_setting",
                  "value": {
                    "type": "string",
                    "value": "new_card_value"
                  },
                  "lifetime": 2592000,
                  "scope": "card"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

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

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

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

Предыдущая
Триггеры
Следующая
Вычисляемые выражения