创建 Web 组件

在线示例

可以完全从头创建自定义的 Web 组件， 也可以通过扩展已有的 Vaadin web 组件实现。 在实现了客户端侧的组件后，可以为其创建 Java API。

下面的示例展示通过扩展 Vaadin 按钮并 基于 Lit 如何创建明暗主题切换的开关。

创建 JavaScript Web 组件

在 frontend/src/component/theme-toggle 文件夹创建 theme-toggle.js 文件。其中包含一个 Web 组件，实现了明暗主题切换的开关。

import {html} from 'lit';
import {Button} from '@vaadin/button';
import {defineCustomElement} from '@vaadin/component-base/src/define.js';

export class ThemeToggle extends Button { (1)

    static get is() {
        return 'theme-toggle'; (2)
    }

    static get template() { (3)
        return html`
            <div class="vaadin-button-container">
                <span part="prefix" aria-hidden="true">
                    <slot name="prefix"></slot>
                </span>
                <span part="label">
                    <slot></slot>
                </span>
            </div>

            <slot name="tooltip"></slot>
        `;
    }

    static get properties() { (4)
        return {
            ariaLabel: {
                type: String,
                value: 'Theme toggle',
                reflectToAttribute: true,
            },
            storageKey: {
                type: String,
                value: 'jmix.flowui.theme',
                observer: '_onStorageKeyChanged'
            }
        };
    }

    constructor() {
        super();

        this.addEventListener('click', () => this.toggleTheme());
        this.addEventListener('click', () => {
            const customEvent = new CustomEvent('theme-changed', {detail: {value: this.getCurrentTheme()}});
            this.dispatchEvent(customEvent); (5)
        });
    }

    /** @protected */
    ready() {
        super.ready();
        this.applyStorageTheme();
    }

    applyStorageTheme() {
        let storageTheme = this.getStorageTheme();
        let currentTheme = this.getCurrentTheme();
        if (storageTheme && currentTheme !== storageTheme) {
            this.applyTheme(storageTheme);
        }
    }

    getStorageTheme() {
        return localStorage.getItem(this.storageKey);
    }

    getCurrentTheme() {
        return document.documentElement.getAttribute('theme');
    }

    toggleTheme() {
        const theme = this.getCurrentTheme();
        this.applyTheme(theme === 'dark' ? '' : 'dark');
    }

    applyTheme(theme) {
        document.documentElement.setAttribute('theme', theme);
        localStorage.setItem(this.storageKey, theme);
    }

    /** @protected */
    _onStorageKeyChanged(storageKey, oldStorageKey) {
        const theme = localStorage.getItem(oldStorageKey);
        localStorage.removeItem(oldStorageKey);

        if (theme) {
            localStorage.setItem(storageKey, theme);
        }
    }
}

defineCustomElement(ThemeToggle); (6)
1 扩展 Vaadin 的组件，重用按钮的行为和样式。
2 定义 HTML 元素的名称。
3 定义了 Shadow DOM 模板，包括图标、文本和工具提示的槽位。
4 定义客户端属性，包括保存所选主题的本地存储键值。
5 在切换主题后发送 theme-changed 事件。
6 导出自定义 HTML 元素，名称在 static get is() 方法中定义。

为 Web 组件创建 Java API

创建 ThemeToggle.java 文件，这是一个 UI 组件类。为服务端代码、访问方法、事件监听器和数据源连接定义了 API。

import com.vaadin.flow.component.*;
import com.vaadin.flow.component.dependency.JsModule;
import com.vaadin.flow.component.icon.Icon;
import com.vaadin.flow.component.icon.VaadinIcon;
import com.vaadin.flow.component.shared.HasTooltip;
import com.vaadin.flow.dom.Element;
import com.vaadin.flow.shared.Registration;
import io.jmix.flowui.kit.component.HasTitle;

import java.util.Set;
import java.util.function.Predicate;
import java.util.stream.Collectors;
import java.util.stream.Stream;

