Skip to Content
Documentation
Afficher et explorer

Recherche et filtres

Combiner recherche, filtres de colonnes et règles avancées ET/OU.

Un tableau peut proposer une recherche rapide, une barre de filtres et un éditeur de règles avancées. Déclarez les types des colonnes pour proposer les opérateurs adaptés.

Exemple de configuration

Partez du démarrage React ou du démarrage Vue. Le fichier suivant complète leur catalogue de produits. Passez cette configuration via getTableConfig en React ou config en Vue.

filtering-config.ts
import { defineTableConfig } from "@/components/ui/yayaw-table/config/helpers";
import { productConfig } from "./product-config";

export const filteringConfig = defineTableConfig({
  ...productConfig,
  table: {
    ...productConfig.table,
    enableColumnFilters: true,
    enableAdvancedFilters: true,
    showFilterBar: true,
    filterBarColumns: ["status"],
    showClearFilters: true,
    searchDebounceMs: 250,
  },
});
filtering-config.ts
import { defineTableConfig } from "@/components/ui/yayaw-table-vue/config";
import { productConfig } from "./product-config";

export const filteringConfig = defineTableConfig({
  ...productConfig,
  table: {
    ...productConfig.table,
    enableColumnFilters: true,
    enableAdvancedFilters: true,
    showFilterBar: true,
    filterBarColumns: ["status"],
    showClearFilters: true,
    searchDebounceMs: 250,
  },
});

Choisir le bon contrôle

La recherche traite le texte libre. La barre optionnelle met en avant des colonnes à options statiques, booléennes ou de date souvent utilisées. Les menus de colonnes ouvrent la règle de leur colonne. Le menu de filtre, inspiré de Notion, ajoute des règles typées et les combine avec Et / Ou : dès deux règles, les deux éditions proposent « toutes les conditions / au moins une condition », enregistré avec les vues et dans l’URL. Masquer un contrôle ne dispense pas le backend de traiter les filtres reçus.

Le menu de filtre

Les filtres natifs sont activés par défaut ; table.enableAdvancedFilters: false désactive explicitement leur éditeur. + Filtre reste directement accessible dans la ligne de filtres sous la barre d’outils, même avant l’ajout de la première règle, en React et en Vue. Il ouvre la liste des colonnes filtrables avec une recherche. Cette même liste reste disponible depuis l’écran Filtre des Réglages de la vue. Le badge du bouton des réglages de la vue compte les filtres et tris actifs que la vue par défaut (table.defaultView par-dessus les valeurs par défaut du catalogue) n’applique pas déjà : un tableau qui montre sa vue par défaut n’a pas de badge. Choisir une colonne ajoute une règle et ouvre son éditeur, et l’entrée de filtre d’un en-tête de colonne ouvre la règle de cette colonne.

  • Compteurs par propriété : la liste des propriétés affiche le nombre de règles actives et complètes à côté de chaque colonne, y compris les périodes épinglées. Les règles désactivées et les brouillons incomplets ne comptent pas. Plusieurs valeurs sélectionnées dans une même règle comptent pour un filtre ; une propriété sans règle active n’affiche aucun compteur.

  • État vide : sans règle, + Filtre reste disponible. Supprimer la dernière règle conserve ce point d’entrée visible.

  • Effacer les filtres : quand des règles sont affichées dans cette ligne, une action à côté de leurs puces les efface ensemble. Les périodes épinglées dans la barre d’outils ou la barre de filtres rapides restent inchangées. L’action disparaît quand la ligne n’a plus de règle à effacer.

  • Puces : chaque règle s’affiche sous la barre d’outils comme une puce (« Statut est Actif », « Échéance · 30 derniers jours »). Un clic sur la puce change l’opérateur ou la valeur, ou supprime la règle. Les opérateurs suivent le type de la colonne : texte, nombre, date, sélection, sélection multiple, booléen, lieu et dossier de l’arborescence.

  • Filtre avancé : Ajouter un filtre avancé présente les règles en une seule liste combinée avec Et ou Ou, comme Notion.

  • Saisie : le texte et les nombres filtrent dès que la saisie marque une pause (500 ms), sur Entrée ou en quittant le champ ; Échap rétablit la valeur qui filtre.

  • Règles incomplètes : une règle sans valeur reste une puce en pointillés et n’atteint jamais list, l’URL ni une vue enregistrée.

  • Libellés : le menu a des libellés anglais et français intégrés, choisis selon la langue de la table, et lit les traductions filters.menu.* et filters.menu.operators.* (voir Traductions).

