Introduction à l'intégration de la bibliothèque

L'outil React-Awesome-Query-Builder offre une méthode efficace pour implémenter des systèmes de recherche avancée au sein des applications web modernes. Il permet aux développeurs de générer automatiquement des interfaces graphiques pour assembler des conditions complexes, évitant ainsi la codification manuelle de chaque règle logique. La bibliothèque est conçue pour s'intégrer harmonieusement avec diverses bibliothèques de composants UI.

Conditions préalables et installation

Avant de procéder à l'implémentation, assurez-vous que votre environnement de développement répond aux spécifications suivantes :

• Environnement React版本 : Version 16.x minimum recommandée
• Gestionnaire de paquets : npm ou yarn configuré
• Runtime : Node.js version 14 ou supérieure

Pour ajouter le module à votre projet actuel, exécutez la commande suivante dans le terminal :

npm install react-awesome-query-builder --save-dev

Ou si vous préférez Yarn :

yarn add react-awesome-query-builder -D

Une fois installé, importez le composant principal et son fichier de styles global dans le fichier racine de votre application (ex: Main.tsx) :

import { QueryBuilder } from 'react-awesome-query-builder';
import 'react-awesome-query-builder/lib/css/styles.css';

Adaptation visuelle via les thèmes

Ce moteur de requête supporte nativement plusieurs designs afin de respecter la charte graphique existante. Les packages disponibles incluent :

• Bootstrap : Pour les projets basés sur le grid classique
• Material UI : Style Google Materail Design
• Ant Design : Interface utilisateur cohérente et réactive
• Fluent UI : Standards Microsoft

Pour utiliser l'interface Ant Design, remplacez l'import par chemin spécifique :

import { QueryBuilder } from 'react-awesome-query-builder/antd';
import 'react-awesome-query-builder/antd/css/styles.css';

Définition de la structure des données

Le comportement du filtre dépend entièrement de la définition des champs autorisés. Créez un objet schématique décrivant chaque colonne disponible, son type de donnée et les opérateurs applicables.

const schemaFiltres = {
  categorie: {
    label: 'Catégorie Produit',
    type: 'select',
    values: ['Electronique', 'Vêtements', 'Livre'],
    operators: ['equal', 'not_equal']
  },
  prix: {
    label: 'Montant en Euros',
    type: 'number',
    operators: ['between', 'greater_than', 'less_than']
  },
  status: {
    label: 'Statut Commande',
    type: 'boolean',
    operators: ['equal', 'not_equal']
  }
};

Implémentation du composant React

L'instance principale se rend comme n'importe quel autre composant React. Gèrez l'état local pour stocker la configuration actuelle du requêteur.

function InterfaceRecherche() {
  const [etatReq, setEtatReq] = useState({});

  const processeurChangement = (nouvelleRequete) => {
    // Conversion si nécessaire vers JS plain
    setEtatReq(() => nouvelleRequete?.toJS ? nouvelleRequete.toJS() : nouvelleRequete);
  };

  return (
    <div classname="conteneur-filtres">
      <querybuilder depthlimit:="" fields="{schemaFiltres}" onchange="{processeurChangement}" query="{etatReq}" settings="{{" showerrormessage:="" true=""></querybuilder>
    </div>
  );
}

Extraction des résultats pour le Backend

La librairie inclut des fonctions utilitaires pour transformer la configuration visuelle en formats exploitables par l'API serveur.

Exportation vers JSON Standard

import { serializeQuery } from 'react-awesome-query-builder';

const payloadJson = serializeQuery(etatReq, { format: 'json' });

Conversion en requête SQL brute

Utile pour les environnements utilisant directement des bases de données relationnelles.

const conditionSql = serializeQuery(etatReq, { format: 'sql' });
// Résultat attendu : "status = 1 AND prix BETWEEN 10 AND 50"

Intégration ElasticSearch

Pour les moteurs de recherche full-text.

const reqElastic = serializeQuery(etatReq, { format: 'elastic' });

Personnnalisation avancée

Vérification manuelle des entrées

Il est possible d'inclure une fonction de validation propre pour s'assurer que les valeurs saisies respectent des contraintes spécifiques avant soumission.

schemaFiltres.telephone = {
  label: 'Numéro',
  type: 'text',
  validateValue: (val) => val.length === 10 ? null : 'Le numéro doit faire 10 chiffres'
};

Ajout d'opérateurs personnalisés

Pour gérer des logiques métier absentes de la base, ajoutez vos propres définitions dans les configurations globales.

const optionGlobal = {
  op_custom: {
    name: 'Débutant par',
    valueName: 'prefix',
    widget: 'text'
  }
};

Recommandations techniques

• Gestion du Layout : Entourez toujours le composant d'une div parent avec une largeur définie pour supporter le système de redimensionnement interne.
• Composants Formulaires : Si le filtre est intégré dans un formulaire, interceptez l'événement submit natif via e.preventDefault() sur les boutons d'action pour éviter les rechargements inattendus.
• Mobile First : Appliquez des media queries CSS pour réduire la taille de la police et l'espacement interne lorsque l'écran est inférieur à 768px.