§Gravity UI ChartKit ·

Plugin-basierte React-Komponente, die eine einheitliche Rendering-Schnittstelle für mehrere Charting-Bibliotheken bietet. Sie registrieren ein oder mehrere Plugins und rendern Diagramme über <ChartKit type="..." data={...} /> — ChartKit leitet automatisch an den richtigen Renderer weiter.

Jeder Plugin-Renderer wird lazy-geladen, sodass der zugrunde liegende Bibliotheks-Code nur dann heruntergeladen wird, wenn ChartKit tatsächlich in der Benutzeroberfläche gerendert wird. ChartKit kümmert sich außerdem standardmäßig um die mobilefreundliche Anzeige von Tooltips. Sie können die integrierten Plugins verwenden oder eigene implementieren.

Wann verwenden:

• Sie benötigen moderne deklarative Diagramme (gravity-charts) oder Zeitreihen-/Monitoring-Diagramme (yagr)
• Sie benötigen mehrere Diagrammtypen unter einer einzigen konsistenten API
• Sie entwickeln im Gravity UI-Ökosystem

Wann nicht verwenden:

• Sie benötigen nur eine spezifische Charting-Bibliothek — bevorzugen Sie die direkte Verwendung von @gravity-ui/charts

§Inhaltsverzeichnis

• Erste Schritte
• Aktualisieren von Charting-Paketen
• Entwicklung

§Erste Schritte

§Anforderungen