Une colonne peut déclarer filterType si sa cellule utilise une autre représentation, et filterOperators pour proposer uniquement les opérateurs pris en charge par son serveur. Pour les choix distants, optionsLoader(query, signal) fournit des identifiants typés et leurs libellés ; optionsSearchMinLength et optionsSearchDebounceMs définissent quand lancer la recherche. L’éditeur ignore les réponses périmées, conserve les libellés sélectionnés et signale les erreurs. Appliquez les mêmes règles Et/Ou côté serveur avant la pagination et les totaux. Les contrôles filterRenderer propres à l’application restent disponibles.

Les vues enregistrées remplacent les presets de filtres : enregistrez une vue filtrée pour réutiliser un ensemble de règles. Les anciens composants de filtre React (AdvancedFilterPanel, EnhancedFilterChip, FilterPresetsPanel, ModernAddFilterDropdown, les filtres par type comme DateFilter, et useFilterPresets) ainsi que AdvancedFilters et FilterRule en Vue n’existent plus ; voir Migration.

Règles de date

L’éditeur d’une règle de date propose trois choix sous forme de groupe radio segmenté :

  • Relative : « Ce(tte) », « Les derniers » ou « Les prochains », puis un nombre et une unité (jour, semaine, mois, année), par exemple les 2 dernières semaines. La période suit le calendrier.

  • Date exacte : un jour, choisi dans un calendrier mensuel.

  • Période : le premier et le dernier jour, choisis dans le même calendrier, tous deux inclus.

Le calendrier met en évidence la période couverte par la règle, y compris les périodes relatives. Les choix relatifs sont enregistrés comme des jetons : un « Ce mois-ci » enregistré désigne toujours le mois en cours le mois suivant.

Pour garder sous la main la période d’une colonne de date, nommez-la dans la configuration de la table :

table: {
  enableAdvancedFilters: true,
  toolbarDateFilter: "updatedAt",
}

La barre d’outils affiche alors cette période avec les jours qu’elle couvre aujourd’hui (« Ce mois-ci · 1 – 31 oct. ») et la modifie en un clic ; choisir cette colonne dans l’écran Filtre ouvre la même période au lieu d’ajouter une deuxième règle. Une colonne date listée dans table.filterBarColumns reçoit la même période dans la barre de filtres : toutes les dates, un choix relatif, ou des jours du / au. Chacune de ces périodes est une règle avancée (filter-bar-<columnId>) : les graphiques, les calendriers et les autres modes d’affichage filtrent avec elle, et list la reçoit comme toute règle de date.

Conserver les types des valeurs

Les valeurs de sélection sont des identifiants stables, pas leurs libellés traduits. Une sélection multiple stocke un tableau. Les nombres et booléens doivent conserver leur type : la chaîne "false" n’est pas le booléen false. Les filtres de date choisissent des jours : les valeurs d’une règle de date sont des jours du calendrier écrits AAAA-MM-JJ (un jour, ou le premier et le dernier jour de between, inclus tous les deux), que la colonne contienne des dates ou des horodatages ; voir Règles de date. Le helper partagé matchesContractFilter illustre les opérateurs dans le démarrage. Traduisez cette même sémantique dans votre requête de base de données.

Tester le parcours complet

Dans la recette catalogue, filtrez sur Active, cherchez « desk », puis effacez les filtres. Le passage en galerie conserve la requête. Testez ET et OU avec au moins deux règles et vérifiez les totaux avant et après pagination.

Garder les filtres fréquents accessibles

Exposez Statut dans la barre de filtres rapides. Sur écran compact, le panneau des filtres de la vue accueille ces raccourcis. L’action list applique les filtres avant la pagination.

Copiez cette configuration complète à côté de product-config.ts. Utilisez () => exampleConfig pour getTableConfig en React, ou :config="exampleConfig" en Vue.

Agrandir ↗

Données de démonstration. Les modifications restent dans cet aperçu.

Agrandir ↗

Données de démonstration. Les modifications restent dans cet aperçu.

Proposer des règles de filtrage composées

Activez l’éditeur avancé sans barre rapide permanente. Saisissez la valeur numérique entière avant de l’appliquer ; l’adaptateur de requête traite les règles typées et leur combinaison ET/OU.

Copiez cette configuration complète à côté de product-config.ts. Utilisez () => exampleConfig pour getTableConfig en React, ou :config="exampleConfig" en Vue.

Agrandir ↗

Données de démonstration. Les modifications restent dans cet aperçu.

Agrandir ↗

Données de démonstration. Les modifications restent dans cet aperçu.

Facettes à côté des enregistrements

table.facets affiche un panneau de facettes à côté des enregistrements, dans tous les modes d’affichage sauf la vue Formulaire. Chaque colonne listée affiche ses valeurs avec leur nombre d’enregistrements, et un clic filtre la table :

