Listes

Ouvrir dans ChatGPT

info

Cette section décrit les fonctionnalités communes de tous les composants de liste et n'est pas une classe qui peut être instanciée ou utilisée directement.

Il existe trois types de listes disponibles pour une utilisation dans vos applications : ListBox, ChoiceBox et ComboBox. Ces composants affichent tous une liste d'éléments clé-valeur et fournissent des méthodes pour ajouter, supprimer, sélectionner et gérer les éléments dans la liste.

Cette page décrit les caractéristiques et comportements partagés de tous les composants de liste, tandis que les détails spécifiques pour chacun sont couverts dans leurs pages respectives.

Utilisation de ListItem

Les composants de liste sont composés d'objets ListItem, qui représentent des éléments individuels au sein d'une liste. Chaque ListItem est associé à une clé unique et à un texte d'affichage. Les principales caractéristiques de la classe ListItem incluent :

• Un ListItem encapsule une clé unique sous forme d'Object et un texte sous forme de String à afficher dans le composant de liste.
• Vous pouvez construire un ListItem en fournissant une clé et un texte, ou en spécifiant uniquement le texte, qui est également utilisé comme clé.

Les clés doivent être uniques dans une liste. L'ajout d'un deuxième élément uniquement texte avec le même texte déclenche une IllegalArgumentException. Pour afficher des étiquettes en double, fournissez des clés distinctes pour ces éléments.

Gestion des objets ListItem avec l'API

Les différents composants de liste offrent plusieurs méthodes pour gérer la liste des éléments et maintenir un état cohérent entre la liste et le client. En utilisant ces méthodes, vous pouvez gérer efficacement les éléments au sein de la liste. L'API vous permet d'interagir avec et de manipuler la liste pour répondre aux besoins de votre application.

Ajout d'éléments

• Ajout d'un élément :

  • Pour ajouter un ListItem à la liste, vous pouvez utiliser la méthode add(ListItem item).
  • Vous pouvez également ajouter un nouveau ListItem en spécifiant la clé et le texte en utilisant la méthode add(Object key, String text) ou add(String text).

• Insertion d'un élément à un index spécifique :

  • Pour insérer un élément à un index spécifique, utilisez la méthode insert(int index, ListItem item).
  • Vous pouvez insérer un élément avec clé et texte en utilisant la méthode insert(int index, Object key, String text) ou insert(int index, String text).

• Insertion de plusieurs éléments :

  • Vous pouvez insérer plusieurs éléments à un index spécifié en utilisant la méthode insert(int index, List< ListItem > items).

conseil

Pour optimiser les performances, au lieu de déclencher un message serveur-client chaque fois que vous utilisez la méthode add(), il est plus efficace de créer d'abord une liste d'objets ListItem. Une fois que vous avez cette liste, vous pouvez les ajouter tous en une seule fois en utilisant la méthode insert(int index, List<ListItem> items). Cette approche réduit la communication serveur-client, améliorant l'efficacité globale. Pour des directives détaillées sur cela et d'autres meilleures pratiques dans l'architecture webforJ, référez-vous à Interaction Client/Serveur.

Suppression d'éléments

• Suppression d'un élément :

  • Pour supprimer un élément de la liste, utilisez la méthode remove(int index) ou remove(Object key).

• Suppression de tous les éléments :

  • Vous pouvez supprimer tous les éléments de la liste en utilisant removeAll().

Sélection d'éléments

Tous les types de listes implémentent l'interface SelectableList. Cette interface permet plusieurs façons de sélectionner l'actuel ListItem.

Avec un ListItem donné

select(ListItem item) prend un ListItem comme paramètre à sélectionner.

ListBox demoList = new ListBox();
ListItem demoItem = new ListItem("demo","Élément Démo");
demoList.add(demoItem);
demoList.select(demoItem);

Avec une clé donnée d'un ListItem

selectKey(Object key) prend une clé pour un ListItem comme paramètre à sélectionner.

ListBox demoList = new ListBox();
demoList.add("demo","Élément Démo");
demoList.selectKey("demo");

Avec un index donné d'un ListItem

selectIndex(int index) prend un index pour un ListItem comme paramètre à sélectionner.

ListBox demoList = new ListBox();
demoList.add("demo","Élément Démo");
demoList.selectIndex(0);

Autres opérations sur les listes

• Accéder et mettre à jour des éléments :

  • Pour accéder aux éléments par clé ou index, utilisez getByKey(Object key) ou getByIndex(int index).
  • Vous pouvez mettre à jour le texte d'un élément en utilisant la méthode setText(String text) dans la classe ListItem.

• Récupération d'informations sur la liste :

  • Vous pouvez obtenir la taille de la liste en utilisant la méthode size().
  • Pour vérifier si la liste est vide, utilisez la méthode isEmpty().

Itération sur des listes

Tous les composants de liste implémentent l'interface Java Iterable. Utilisez forEach() ou une boucle for pour accéder ou modifier chaque ListItem.

