Миграция с Lumo на Aura

В Jmix 3 тема Aura используется по умолчанию в новых проектах, а тема Lumo по-прежнему поддерживается. После обновления приложения с Jmix 2 вы можете продолжить использовать Lumo или перейти на Aura.

Проще всего использовать новый проект Jmix 3 с темой Aura в качестве образца. Сгенерированные файлы этого проекта содержат правильную структуру темы и стили стандартных экранов.

Создание проекта-образца

Создайте пустой проект с той же версией Jmix, что и у обновленного приложения. Выберите тему Aura.

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

Копирование темы Aura

Скопируйте каталог темы Aura из проекта-образца в обновленное приложение:

src/main/resources/META-INF/resources/themes/<reference-project>-aura

Переименуйте скопированный каталог в <application-name>-aura. Внутри него:

  • Переименуйте <reference-project>.css в <application-name>.css.

  • Измените последний импорт в styles.css, указав новое имя файла.

Итоговый каталог должен выглядеть так:

src/main/resources/META-INF/resources/themes/<application-name>-aura
├── <application-name>.css
├── styles.css
└── view
    ├── login-view.css
    ├── main-view-top-menu.css
    └── main-view.css

Не изменяйте старую тему Lumo до завершения миграции: она понадобится как образец. Не копируйте сгенерированные стили экранов из старой темы Lumo поверх файлов Aura.

Подключение Aura

В основном классе приложения удалите аннотацию @Theme, а также импорты и аннотации таблиц стилей, относящиеся к теме Lumo.

Добавьте следующие импорты:

import com.vaadin.flow.component.dependency.StyleSheet;
import com.vaadin.flow.theme.aura.Aura;
import io.jmix.flowui.theme.aura.JmixAura;

Добавьте аннотации таблиц стилей Aura в указанном порядке:

@StyleSheet(Aura.STYLESHEET)
@StyleSheet(JmixAura.STYLESHEET)
@StyleSheet("themes/<application-name>-aura/styles.css")

Обновление стандартных экранов

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

Например, сгенерированный главный экран назначает класс jmix-main-view-app-layout компоненту appLayout, а класс jmix-initial-layout — компоненту initialLayout.

В старых главных экранах для расположения userMenu могут использоваться служебные классы Lumo:

<userMenu id="userMenu"
          themeNames="tertiary"
          classNames="ms-auto me-m">

Замените их классом из сгенерированных стилей главного экрана Aura:

<userMenu id="userMenu"
          themeNames="tertiary"
          classNames="jmix-main-view-user-menu">

Перенос пользовательских стилей

Перенесите CSS-правила приложения из старой темы в <application-name>.css. Также скопируйте изображения, шрифты и другие ресурсы, которые используют эти правила. Импорт CSS приложения должен оставаться последним в styles.css, чтобы его правила могли переопределять сгенерированные стили экранов.

Проверьте перенесенный код на следующие особенности Lumo:

Служебные классы Lumo

Aura не содержит служебных классов Lumo. Замените константы LumoUtility и имена служебных классов Lumo API компонентов, пользовательскими классами CSS или подходящими константами из io.jmix.flowui.theme.StyleUtility.

Пользовательские свойства CSS

Замените свойства --lumo- в соответствии с их назначением. Прямая замена существует не для каждого свойства Lumo. Если для настройки есть подходящее общее свойство --vaadin-, используйте его. Для настроек всей темы используйте свойства Aura.

Настройка Свойство Aura

Основной цвет

--aura-accent-color-light и --aura-accent-color-dark

Фон приложения

--aura-background-color-light и --aura-background-color-dark

Семейство и размер шрифта

--aura-font-family и --aura-base-font-size

Радиус границы

--aura-base-radius

Плотность компонентов

--aura-base-size

Полный список свойств см. в справочнике темы Aura.

Настройки компонентов

Проверьте варианты темы и Java-константы с префиксом LUMO_. Перенесите правила из старого каталога components в таблицу стилей приложения, поскольку Vaadin 25 больше не добавляет их по умолчанию. См. Стилизация компонентов UI.

Стили для светлой и темной схем

Замените пользовательские цвета свойствами цветов Aura или функцией CSS light-dark(). Селектор наподобие html[theme~='dark'] не охватывает системные режимы LIGHT_DARK и DARK_LIGHT. См. CSS для цветовых схем.

Пересборка и проверка

Перед пересборкой frontend-бандла очистите сгенерированные frontend-файлы и результаты предыдущей сборки:

./gradlew clean vaadinClean

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

Для развертывания JAR проверьте production-сборку:

./gradlew -Pvaadin.productionMode=true bootJar

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

Удаление старой темы

После проверки приложения в режимах разработки и production удалите каталог старой темы Lumo.