Passer au contenu principal

Using Components

Ouvrir dans ChatGPT
Java API

Les composants sont les blocs de construction des applications webforJ. Que vous utilisiez des composants intégrés comme Button et TextField, ou que vous travailliez avec des composants personnalisés fournis par votre équipe, la manière dont vous interagissez avec eux suit le même modèle cohérent : vous configurez des propriétés, gérez l'état et composez des composants en mises en page.

Ce guide se concentre sur ces opérations quotidiennes : pas sur les détails internes du fonctionnement des composants, mais sur la façon de faire les choses avec eux dans la pratique.

Propriétés des composants​

Chaque composant expose des propriétés qui contrôlent son contenu, son apparence et son comportement. La plupart de celles-ci ont des méthodes Java typées dédiées (setText(), setTheme(), setExpanse(), etc.), qui sont la manière principale dont vous configurerez des composants dans webforJ. Les sections ci-dessous couvrent les propriétés et méthodes qui s'appliquent largement aux types de composants.

Contenu textuel​

La méthode setText() définit le texte visible d'un composant, tel que la légende d'un Button ou le contenu d'un Label. Pour les composants d'entrée comme TextField, utilisez setValue() à la place pour définir la valeur actuelle du champ.

Button button = new Button();
button.setText("Cliquez Moi");

Label label = new Label();
label.setText("Statut : prêt");

TextField field = new TextField();
field.setValue("Valeur initiale");

Certains composants prennent également en charge setHtml() dans les cas où vous avez besoin de balisage HTML en ligne dans le contenu :

Div container = new Div();
container.setHtml("<strong>Texte en gras</strong> et <em>texte en italique</em>");

Attributs HTML​

La plupart des configurations dans webforJ se font via des méthodes Java typées plutôt que des attributs HTML bruts. Cependant, setAttribute() est utile pour passer des attributs d'accessibilité qui n'ont pas d'API dédiée :

Button button = new Button("Soumettre");
button.setAttribute("aria-label", "Soumettre le formulaire");
button.setAttribute("aria-describedby", "form-hint");
Vérifiez le support des composants

Tous les composants ne supportent pas des attributs arbitraires. Cela dépend de l'implémentation sous-jacente du composant.

Identifiants de composant​

Vous pouvez attribuer un identifiant à l'élément HTML d'un composant en utilisant setAttribute() :

Button submitButton = new Button("Soumettre");
submitButton.setAttribute("id", "submit-btn");

TextField emailField = new TextField("Email");
emailField.setAttribute("id", "email-input");

Les identifiants DOM sont couramment utilisés pour les sélecteurs de test et le ciblage CSS dans vos feuilles de style.

Préférez les classes pour cibler plusieurs composants

Contrairement aux classes CSS, les identifiants doivent être uniques dans votre application. Si vous devez cibler plusieurs composants, utilisez addClassName() à la place.

Identifiants gérés par le framework

webforJ attribue également des identifiants automatiques aux composants en interne. L'identifiant côté serveur (accessible via getComponentId()) est utilisé pour le suivi du framework, tandis que l'identifiant côté client (accessible via getClientComponentId()) est utilisé pour la communication client-serveur. Ceux-ci sont distincts de l'attribut id DOM que vous définissez avec setAttribute().

Style​

Trois méthodes couvrent la plupart des besoins en matière de style : setStyle() pour des valeurs CSS individuelles, et addClassName() et removeClassName() pour appliquer ou supprimer des classes CSS définies dans vos feuilles de style. Utilisez setStyle() pour des ajustements de style mineurs ou uniques, et utilisez des classes CSS pour appliquer un style plus important ou réutilisable.

Div container = new Div();
container.setStyle("padding", "20px");

if (isHighPriority) {
    container.setStyle("border-left", "4px solide rouge");
}

Button button = new Button("Basculer");
button.addClassName("principal", "grand");

if (isLoading) {
    button.addClassName("chargement");
}
Approche héritée

@InlineStyleSheet est une approche héritée et n'est généralement pas recommandée pour les nouveaux projets. Dans la plupart des cas, gardez vos styles dans des fichiers CSS séparés.

État des composants​

Au-delà du contenu et de l'apparence, les composants ont des propriétés d'état qui déterminent s'ils sont visibles et s'ils répondent à l'interaction de l'utilisateur. Les deux plus couramment utilisés sont setVisible() et setEnabled().