Le code ci-dessous démontre deux façons simples d'itérer à travers une liste :

list.forEach(item -> {
   item.setText("Modifié : " + item.getText());
});

for (ListItem item : list) {
   item.setText("Modifié2 : " + item.getText());
}

Recherche 26.02

Tous les composants List ont un champ de recherche intégré qui filtre les éléments par leur texte. Le champ est désactivé par défaut. Utilisez getSearch() pour accéder à la configuration de la recherche, puis setFieldVisible(true) pour afficher le champ en haut de la liste du composant.

ComboBox comboBox = new ComboBox("Fruit");
comboBox.insert("Pomme", "Banane", "Cerise", "Abricot", "Ananas");

comboBox.getSearch()
  .setFieldVisible(true)
  .setPlaceholder("Rechercher des fruits")
  .setEmptyMessage("Aucun fruit trouvé");

Le filtrage ne cache que les éléments qui ne correspondent pas. Les index des éléments et la sélection actuelle sont intacts, donc getSelectedIndex() continue de faire référence à la liste complète plutôt qu'aux éléments actuellement visibles.

Le champ de recherche peut être caché à nouveau avec setFieldVisible(false).

Configuration du champ

• setPlaceholder() définit le texte d'espace réservé du champ de recherche. La valeur par défaut est Recherche.

• setEmptyMessage() définit le message affiché lorsqu'une recherche ne renvoie aucun résultat. La valeur par défaut est Aucune donnée à afficher.

Chaque paramètre a un getter correspondant : isFieldVisible(), getPlaceholder(), getEmptyMessage(), et getTerm().

Filtrage depuis le code

setTerm() définit le terme de recherche et filtre la liste. Cela fonctionne que le champ soit visible ou non, donc une liste peut être filtrée sans afficher d'interface utilisateur de recherche.

listBox.getSearch().setTerm("pomme");

getTerm() et le champ de recherche

Taper dans le champ de recherche n'écrit pas le terme de retour à la configuration. getTerm() renvoie la dernière valeur passée à setTerm(), pas ce que l'utilisateur a tapé.

Propriétés de liste partagées

Étiquette

Tous les composants List peuvent se voir attribuer une étiquette, qui est un texte descriptif ou un titre associé au composant. Les étiquettes fournissent une brève explication ou une invite pour aider les utilisateurs à comprendre le but ou la sélection attendue pour cette liste particulière. En plus de leur importance pour l'utilisabilité, les étiquettes de liste jouent également un rôle crucial dans l'accessibilité, permettant aux lecteurs d'écran et aux technologies d'assistance de fournir des informations précises et de faciliter la navigation au clavier.

Texte d'aide

Chaque composant List peut afficher un texte d'aide sous la liste en utilisant la méthode setHelperText(). Ce texte d'aide offre un contexte supplémentaire ou des explications sur les options disponibles, garantissant que les utilisateurs disposent des informations nécessaires pour faire des sélections éclairées.

Alignement horizontal

Tous les composants de liste implémentent l'interface HasHorizontalAlignment, vous donnant le contrôle sur la manière dont le texte et le contenu sont alignés dans le composant.

Utilisez la méthode setHorizontalAlignment() avec l'énumération HasHorizontalAlignment.Alignment pour définir l'alignement :

• Alignment.LEFT (par défaut)
• Alignment.MIDDLE
• Alignment.RIGHT

ListBox listBox = new ListBox();
listBox.setHorizontalAlignment(Alignment.LEFT);

Pour obtenir l'alignement actuel :

Alignment alignment = listBox.getHorizontalAlignment();

Expanses

Tous les composants de liste dans webforJ implémentent également l'interface HasExpanse, vous permettant d'ajuster la taille globale et le poids visuel du composant. Cela est utile pour adapter le composant à divers contextes UI, tels que des formulaires, des dialogues, des barres latérales, etc.

Utilisez la méthode setExpanse() pour définir le niveau d'expansion. Les options incluent :

• Expanse.NONE
• Expanse.XSMALL
• Expanse.SMALL
• Expanse.MEDIUM (par défaut)
• Expanse.LARGE
• Expanse.XLARGE

ListBox listBox = new ListBox();
listBox.setExpanse(Expanse.LARGE);

Vous pouvez récupérer le paramètre actuel en utilisant :

Expanse current = listBox.getExpanse();

Sujets

📄️ChoiceBox

Pick a single value from a fixed set with the ChoiceBox dropdown, including dropdown type styling, max row count, and keyboard navigation.

📄️ComboBox

Combine a dropdown list with a text input in the ComboBox to let users select preset items or type custom values with placeholder support.

📄️ListBox

Show a scrollable, always-visible list with the ListBox component, supporting single or multiple selection and keyboard navigation.

Continuez à apprendre.

ArticleMulti-select in Java UI: ListBox and ChoiceBox with webforJArticleComboBox in Java: preset items and custom values