GraphicWalker

GraphicWalker est le composant principal qui fournit une interface complète d'exploration interactive des données avec la construction de graphiques par glisser-déposer, la gestion des champs et plusieurs onglets de graphiques.

import { GraphicWalker } from '@kanaries/graphic-walker';

Props

Props de données

Prop	Type	Requis	Description
`data`	`Record<string, any>[]`	Oui*	Tableau d'enregistrements de données. Utilisé pour le calcul côté client.
`fields`	`IMutField[]`	Oui	Définitions de champs décrivant chaque colonne de vos données.
`computation`	`IComputationFunction`	Oui*	Fonction de calcul côté serveur. Alternative à `data`.
`computationTimeout`	`number`	Non	Délai d'expiration en ms pour les requêtes de calcul.

*Fournissez soit data (côté client) soit computation (côté serveur), pas les deux.

Props de configuration des graphiques

Prop	Type	Par défaut	Description
`chart`	`IChart[]`	`undefined`	Spécifications de graphiques préconfigurés à charger.
`defaultConfig`	`{ config?: Partial<IVisualConfigNew>; layout?: Partial<IVisualLayout> }`	`undefined`	Configuration par défaut appliquée aux nouveaux graphiques.
`defaultRenderer`	`'vega-lite' \| 'observable-plot'`	`'vega-lite'`	Moteur de rendu par défaut pour les nouveaux graphiques.

Props d'apparence

Prop	Type	Par défaut	Description
`appearance`	`'media' \| 'light' \| 'dark'`	`'media'`	Réglage du mode sombre. `'media'` suit la préférence système.
`vizThemeConfig`	`IThemeKey \| GWGlobalConfig`	`undefined`	Thème de rendu des graphiques. Options intégrées : `'vega'`, `'g2'`, `'streamlit'`.
`uiTheme`	`IUIThemeConfig`	`undefined`	Schéma de couleurs personnalisé de l'interface pour les modes clair et sombre.

Props de contrôle de l'interface

Prop	Type	Par défaut	Description
`hideChartNav`	`boolean`	`false`	Masque la navigation par onglets des graphiques, limitant à un seul graphique.
`hideSegmentNav`	`boolean`	`false`	Masque la navigation des segments données/visualisation.
`hideProfiling`	`boolean`	`false`	Masque le profilage des champs (aperçus de distribution).
`toolbar`	`{ extra?: ToolbarItemProps[]; exclude?: string[] }`	`undefined`	Personnalise la barre d'outils — ajouter des boutons supplémentaires ou exclure les boutons intégrés.

Props de fonctionnalités de données

Prop	Type	Par défaut	Description
`scales`	`IChannelScales`	`undefined`	Configurations d'échelles personnalisées pour les canaux visuels.
`geographicData`	`IGeographicData & { key: string }`	`undefined`	Données GeoJSON/TopoJSON pour les visualisations géographiques.
`geoList`	`IGeoDataItem[]`	`undefined`	Liste des jeux de données géographiques disponibles à la sélection.
`experimentalFeatures`	`{ computedField?: boolean }`	`undefined`	Active les fonctionnalités expérimentales comme les champs calculés.

Props i18n

Prop	Type	Par défaut	Description
`i18nLang`	`string`	`undefined`	Code de langue (ex. `'en-US'`, `'zh-CN'`, `'ja-JP'`).
`i18nResources`	`Record<string, Record<string, string>>`	`undefined`	Ressources de traduction personnalisées.

Props Ref et État

Prop	Type	Description
`ref`	`React.Ref<IGWHandler>`	Ref pour accéder à l'API du gestionnaire (exporter des graphiques, naviguer entre les onglets, etc.).
`storeRef`	`React.RefObject<CommonStore>`	Ref vers le store d'état interne.
`keepAlive`	`boolean \| string`	Maintient l'état du composant en vie lorsqu'il est démonté. Passez une chaîne comme clé unique pour les instances multiples.
`onMetaChange`	`(fid: string, meta: Partial<IMutField>) => void`	Callback lorsque les métadonnées d'un champ changent.

Gestion des erreurs

Prop	Type	Description
`onError`	`(err: Error) => void`	Callback pour la gestion des erreurs.

Styles

Prop	Type	Description
`className`	`string`	Classe CSS appliquée à l'élément racine.
`style`	`React.CSSProperties`	Styles en ligne appliqués à l'élément racine.

Gestionnaire Ref (IGWHandler)

Accédez au gestionnaire via une ref React pour contrôler le composant de manière programmatique :

import { useRef } from 'react';
import { GraphicWalker } from '@kanaries/graphic-walker';
import type { IGWHandler } from '@kanaries/graphic-walker';
 
function App() {
  const gwRef = useRef<IGWHandler>(null);
 
  return <GraphicWalker ref={gwRef} data={data} fields={fields} />;
}

Propriétés et méthodes du gestionnaire

Membre	Type	Description
`chartCount`	`number`	Nombre total d'onglets de graphiques.
`chartIndex`	`number`	Index de l'onglet de graphique actuellement sélectionné.
`openChart(index)`	`(index: number) => void`	Basculer vers un onglet de graphique spécifique.
`renderStatus`	`'computing' \| 'rendering' \| 'idle' \| 'error'`	Statut de rendu actuel du graphique actif.
`onRenderStatusChange(cb)`	`(cb: Function) => () => void`	Écouter les changements de statut de rendu. Retourne une fonction de nettoyage.
`exportChart(mode?)`	`(mode?: 'svg' \| 'data-url') => Promise<IChartExportResult>`	Exporter le graphique actuel. Par défaut `'svg'`.
`exportChartList(mode?)`	`(mode?: 'svg' \| 'data-url') => AsyncGenerator`	Générateur asynchrone qui produit les données d'export de chaque graphique.

Exemple d'export

async function handleExport() {
  if (!gwRef.current) return;
 
  // Export current chart as SVG
  const result = await gwRef.current.exportChart('svg');
  console.log(result.title, result.charts);
 
  // Export all charts
  for await (const item of gwRef.current.exportChartList('data-url')) {
    console.log(`Chart ${item.index + 1}/${item.total}:`, item.data.title);
  }
}

Exemples

Explorateur de base

import { GraphicWalker } from '@kanaries/graphic-walker';
 
function Explorer({ data, fields }) {
  return <GraphicWalker data={data} fields={fields} />;
}

Avec mode sombre et thème

<GraphicWalker
  data={data}
  fields={fields}
  appearance="dark"
  vizThemeConfig="streamlit"
/>

Avec personnalisation de la barre d'outils

<GraphicWalker
  data={data}
  fields={fields}
  toolbar={{
    exclude: ['export_chart'],
    extra: [
      {
        key: 'custom-save',
        label: 'Save',
        icon: SaveIcon,
        onClick: handleSave,
      },
    ],
  }}
/>

Calcul côté serveur

import { GraphicWalker } from '@kanaries/graphic-walker';
import type { IComputationFunction } from '@kanaries/graphic-walker';
 
const computation: IComputationFunction = async (payload) => {
  const response = await fetch('/api/compute', {
    method: 'POST',
    body: JSON.stringify(payload),
    headers: { 'Content-Type': 'application/json' },
  });
  return response.json();
};
 
function App() {
  return (
    <GraphicWalker
      computation={computation}
      fields={fields}
    />
  );
}

Premiers pas GraphicRenderer