setVisible() contrôle si le composant est rendu dans l'interface utilisateur. setEnabled() contrôle s'il accepte l'entrée ou l'interaction tout en restant visible. Dans la plupart des cas, le désactivation est préférable à la dissimulation : un bouton désactivé communique toujours qu'une action existe mais n'est pas encore disponible, ce qui est moins déroutant que de le faire apparaître et disparaître.

// Révéler un champ supplémentaire lorsque une case à cocher est cochée
TextField advancedField = new TextField("Paramètre avancé");
advancedField.setVisible(false);

CheckBox enableAdvanced = new CheckBox("Afficher les paramètres avancés");
enableAdvanced.addValueChangeListener(e -> advancedField.setVisible(e.getValue()));

// Activer un bouton uniquement lorsque le champ requis a une valeur
Button submitButton = new Button("Soumettre");
submitButton.setEnabled(false);

TextField nameField = new TextField("Nom");
nameField.addValueChangeListener(e -> submitButton.setEnabled(!e.getValue().isBlank()));

Le formulaire de connexion suivant démontre setEnabled() en pratique. Le bouton de connexion reste désactivé jusqu'à ce que les deux champs aient un contenu, ce qui rend clair à l'utilisateur que l'entrée est requise avant de continuer :

Afficher le code

Travailler avec des conteneurs​

Dans webforJ, la mise en page est gérée par des conteneurs, qui sont des composants qui contiennent d'autres composants et contrôlent comment ils sont arrangés. Vous ne positionnez pas manuellement les composants enfants ; au lieu de cela, vous les ajoutez à un conteneur et configurez les propriétés de mise en page de ce conteneur.

Ajouter des composants​

Tous les conteneurs fournissent une méthode add(). Vous pouvez passer des composants un à un ou tous à la fois :

FlexLayout container = new FlexLayout();

container.add(new Button("Cliquez Moi"));

TextField nameField = new TextField("Nom");
TextField emailField = new TextField("Email");
Button submitButton = new Button("Soumettre");

container.add(nameField, emailField, submitButton);

Options de mise en page​

FlexLayout est le conteneur de mise en page principal dans webforJ et couvre la majorité des cas d'utilisation : lignes, colonnes, alignement, espacement et enveloppement. Pour des arrangements plus complexes tels que CSS Grid ou un positionnement personnalisé, vous pouvez appliquer CSS directement via setStyle() ou addClassName() sur n'importe quel composant conteneur. Voir la documentation FlexLayout pour la gamme complète d'options de mise en page.

Afficher et cacher des sections​

Une utilisation courante de setVisible() dans les conteneurs est de révéler une interface utilisateur supplémentaire seulement lorsque cela est pertinent. Cela garde l'interface centrée et réduit l'encombrement visuel. Plutôt que de naviguer vers une nouvelle vue, vous pouvez montrer une section de la mise en page actuelle en réponse directe à une entrée utilisateur.

Le panneau de paramètres suivant démontre cela : les préférences de notification de base sont toujours visibles, et une section d'options avancées n'apparaît que lorsque l'utilisateur en fait la demande. Le bouton de sauvegarde s'active dès qu'un paramètre est modifié :

Afficher le code

Gestion des conteneurs​

Utilisez remove() et removeAll() pour retirer des composants d'un conteneur à l'exécution :

FlexLayout container = new FlexLayout();
Button tempButton = new Button("Temporaire");

container.add(tempButton);
container.remove(tempButton);

container.removeAll();

Ceci est utile lorsque vous devez remplacer complètement le contenu, par exemple en échangeant un indicateur de chargement pour les données chargées.

Validation de formulaire​

Coordonner plusieurs composants pour contrôler une action de soumission est l'un des modèles les plus courants dans les interfaces utilisateur webforJ. L'idée centrale est simple : chaque champ de saisie enregistre un écouteur, et chaque fois qu'une valeur change, le formulaire réévalue si tous les critères sont satisfaits et met à jour le bouton de soumission en conséquence.

Ceci est préférable à l'affichage des erreurs de validation seulement après que l'utilisateur a cliqué sur soumettre, car cela fournit des retours continus et empêche des soumissions inutiles. Le bouton de soumission sert d'indicateur : désactivé signifie que le formulaire n'est pas prêt, activé signifie qu'il l'est.

