Использование

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

Возможности

Механизмы темизации позволяют:

• Переопределять цветовые параметры ВСЕХ компонентов системы
• Переопределять определенные графические элементы системы:
  • Логотипы
  • Фоновые изображения
  • Favicon
  • Флаги локализации
  • Графические элементы дерева

Термины

• Схема темизации — набор правил, определяющих параметры и структуру темы приложения
• Стандартная тема — тема по умолчанию, содержит базовый набор параметров оформления системы
• Пользовательская тема — набор параметров, переопределяющих параметры стандартной темы

Структура темы

Тема представляет собой файл в формате JSON. Файл темы должен содержать набор конфигурационных параметров, строго соответствующий требуемой структуре — схеме темизации.

По своей структуре тема состоит из следующих узловых элементов:

• Группа — объединяет другие группы и/или параметры по общему смыслу.
• Параметр темы — конечное значение. Может быть двух видов:
  • Цвет. Строка в формате HEX8 (с альфа-каналом) или ссылка на другой параметр темы.
  • URL. Строка URL-адреса (В том числе допускается Data URL) или ссылка на другой параметр темы.

Настройка пользовательской темы

В качестве примера настройки пользовательской темы зададим параметры:

• general.palette.danger.500 — цветовое значение #FF0000FF
• platform.uikit.button.standard.default.normal.backgroundColor — ссылка на заданный нами цвет из палитры
• platform.app.favicon.iconUrl - значение для иконки в формате Data URL

Для этого необходимо создать файл theme.json со следующей структурой:

{
  "theme": {
    "general": {
      "palette": {
        "danger": {
          "500": {
            "type": "literal",
            "value": "#FF0000FF"
          }
        }
      }
    },
    "platform": {
      "uikit": {
        "button": {
          "standard": {
            "default": {
              "normal": {
                "backgroundColor": {
                  "type": "link",
                  "path": "general.palette.danger.500"
                }
              }
            }
          }  
        }    
      },
      "app": {
        "favicon": {
          "iconUrl": {
            "type": "literal",
            "value": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIj8+PHN2ZyB2aWV3Qm94PSIwIDAgNjQgNjQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGNpcmNsZSBjeD0iMzIiIGN5PSIzMiIgcj0iMzIiIGZpbGw9InJlZCIvPjwvc3ZnPgo="
          }
        }
      }        
    }
  }
}
Копировать

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

Установка пользовательской темы

JSON-файл с пользовательской темой необходимо смонтировать в корневую публичную директорию UI-сервиса. Для Docker-контейнера это путь: /usr/share/nginx/html/theme.json:

docker run repository.universe-data.ru/dis/unidata-dg/frontend:v2.15.0 \
   -p '80:80' \
   -v ./theme.json:/usr/share/nginx/html/theme.json
   -e BACKEND_ADDRESS=$BACKEND_ADDRESS 
Копировать

При запуске системы пользовательская тема будет применена.

Использование параметров темизации

При реализации кастомизаций возможно использовать параметры темизации в пользовательских CSS-файлах. Все параметры темизации хранятся в CSS-переменных именуемых согласно формату: --un-theme-<parameter-id>, где <parameter-id> - это путь к параметру, с разделителем -. Например, значение для параметра general.palette.danger.500 хранится в css-переменной --un-theme-general-palette-danger-500:

.custom-class {
  background-color: var(--un-theme-general-palette-danger-500);
}
Копировать