Regrouper une liste avec le composant GroupBy

GroupBy ajoute à une liste Vue un regroupement par champ, avec des colonnes d'agrégation (compte, somme, moyenne, minimum, maximum). Il reprend le regroupement de la vue Rapport du desk. Il est destiné aux applications Vue qui utilisent le paquet @framework/ui (Studio, Builder, HRMS…).

Lien avec frappe-ui

GroupBy fait partie du paquet @framework/ui de Dodock. Ce paquet complète frappe-ui avec des composants qui dépendent du serveur Dodock : métadonnées des types de documents, permissions, requêtes. Il n'est pas publié sur npm : l'application le consomme comme paquet local, et vue, vue-router et frappe-ui sont des dépendances partagées avec l'application hôte (voir Package @framework/ui).

GroupBy est construit avec les composants de base de frappe-ui (Popover, Combobox, Select, Switch, Button) et charge ses données avec createResource. Pour ces composants de base, consultez la documentation de frappe-ui sur ui.frappe.io. Les types TypeScript et les commentaires du dossier ui/src/components/GroupBy/ sont la référence de l'API.

import { GroupBy, GroupByTable, serializeGroupBy, useGroupByData } from "@framework/ui/GroupBy";

Fonctionnement

Le regroupement passe par quatre éléments. Les deux composants d'affichage n'exécutent aucune requête : l'application choisit comment charger les données.

      
flowchart LR
  A[GroupBy
    

1. GroupBy est le bouton et le panneau qui modifient le regroupement. Son v-model est un objet GroupBySettings (champs de regroupement, agrégats, largeurs, tri, affichage des totaux), ou null si la liste n'est pas regroupée. Les modifications restent dans un brouillon jusqu'au clic sur « Appliquer ». Les champs proposés viennent des métadonnées du doctype. La prop exclude retire des champs des sélecteurs.
2. serializeGroupBy(settings) transforme ce modèle en arguments de frappe.client.get_list : fields (avec un alias _aggregate_{i} par agrégat), group_by et order_by. serializeGroupByTotals(settings) donne les mêmes agrégats sans regroupement, pour la ligne de totaux.
3. useGroupByData(doctype, groupBy, filters) est optionnel. Il exécute ces requêtes et renvoie des refs (rows, totals, loading, rowCount, totalCount, hasNextPage, pageLength…) et les fonctions loadMore() et reload(). Chaque paramètre accepte une valeur, une ref ou une fonction. Une modification du type de document, du regroupement, des filtres ou de la longueur de page relance la requête depuis la première page. Le nombre de groupes est compté sur 1 000 clés au plus : au-delà, totalCapped vaut true.
4. GroupByTable affiche une ligne par groupe. Un clic sur un en-tête trie les groupes, la poignée entre deux colonnes change leur largeur. Le tableau renvoie le regroupement mis à jour par update:groupBy : le tri et les largeurs font partie du modèle.

Une application qui a déjà sa couche de données appelle serializeGroupBy elle-même et passe les lignes à GroupByTable.

Champs et agrégats

• Les champs regroupables sont ceux de la vue Rapport du desk : Select, Link, Dynamic Link, Data, Autocomplete, Check, Int, Date, Rating, et les champs standard owner, modified_by, _user_tags et docstatus. Les champs virtuels sont exclus.
• count ne demande aucun champ. sum porte sur les champs numériques. avg, min et max acceptent aussi les champs Rating. min et max acceptent aussi les dates et heures, y compris creation et modified.
• Une note (Rating) est stockée comme une fraction de son échelle. GroupByTable l'affiche sur son échelle : une moyenne de 0,8 s'affiche « 4 / 5 ».

Enregistrer le regroupement dans la vue

Le composable useListView du module @framework/ui/ListView expose une ref groupBy et l'inclut dans le snapshot de la vue, avec les filtres, le tri et les colonnes. La bibliothèque n'enregistre rien elle-même : l'application enregistre ce snapshot, puis le rend à restore() au chargement. Un snapshot sans clé groupBy laisse la liste non regroupée.

Limites

• Pas de regroupement par champ d'une table enfant.
• Pas de paramètre d'URL _group_by pour partager une liste regroupée.
• Les lignes de groupe ne s'ouvrent pas : un groupe n'a pas de document à afficher.