• React 16, 17 oder 18
• [@gravity-ui/uikit](https://github.com/gravity-ui/uikit) — erforderliche Peer-Abhängigkeit (stellt Theming und UI-Primitive bereit)

§Installation

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

§Styles

Importieren Sie die Styles von @gravity-ui/uikit in Ihrem Einstiegspunkt:

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

Ausführliche Informationen zur Einrichtung finden Sie im uikit styles guide.

§Grundlegende Verwendung

ChartKit verwendet eine globale Plugin-Registry. Rufen Sie settings.set einmal am Einstiegspunkt Ihrer App auf, um die benötigten Plugins zu registrieren. Wenn <ChartKit type="..." /> gerendert wird, sucht es nach dem passenden Plugin — wenn keines gefunden wird, wird ein Fehler ausgelöst. Der Renderer jedes Plugins ist eine React.lazy-Komponente, sodass deren Code nur dann abgerufen wird, wenn ChartKit zum ersten Mal in der Benutzeroberfläche erscheint.

Sie können mehrere Plugins gleichzeitig registrieren:

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

Oder rufen Sie settings.set mehrmals auf — es wird die Plugin-Liste zusammengeführt, anstatt sie zu ersetzen.

Grundlegendes Beispiel:

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 passt sich an die Größe seines Elternelements an — stellen Sie sicher, dass der Container eine explizite Höhe hat.

§Aktualisieren von Charting-Paketen

ChartKit bündelt zwei Gravity UI Charting-Bibliotheken als Abhängigkeiten:

• @gravity-ui/charts — treibt das gravity-charts-Plugin an
• @gravity-ui/yagr — treibt das yagr-Plugin an

Wenn Sie eine neuere Version eines dieser Pakete benötigen, eröffnen Sie eine Package update request Issue und wählen Sie die benötigten Pakete aus. Die Maintainer werden die ausgewählten Pakete aktualisieren und das Update veröffentlichen.

§Entwicklung

§Voraussetzungen

• Node.js 22 (siehe .nvmrc)
• npm 10 oder neuer

§Einrichtung

Klonen Sie das Repository und installieren Sie die Abhängigkeiten:

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

§Storybook ausführen

npm run start

Storybook ist unter http://localhost:7007 verfügbar.

§Entwicklung mit einer lokalen Abhängigkeit

Um an einer Abhängigkeit (z. B. @gravity-ui/charts) zu arbeiten und Ihre Änderungen live in Storybook zu sehen, ohne sie auf npm zu veröffentlichen:

1. Lokales Paket verlinken

# In Ihrem lokalen Klon von @gravity-ui/charts:
git clone https://github.com/gravity-ui/charts.git
cd charts
npm ci
# Nehmen Sie Ihre Änderungen vor
npm run build
npm link

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

2. Lokales Paket-Watching konfigurieren

Erstellen Sie eine .env.local-Datei im ChartKit-Root-Verzeichnis (sie wird von .gitignore ignoriert):

LOCAL_PKG=@gravity-ui/charts

Dies weist Vite an, dieses Paket in node_modules zu überwachen und es nicht vorab zu bündeln. Nach dem erneuten Erstellen von @gravity-ui/charts wird Storybook automatisch neu geladen.

Für mehrere Pakete verwenden Sie eine durch Kommas getrennte Liste:

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

3. Storybook starten

npm run start

4. Ursprüngliches Paket wiederherstellen

Wenn Sie fertig sind:

1. Kommentieren Sie LOCAL_PKG in .env.local aus
2. Führen Sie npm install in ChartKit aus — dies ersetzt den Symlink durch die Registry-Version

# In ChartKit:
npm ci

§Tests ausführen

npm test

Visuelle Regressionstests werden in Docker ausgeführt, um konsistente Screenshots über verschiedene Umgebungen hinweg zu gewährleisten:

npm run test:docker

Um die Referenz-Screenshots nach beabsichtigten UI-Änderungen zu aktualisieren:

npm run test:docker:update

§Mitwirken

Bitte beachten Sie die contributing guide, bevor Sie einen Pull Request einreichen.

§Lizenz

Unter der MIT-Lizenz vertrieben. Details finden Sie in LICENSE.

§Für KI-Agenten

Eine React-Komponente zum Verteilen von Plugins, die Diagramme aus mehreren Gravity UI-Diagrammbibliotheken über eine einzige <ChartKit type="..." data={...} />-API rendert. Verwenden Sie sie, wenn Sie einen einzigen, lazy-loading-fähigen Einstiegspunkt für gemischte Diagrammtypen benötigen, anstatt jede Diagrammbibliothek direkt zu importieren.

§Wann verwenden

• Rendern von mehr als einer Diagramm-Engine (z. B. gravity-charts + yagr) hinter einer einheitlichen Komponente.
• Lazy-Loading von Diagramm-Bundles – der Renderer jedes Plugins ist React.lazy, sodass der Code einer Bibliothek nur dann abgerufen wird, wenn sein Diagrammtyp tatsächlich angezeigt wird.
• Bündeln von Diagrammen in einer Gravity UI-App, die mobilfreundliche Tooltips und einheitliches Theming "out of the box" wünscht.

§Wann nicht verwenden

• Für nur einen Diagrammtyp importieren Sie @gravity-ui/charts (allgemein) oder @gravity-ui/yagr (hochperformante Zeitreihen) direkt – die Plugin-Registrierung ist ein Overhead für eine Engine.
• Zum Erstellen eines Dashboard-Gitters von Widgets verwenden Sie @gravity-ui/dashkit – ChartKit rendert ein Diagramm; DashKit ordnet viele Widgets an.

§Häufige Fallstricke

• Rendern von <ChartKit> vor settings.set({plugins: [...]}) – die globale Plugin-Registrierung muss am App-Einstiegspunkt gefüllt werden; ein nicht registrierter type löst zur Renderzeit einen Fehler aus.
• Halluzinierte Prop chartType / library – die Dispatch-Prop ist type (z. B. type="gravity-charts"), und die Daten sind data.
• Vergessen einer Container-Höhe – ChartKit füllt sein übergeordnetes Element; ohne eine explizite Höhe auf dem Wrapper kollabiert das Diagramm auf Null.
• Erwarten, dass Plugins gebündelt sind – Plugin-Renderer (@gravity-ui/chartkit/gravity-charts, .../yagr) sind lazy; das erste Rendern eines Typs ruft sein Bundle ab.
• Fehlender Import der uikit-Styles – das Theming hängt von @gravity-ui/uikit/styles/styles.css ab; ohne diesen werden Diagramme ungestylt gerendert.

§Dokumentation für KI-Agenten

Agentenlesbare Dokumentation für die installierte Version befindet sich in node_modules/@gravity-ui/chartkit/build/docs/INDEX.md.