§Gravity UI ChartKit ·

Composant React basé sur des plugins qui offre une interface de rendu unifiée pour plusieurs bibliothèques de graphiques. Vous enregistrez un ou plusieurs plugins et affichez les graphiques via <ChartKit type="..." data={...} /> — ChartKit distribue automatiquement au bon rendu.

Chaque rendu de plugin est chargé à la demande (lazy-loaded), de sorte que le code de la bibliothèque sous-jacente n'est téléchargé que lorsque ChartKit est effectivement rendu dans l'interface utilisateur. ChartKit gère également l'affichage des infobulles adaptées aux mobiles dès l'installation. Vous pouvez utiliser les plugins intégrés ou implémenter les vôtres.

Quand l'utiliser :

• Vous avez besoin de graphiques déclaratifs modernes (gravity-charts) ou de graphiques de séries temporelles / de surveillance (yagr)
• Vous avez besoin de plusieurs types de graphiques sous une API unique et cohérente
• Vous développez dans l'écosystème Gravity UI

Quand ne pas l'utiliser :

• Vous n'avez besoin que d'une seule bibliothèque de graphiques spécifique — préférez utiliser @gravity-ui/charts directement

§Table des matières

• Démarrage
• Développement

§Démarrage

§Prérequis

• React 16, 17 ou 18
• [@gravity-ui/uikit](https://github.com/gravity-ui/uikit) — dépendance pair requise (fournit le theming et les primitives UI)

§Installation

npm install @gravity-ui/chartkit @gravity-ui/uikit

§Styles

Importez les styles de @gravity-ui/uikit dans votre point d'entrée :

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

Pour des détails complets sur la configuration, consultez le guide des styles uikit.

§Utilisation de base

ChartKit utilise un registre global de plugins. Appelez settings.set une seule fois au point d'entrée de votre application pour enregistrer les plugins dont vous avez besoin. Lorsque <ChartKit type="..." /> est rendu, il recherche le plugin correspondant — si aucun n'est trouvé, une erreur est levée. Le rendu de chaque plugin est un composant React.lazy, son code est donc récupéré uniquement lorsque ChartKit apparaît pour la première fois dans l'interface utilisateur.

Vous pouvez enregistrer plusieurs plugins à la fois :

settings.set({plugins: [GravityChartsPlugin, YagrPlugin]});

Ou appelez settings.set plusieurs fois — il fusionne la liste des plugins au lieu de la remplacer.

Exemple de base :

import {ThemeProvider} from '@gravity-ui/uikit';
import ChartKit, {settings} from '@gravity-ui/chartkit';
import {GravityChartsPlugin} from '@gravity-ui/chartkit/gravity-charts';

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

settings.set({plugins: [GravityChartsPlugin]});

const data = {
  series: {
    data: [
      {
        type: 'line',
        name: 'Series',
        data: [
          {x: 0, y: 10},
          {x: 1, y: 25},
          {x: 2, y: 18},
          {x: 3, y: 30},
        ],
      },
    ],
  },
};

export default function App() {
  return (
    <ThemeProvider theme="light">
      <div style={{height: 300}}>
        <ChartKit type="gravity-charts" data={data} />
      </div>
    </ThemeProvider>
  );
}

ChartKit s'adapte à la taille de son parent — assurez-vous que le conteneur a une hauteur explicite.

§Développement

§Prérequis

• Node.js 22 (voir .nvmrc)
• npm 10 ou plus récent

§Configuration

Clonez le dépôt et installez les dépendances :

git clone https://github.com/gravity-ui/ChartKit.git
cd ChartKit
npm ci

§Lancement de Storybook

npm run start

Storybook sera disponible à l'adresse http://localhost:7007.

§Développement avec une dépendance locale

Pour travailler sur une dépendance (par exemple, @gravity-ui/charts) et voir vos modifications en direct dans Storybook sans la publier sur npm :

1. Lier le package local

# Dans votre clone local de @gravity-ui/charts :
git clone https://github.com/gravity-ui/charts.git
cd charts
npm ci
# faites vos modifications
npm run build
npm link

# Dans ChartKit :
npm link @gravity-ui/charts

2. Configurer la surveillance du package local

Créez un fichier .env.local à la racine de ChartKit (il est ignoré par git) :

LOCAL_PKG=@gravity-ui/charts

Cela indique à Vite de surveiller ce package dans node_modules et d'éviter de le pré-compiler. Après avoir reconstruit @gravity-ui/charts, Storybook se rechargera automatiquement.

Pour plusieurs packages, utilisez une liste séparée par des virgules :

LOCAL_PKG=@gravity-ui/charts,@gravity-ui/uikit

3. Lancer Storybook

npm run start

4. Restaurer le package d'origine

Lorsque vous avez terminé :

1. Commentez LOCAL_PKG dans .env.local
2. Exécutez npm install dans ChartKit — cela remplace le lien symbolique par la version du registre

# Dans ChartKit :
npm ci

§Lancement des tests

npm test

Les tests de régression visuelle s'exécutent dans Docker pour garantir des captures d'écran cohérentes entre les environnements :

npm run test:docker

Pour mettre à jour les captures d'écran de référence après des modifications intentionnelles de l'interface utilisateur :

npm run test:docker:update

§Contribution

Veuillez consulter le guide de contribution avant de soumettre une pull request.