Стилизация компонентов UI

Компоненты Vaadin и Jmix можно стилизовать несколькими способами. Начинайте с подхода самого высокого уровня и добавляйте пользовательский CSS только при необходимости.

Используйте следующий порядок:

Настройте тему приложения.
Используйте встроенный вариант темы компонента.
Примените пользовательский CSS к компонентам.
Измените стили в Java.

Тема приложения

Наиболее согласованный способ стилизовать приложение и его составные части — настроить тему. Vaadin предоставляет визуальный редактор тем для Aura и Lumo.

См. Настройка Aura и Настройка Lumo.

Варианты темы компонентов

LIVE DEMO

Многие компоненты содержат встроенные варианты темы, которые изменяют цвет, размер или другие свойства внешнего вида. Применяйте варианты темы компонентов с помощью XML-атрибута themeNames или Java API, например addThemeVariants() и addThemeNames().

<hbox>
    <button text="Primary" themeNames="primary"/>
    <button text="Success" themeNames="success"/>
    <button text="Tertiary" themeNames="tertiary"/>
</hbox>

Figure 1. Кнопки с примененными вариантами темы

Aura и Lumo поддерживают разные варианты темы компонентов. На страницах справочника компонентов указано, поддерживает ли вариант Aura, Lumo или обе темы.

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

Встроенный вариант темы компонента можно переопределить CSS-правилом, которое обращается к его значению в атрибуте theme:

my-project.css

vaadin-button[theme~="primary"] {
    background-color: purple;
}

Применение CSS к компонентам

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

Стилизация всех экземпляров компонента

Компоненты Vaadin предоставляют пользовательские CSS-свойства с префиксом --vaadin-. Vaadin называет их свойствами стилей компонентов. Это основной API для изменения стилей компонентов.

Задайте свойство стиля компонента для элемента html, чтобы изменить все экземпляры, которые его используют. Чтобы ограничить общее свойство типом компонента, используйте селектор компонента:

my-project.css

html {
    --vaadin-button-border-radius: 1em;
}

vaadin-text-field {
    --vaadin-input-field-border-radius: 2em;
}

Стилизация отдельных экземпляров компонента

Используйте XML-атрибут classNames или Java-метод addClassName(), чтобы применить CSS-класс к выбранным экземплярам компонента:

<textField classNames="wide"/>

my-project.css

vaadin-text-field.wide {
    width: 24em;
}

Также можно ограничить правила компонентами внутри родительского элемента с пользовательским классом:

my-project.css

.button-row vaadin-button {
    flex: 1;
}

Части компонентов

Компоненты Vaadin и Jmix сложнее нативных HTML-элементов. Многие внутренние элементы находятся в Shadow DOM, который предотвращает случайное изменение внутренних элементов глобальным CSS.

Figure 2. Структура HTML-элемента компонента

Корневые элементы

У каждого компонента есть корневой HTML-элемент, имя которого обычно начинается с vaadin- или jmix-, например vaadin-button или jmix-value-picker.

my-project.css

jmix-value-picker {
    margin-block: 1em;
}

Теневые части

Теневые (shadow) части — элементы внутри Shadow DOM компонента. Используйте селектор ::part(). Например, часть input-field изменяет поверхность ввода текстового поля:

my-project.css

vaadin-text-field::part(input-field) {
    background: white;
    border: 1px solid black;
}

Figure 3. Текстовое поле с пользовательским фоном и границей

Все теневые части, предоставляемые компонентом, перечислены в разделе CSS-селекторы Text Field.

Обычные дочерние элементы

Обычные дочерние элементы находятся вне Shadow DOM компонента. Используйте селектор >, чтобы выбрать непосредственный дочерний элемент. Например, следующее правило выбирает значки внутри кнопок:

my-project.css

vaadin-button > vaadin-icon {
    color: blue;
}

CSS-селекторы, поддерживаемые компонентом, перечислены в разделе CSS-селекторы Button.

Состояния компонентов

Компоненты предоставляют состояния, например disabled, read-only, invalid и focused. Большинство состояний доступны как атрибуты корневого элемента компонента. Селекторы атрибутов состояния можно сочетать с селекторами частей:

my-project.css

vaadin-text-field[readonly]::part(input-field) {
    border-color: gray;
}

Нативные состояния, например hover, используют CSS-псевдоклассы. Их можно сочетать с предоставляемыми псевдоэлементами. Например, Button предоставляет псевдоэлемент ::before для подсветки при наведении:

my-project.css

vaadin-button:hover::before {
    background-color: blue;
}

Изменение стилей в Java

Используйте API Style компонента, чтобы задавать встроенные CSS-свойства из Java:

@ViewComponent
private JmixButton myBtn;

@Subscribe
public void onInit(final InitEvent event) {
    myBtn.getStyle().set("color", "white");
    myBtn.getStyle().set("background-color", "purple");
}

Встроенные стили применяются только к корневому элементу компонента. Они не могут напрямую обращаться к частям компонента или применяться в зависимости от состояний.

Другой вариант — пользовательские CSS-свойства. Это могут быть встроенные свойства стилей компонентов или темы либо свойства, определенные приложением. Используйте их в CSS-правилах и задавайте значения из Java:

my-project.css

html {
    --my-button-text-color: darkblue;
    --my-button-bg-color: yellow;
}

vaadin-button.my-button {
    color: var(--my-button-text-color);
    background-color: var(--my-button-bg-color);
}

XML-дескриптор экрана

<button id="myBtn"
        text="Button"
        classNames="my-button"/>

@Subscribe
public void onInit(final InitEvent event) {
    UI.getCurrent().getElement().getStyle()
            .set("--my-button-text-color", "white");
    UI.getCurrent().getElement().getStyle()
            .set("--my-button-bg-color", "purple");
}

CSS-правило остается в таблице стилей приложения, поэтому оно может обращаться к частям и состояниям компонентов. Одно пользовательское свойство также может использоваться несколькими правилами.