@Tag("theme-toggle") (1)
@JsModule("./src/component/theme-toggle/theme-toggle.js") (2)
public class ThemeToggle extends Component implements ClickNotifier<ThemeToggle>,
        Focusable<ThemeToggle>, HasTheme, HasEnabled, HasSize, HasStyle,
        HasText, HasTooltip, HasTitle, HasAriaLabel { (3)

    public static final String STORAGE_KEY_PROPERTY = "storageKey";
    public static final String THEME_CHANGED_EVENT = "theme-changed";
    protected Component iconComponent;

    public ThemeToggle() {
        setIcon(createDefaultIcon());
    }

    public ThemeToggle(Component icon) {
        setIcon(icon);
    }

    public ThemeToggle(String text, Component icon) {
        setIcon(icon);
        setText(text);
    }

    protected Icon createDefaultIcon() {
        Icon icon = VaadinIcon.ADJUST.create();
        icon.getElement().getStyle().set("rotate", "180deg");
        return icon;
    }

    @Override
    public void setText(String text) {
        removeAll(getNonTextNodes());
        if (text != null && !text.isEmpty()) {
            getElement().appendChild(Element.createText(text));
        }
        updateThemeAttribute();
    }

    public Component getIcon() {
        return iconComponent;
    }

    public void setIcon(Component icon) {
        if (icon != null && icon.getElement().isTextNode()) {
            throw new IllegalArgumentException("Text node can't be used as an icon.");
        }
        if (iconComponent != null) {
            remove(iconComponent);
        }

        iconComponent = icon;
        if (icon != null) {
            add(icon);
            updateIconSlot();
        }

        updateThemeAttribute();
    }

    protected void updateIconSlot() {
        iconComponent.getElement().setAttribute("slot", "prefix");
    }

    protected void add(Component... components) {
        for (Component component : components) {
            getElement().appendChild(component.getElement());
        }
    }

    protected void remove(Component... components) {
        for (Component component : components) {
            if (getElement().equals(component.getElement().getParent())) {
                component.getElement().removeAttribute("slot");
                getElement().removeChild(component.getElement());
            } else {
                throw new IllegalArgumentException(
                        "The given component (" + component + ") is not a child of this component");
            }
        }
    }

    public boolean isAutofocus() {
        return getElement().getProperty("autofocus", false);
    }

    public void setAutofocus(boolean autofocus) {
        getElement().setProperty("autofocus", autofocus);
    }

    public String getStorageKey() {
        return getElement().getProperty(STORAGE_KEY_PROPERTY);
    }

    public void setStorageKey(String storageKey) {
        getElement().setProperty(STORAGE_KEY_PROPERTY, storageKey);
    }

    protected void removeAll(Element... exclusion) {
        Set<Element> toExclude = Stream.of(exclusion)
                .collect(Collectors.toSet());
        Predicate<Element> filter = toExclude::contains;

        getElement().getChildren()
                .filter(filter.negate())
                .forEach(child -> child.removeAttribute("slot"));

        getElement().removeAllChildren();
        getElement().appendChild(exclusion);
    }

    protected Element[] getNonTextNodes() {
        return getElement().getChildren()
                .filter(element -> !element.isTextNode())
                .toArray(Element[]::new);
    }

    protected void updateThemeAttribute() {
        long childCount = getElement().getChildren()
                .filter(element ->
                        element.isTextNode() || !"vaadin-tooltip".equals(element.getTag()))
                .count();

        if (childCount == 1 && iconComponent != null) {
            getThemeNames().add("icon");
        } else {
            getThemeNames().remove("icon");
        }
    }

    public Registration addThemeChangeListener(ComponentEventListener<ThemeToggleThemeChangedEvent> listener) {
        return addListener(ThemeToggleThemeChangedEvent.class, listener);
    }

    @DomEvent(THEME_CHANGED_EVENT) (4)
    public static class ThemeToggleThemeChangedEvent extends ComponentEvent<ThemeToggle> {

        protected String value;

        public ThemeToggleThemeChangedEvent(ThemeToggle source, boolean fromClient,
                                            @EventData("event.detail.value") String value) { (5)
            super(source, fromClient);
            this.value = value;
        }

        public String getValue() {
            return value;
        }
    }
}
1 定义由 Component` 类自动创建的 根 元素，可以通过 getElement() 方法访问。必须与 Web 组件导出的相同。
2 @JsModule 注解定义需要导入 JavaScript 模块。
3 使用 Vaadin Mixin 接口 为 Web 组件中的大部分功能集提供通用 API 和默认行为。
4 使用 @DomEvent 注解关联 ThemeToggle 组件与 theme-changed DOM 事件。
5 使用 @EventData 注解定义附加的事件数据，这里用到了主题值。
关于创建自定义组件的更多内容可以参阅 Vaadin 文档： 创建组件、 使用 Vaadin Mixin 接口、 使用组件事件。

用例

组件实现完成后，可以在视图 XML 和 Java 中使用，示例：

XML 用法

<view xmlns="http://jmix.io/schema/flowui/view"
      xmlns:app="http://company.com/schema/app-ui-components"
      title="msg://themeToggleView.title"> (1)
    <layout>
        <app:themeToggle text="Click to switch theme"/> (2)
    </layout>
</view>
1 定义一个命名空间，与组件 XSD 中 xmlns 和 targetNamespace 属性相同。
2 添加带有命名空间前缀的 themeToggle 元素。

编程式用法

@Subscribe
public void onInit(final InitEvent event) {
    ThemeToggle themeToggle = new ThemeToggle();
    themeToggle.setText("Click to switch theme");
    themeToggle.addThemeChangeListener(changedEvent ->
            notifications.create("Theme switched: " + getThemeValue(changedEvent))
                    .withPosition(Notification.Position.TOP_CENTER)
                    .show());
    getContent().add(themeToggle);
}