table: {
  facets: {
    columns: ["category", { id: "tags", limit: 12 }],
    position: "left", // ou "right"
    defaultOpen: true, // les téléphones ouvrent le panneau en feuille depuis la barre d’outils
  },
}
  • Colonnes : colonnes de sélection, d’étiquette et de statut, colonnes à choix multiples et de tags, booléens (Oui et Non) et colonne parente d’une arborescence (ses dossiers, avec « Racine »). Une colonne est un identifiant ou { id, label?, limit?, sort?, showEmpty? }. Le panneau accepte aussi limit (8 valeurs avant « Afficher N de plus » et une recherche), showCounts (true par défaut), showZero (false par défaut) et width (256 px, de 180 à 480).

  • Filtrage : un clic écrit la règle qu’écrivent les menus de filtres : isAnyOf, ou contains pour les listes ; « Aucune valeur » écrit isEmpty seule. Les règles se combinent aux autres avec ET. Une sélection est un état de filtre ordinaire : elle va dans l’URL (<tableId>-advancedFilters), s’enregistre avec les vues et apparaît dans les menus de filtres, et une table à facettes affiche le menu de filtres avancés. Tant que la vue combine ses règles avec OU, le panneau le signale et n’y touche pas.

  • Comptages : la table interroge actions.aggregate comme un graphique (groupBy: [{ columnId }], metrics: [{ fn: "count" }]) avec la recherche et les filtres de la vue, sans la règle de la facette elle-même, pour qu’une facette continue de proposer ses autres valeurs. Sans aggregate, les comptages viennent des lignes que renvoie list (2 000 au plus, avec un avis au-delà), ou des lignes de la table (data en Vue). Une colonne de tags compte chaque tag une fois par enregistrement.

  • Clavier et téléphones : « Effacer » par facette et « Tout effacer » ; les flèches, Début et Fin passent d’une valeur à l’autre, Espace et Entrée en cochent une. Le bouton de la barre d’outils ([data-facets-toggle], aria-pressed, avec une pastille quand des facettes filtrent la vue) affiche et masque le panneau ; les téléphones l’ouvrent en feuille. Les facettes demandent les filtres de colonnes (enableColumnFilters différent de false).

Les libellés des facettes existent en anglais et en français, choisis selon la langue de la table, et lisent les traductions facets.<clé>.

Filtrer par dossier

Une table dont les lignes forment une arborescence filtre sa colonne parente avec un sélecteur de dossiers dans les menus de filtres, dans toutes les vues : la racine, ou un ou plusieurs dossiers (leur contenu direct). La règle est isAnyOf avec les identifiants des dossiers, ou isEmpty pour la racine, et se lit « Dans » suivi du nom du dossier. Une facette sur la colonne parente liste les mêmes dossiers avec leur nombre d’enregistrements. table.filetree.folderFilter: false désactive le sélecteur ; voir Les dossiers dans les autres vues.

Dates relatives

La valeur d’une règle de date peut être un jeton plutôt que des jours : $today, $yesterday, $tomorrow, $thisWeek, $lastWeek, $nextWeek, $thisMonth, $lastMonth, $nextMonth, $thisYear, $lastNDays et $nextNDays (N de 1 à 3660, aujourd’hui compris), $lastYear, $nextYear, et les périodes glissantes $last<N><Unité> et $next<N><Unité> avec une unité parmi Days, Weeks, Months ou Years, par exemple $last2Weeks ou $next3Months. Par exemple { "columnId": "due", "operator": "between", "values": "$thisWeek" } ; before et after avec $today se lisent « avant aujourd’hui » et « après aujourd’hui ». L’éditeur des règles de date les propose sous Relative, à côté de Date exacte et Période.

Les vues enregistrées, les liens et table.defaultFilters gardent les jetons : une vue garde le sens « cette semaine » chaque fois qu’on l’ouvre. La table les traduit en jours dans table.timeZone (sinon le fuseau de la personne) avant d’appeler list, aggregate ou les compteurs des facettes ; les semaines commencent le jour table.weekStartsOn (0 = dimanche à 6), sinon le premier jour de la langue. Un serveur qui exécute plus tard une requête enregistrée la résout avec resolveFilterTokens() (voir les actions serveur).

Enregistrements de la personne connectée

Une règle dont la valeur est $viewer correspond à table.viewerId, que l’hôte définit à l’identifiant de la personne connectée : { "columnId": "owner", "operator": "equals", "values": "$viewer" } se lit « qui me sont attribués » pour quiconque ouvre la vue. Sans viewerId, $viewer arrive tel quel au serveur, qui le remplace par la personne connectée.