.. _interface_themes: Настройка темы интерфейса ============================ .. contents:: :depth: 3 **Тема интерфейса** — набор логотипов, favicon и CSS-стилей для визуальной кастомизации Citeck под фирменный стиль организации. Тема представляет собой zip-архив, который загружается через интерфейс или API и применяется ко всему приложению. Статья описывает формат и структуру архива темы, порядок загрузки и применения, API для работы со стилями и изображениями, механизм кэширования, а также примеры CSS-настроек. Основной источник данных: **uiserv/theme** Просмотр существующих тем, их редактирование, применение, загрузка новых осуществляется в журнале **Темы (Рабочее пространство "Раздел администратора" - Конфигурация UI)**. Журнал доступен по адресу: ``/v2/journals?journalId=ecos-theme&viewMode=table&ws=admin$workspace`` .. image:: _static/themes/theme_1.png :width: 700 :align: center Доступные операции с темами: загрузка новой темы **(1)**, скачивание **(2)**, удаление существующей **(3)**, применение темы **(4)**. Действие **Применить тему** доступно для неактивных тем, для текущей темы действие не отображается. Через интерфейс на данный момент не предусмотрена настройка темы — только через скачивание, изменение и загрузку обратно. При загрузке темы через интерфейс **zip-архив** загружается в **uiserv**. Структура архива: .. code-block:: root: theme: image: apple-touch-icon.png apple-touch-icon-precomposed.png favicon.ico login-logo.png logo.png menu-left-logo-large.png menu-left-logo-small.png meta.json main.css где: * **root** — корень архива * **theme** — идентификатор темы * **image** — произвольная папка для изображений. Связь между реальным файлом и его идентификатором осуществляется в meta.json * **meta.json** — метаданные темы * **main.css** — главный файл со стилями Общий вид **meta.json**:: { "name": { "ru": "Тема ECOS", "en": "ECOS theme" }, "parentRef": null, "images": { "favicon": "/image/favicon.ico", "logo": "/image/logo.svg", "login-logo": "/image/login-logo.svg", "menu-left-logo-large": "/image/menu-left-logo-large.svg", "menu-left-logo-small": "/image/menu-left-logo-small.svg", "apple-touch-icon": "/image/apple-touch-icon.png", "apple-touch-icon-precomposed": "/image/apple-touch-icon-precomposed.png" } } * **name** — имя темы. Справочная информация; * **images** — ссылки на изображения: * **favicon** — значок для сайта. Поддерживается только ICO формат * **logo** — логотип темы. Будет использоваться при выборе темы * **login-logo** — логотип на странице логина * **menu-left-logo-large** — логотип в левом развернутом меню * **menu-left-logo-small** — логотип в левом свернутом меню * **apple-touch-icon** — логотип, используемый iOS для закладок и сайтов «на домашнем экране» * **apple-touch-icon-precomposed** — логотип, используемый в ранних версиях iOS для закладок и сайтов «на домашнем экране» Поддерживаемые форматы логотипов: **jpeg**, **ico**, **png** (в предстоящем релизе добавлен **svg**). Размер логотипа не лимитирован. Кроме логотипов можно менять стили в файле **main.css**. Через этот файл можно изменить практически любую часть UI, но в общем случае предполагается, что автор изменений хорошо знает, как работать со стилями в браузере. На данный момент сервер никак не обрабатывает стили. Т. е. в архиве желательно грузить сразу минифицированные стили. Помимо **main.css** могут быть и другие стили и к ним можно получить доступ по API. В будущем если файл main.css будет отсутствовать, то сервер сгенерирует его из всех css файлов в теме. Конфигурация active-theme ---------------------------- Для хранения текущей темы используется конфигурация в uiserv **active-theme** Для получения текущей темы:: await Records.get('uiserv/config@active-theme').load('value'); Информация об активной теме доступна в журнале **Конфигурация ECOS** (`v2/journals?journalId=ecos-configs&viewMode=table&ws=admin$workspace`) в **active-theme**: .. image:: _static/themes/theme_2.png :width: 700 :align: center Для изменения темы укажите ее новое значение в настройке и сохраните: .. image:: _static/themes/theme_3.png :width: 400 :align: center API ---- Получение основного файла стилей для темы:: /gateway/uiserv/api/theme/{themeId}/style/main.css Расширение .css можно не указывать. Вместо main.css могут быть и другие стили, которые есть в теме (учитывается только имя файла без пути до него). Получение изображений:: /gateway/uiserv/api/theme/{themeId}/image/logo Вместо logo должен быть идентификатор изображения из meta.json темы (images) Вместо {themeId} могут быть: 1. Реальный идентификатор темы 2. Константа “active“, с которой идентификатор темы загружается из конфига **active-theme** Кэш --- Все запросы за стилями и изображениями возвращают заголовки кэширования с временем жизни ~4 часа. Чтобы избежать проблем с кэшем (темы могут меняться "на лету") нужно добавлять в запросы ключ кэширования, который загружается по следующему API:: await Records.get('uiserv/meta@').load('attributes.theme-cache-key'); Стили ------- В активную тему можно добавить кастомный css. Для этого: 1. Скачайте артефакт готовой темы: .. image:: _static/themes/css/custom_01.png :width: 700 :align: center 2. Распакуйте архив: .. image:: _static/themes/css/custom_02.png :width: 400 :align: center 3. Откройте **main.css** .. code-block:: .body { } 4. Внесите в него изменения. 5. Упакуйте в архив (с такой же структурой как был выгружен) и загрузите на стенд: .. image:: _static/themes/css/custom_03.png :width: 700 :align: center 6. Обновите страницу. Настройка ширины выпадающего списка у кнопки Создать ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Например, для настройки ширины выпадающего списка у кнопки Создать: .. code-block:: css .body { } .ecos-dropdown__menu_new, .ecos-dropdown__menu_new ul { max-width: unset !important; } Результат: перейдите к кнопке Создать, ширина выпадающего списка будет подстраиваться под длину текста: .. image:: _static/themes/css/custom_04.png :width: 600 :align: center Изменение цветовой гаммы темы ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: css :root { --main-bg-color: #fafafa; /*основной фон страницы*/ --header-bg-color: #002F6C; /*основной фон хедера страницы*/ --header-component-color: #1e4272dd; /*цвет элементов хедера*/ --primary-color: #002F6C; /*основной цвет темы*/ --dark-primary-color: #002350; /*производная от основного цвета*/ --light-primary-color: #D8E5F8; /*производная от основного цвета*/ } body { } .ecos-sidebar { background: #f8fafc; /*фон боковой панели*/ } .ecos-journal_new .ecos-grid__row_new:not(.ecos-grid__tr_selected):nth-child(odd) { background-color: #d8e5f86b !important; /*чередование строк в таблице*/ } Результат: .. list-table:: :widths: 5 30 :align: center * - Базовая тема: - .. image:: _static/themes/css/custom_05.png :width: 700 :align: center * - Обновленная тема: - .. image:: _static/themes/css/custom_06.png :width: 700 :align: center