Dans ce formulaire de contact, le champ de nom ne doit pas être vide, l'email doit contenir un symbole @, et le message doit avoir au moins 10 caractères de long :

Afficher le code

Mises à jour de contenu dynamique​

Les composants n'ont pas à rester dans un état fixe après leur création. Vous pouvez mettre à jour le texte, échanger des classes CSS, et basculer l'état activé à tout moment en réponse aux événements de l'application. Un exemple courant est de fournir des retours pendant une tâche de longue durée :

Label statusLabel = new Label("Prêt");
Button startButton = new Button("Démarrer le processus");

startButton.onClick(event -> {
    startButton.setEnabled(false);
    statusLabel.setText("Traitement...");
    statusLabel.addClassName("traitement");
    
    performTask(() -> {
        statusLabel.setText("Terminé");
        statusLabel.removeClassName("traitement");
        statusLabel.addClassName("succès");
        startButton.setEnabled(true);
    });
});

Désactiver le bouton pendant que la tâche s'exécute empêche des soumissions en double, et mettre à jour le label tient l'utilisateur informé de ce qui se passe.

ComponentLifecycleObserver​

L'interface ComponentLifecycleObserver vous permet d'observer les événements de cycle de vie des composants depuis l'extérieur du composant lui-même. Cela est utile lorsque vous devez réagir à la création ou à la destruction d'un composant sans modifier son implémentation. Par exemple, vous pourriez l'utiliser pour maintenir un registre de composants actifs ou libérer des ressources externes lorsqu'un composant est retiré.

Utilisation de base​

Appelez addLifecycleObserver() sur n'importe quel composant pour enregistrer un rappel. Le rappel reçoit le composant et l'événement de cycle de vie :

Button button = new Button("Regardez Moi");

button.addLifecycleObserver((component, event) -> {
    switch (event) {
        case CREATE:
            System.out.println("Le bouton a été créé");
            break;
        case DESTROY:
            System.out.println("Le bouton a été détruit");
            break;
    }
});

Modèle : Registre de ressources​

L'événement DESTROY est particulièrement utile pour garder un registre automatiquement synchronisé. Plutôt que de supprimer manuellement des composants lorsqu'ils ne sont plus nécessaires, vous laissez le composant notifier le registre lui-même :

public class ResourceRegistry {
    private final Map<String, Component> activeComponents = new ConcurrentHashMap<>();
    
    public void track(Component component, String name) {
        activeComponents.put(name, component);
        
        component.addLifecycleObserver((comp, event) -> {
            if (event == ComponentLifecycleObserver.LifecycleEvent.DESTROY) {
                activeComponents.remove(name);
            }
        });
    }
}

Modèle : Coordination de composants​

Une classe de coordination qui gère un ensemble de composants liés peut utiliser la même approche pour garder sa liste interne précise :

public class FormCoordinator {
    private final List<DwcComponent<?>> managedComponents = new ArrayList<>();
    
    public void manage(DwcComponent<?> component) {
        managedComponents.add(component);
        
        component.addLifecycleObserver((comp, event) -> {
            if (event == ComponentLifecycleObserver.LifecycleEvent.DESTROY) {
                managedComponents.remove(comp);
            }
        });
    }
    
    public void disableAll() {
        managedComponents.forEach(c -> c.setEnabled(false));
    }
}

Quand utiliser​

Utilisez ComponentLifecycleObserver pour :

  • Construire des registres de composants
  • Implémenter le journalisme ou la surveillance
  • Coordonner plusieurs composants
  • Nettoyer les ressources externes

Pour exécuter du code après qu'un composant ait été attaché au DOM, voir whenAttached() dans le guide des Composants composites.

Données utilisateur​

Les composants peuvent transporter des données arbitraires côté serveur via setUserData() et getUserData(). Les deux méthodes prennent une clé pour identifier les données. Ceci est utile lorsque vous devez associer des objets de domaine ou un contexte avec un composant sans gérer une structure de recherche distincte.

Button button = new Button("Traiter");
button.setUserData("contexte", new ProcessingContext(userId, taskId));

button.onClick(event -> {
    ProcessingContext context = (ProcessingContext) button.getUserData("contexte");
    processTask(context.getUserId(), context.getTaskId());
});

Puisque les données utilisateur ne sont jamais envoyées au client, vous pouvez en toute sécurité stocker des informations sensibles ou de grands objets sans affecter le trafic réseau.