Vega-Diagramm

Übersicht

Eine VegaChart ist eine von vielen möglichen Visualisierungen, die mit der Vega Visualization Grammar erstellt werden können. Dies ist eine deklarative Sprache zum Erstellen, Speichern und Freigeben interaktiver Visualisierungsdesigns. Mit Vega können Sie die visuelle Darstellung und das interaktive Verhalten einer Visualisierung im JSON-Format beschreiben und mit Canvas oder SVG webbasierte Ansichten generieren.

Wenn Sie ein VegaChart erstellen, müssen Sie in den Optionen eine Spezifikation für die Erstellung des Diagramms in der Vega-Visualisierungsgrammatik angeben. Unten finden Sie einige Beispiele für diese Spezifikationen. Weitere Beispiele finden Sie auf der Seite VegaChart-Beispiele.

Hinweis:In den Google Charts VegaChart können Sie jedes Vega-Diagramm zeichnen, das Sie mit einer Vega-JSON-Spezifikation angeben können (einschließlich aller Elemente in der Beispielgalerie). Zusätzliche Funktionen, die Aufrufe an die Viga API erfordern, sind jedoch noch nicht verfügbar.

Ein einfaches Beispiel für ein Balkendiagramm

Hier ein einfaches Beispiel für ein VegaChart, das ein Balkendiagramm zeichnet. Weitere Informationen finden Sie im ursprünglichen Beispiel, in einer detaillierten Anleitung und im Balkendiagramm im Vega-Diagrammeditor.

Dies stellt zwar eine weitere Möglichkeit dar, ein Balkendiagramm in Google Charts zu erstellen. Wir planen jedoch, alle Features der anderen Balken- und Säulendiagramme in einer neuen Implementierung basierend auf diesem VegaChart zu integrieren.

In diesem Beispiel wird die Option „data“ durch Folgendes ersetzt, die die vom Zeichenaufruf bereitgestellte „datatable“ als „Quelle“ für ein anderes Datenobjekt mit dem Namen „table“ verwendet. „table“ wird im weiteren Verlauf der Vega-Spezifikation verwendet.

  'data': [{'name': 'table', 'source': 'datatable'}],

<html>
  <head>
    <script src='https://www.gstatic.com/charts/loader.js'></script>
    <script>
      google.charts.load('upcoming', {'packages': ['vegachart']}).then(drawChart);

      function drawChart() {
        const dataTable = new google.visualization.DataTable();
        dataTable.addColumn({type: 'string', 'id': 'category'});
        dataTable.addColumn({type: 'number', 'id': 'amount'});
        dataTable.addRows([
          ['A', 28],
          ['B', 55],
          ['C', 43],
          ['D', 91],
          ['E', 81],
          ['F', 53],
          ['G', 19],
          ['H', 87],
        ]);

        const options = {
          "vega": {
            "$schema": "https://vega.github.io/schema/vega/v4.json",
            "width": 500,
            "height": 200,
            "padding": 5,

            'data': [{'name': 'table', 'source': 'datatable'}],

            "signals": [
              {
                "name": "tooltip",
                "value": {},
                "on": [
                  {"events": "rect:mouseover", "update": "datum"},
                  {"events": "rect:mouseout",  "update": "{}"}
                ]
              }
            ],

            "scales": [
              {
                "name": "xscale",
                "type": "band",
                "domain": {"data": "table", "field": "category"},
                "range": "width",
                "padding": 0.05,
                "round": true
              },
              {
                "name": "yscale",
                "domain": {"data": "table", "field": "amount"},
                "nice": true,
                "range": "height"
              }
            ],

            "axes": [
              { "orient": "bottom", "scale": "xscale" },
              { "orient": "left", "scale": "yscale" }
            ],

            "marks": [
              {
                "type": "rect",
                "from": {"data":"table"},
                "encode": {
                  "enter": {
                    "x": {"scale": "xscale", "field": "category"},
                    "width": {"scale": "xscale", "band": 1},
                    "y": {"scale": "yscale", "field": "amount"},
                    "y2": {"scale": "yscale", "value": 0}
                  },
                  "update": {
                    "fill": {"value": "steelblue"}
                  },
                  "hover": {
                    "fill": {"value": "red"}
                  }
                }
              },
              {
                "type": "text",
                "encode": {
                  "enter": {
                    "align": {"value": "center"},
                    "baseline": {"value": "bottom"},
                    "fill": {"value": "#333"}
                  },
                  "update": {
                    "x": {"scale": "xscale", "signal": "tooltip.category", "band": 0.5},
                    "y": {"scale": "yscale", "signal": "tooltip.amount", "offset": -2},
                    "text": {"signal": "tooltip.amount"},
                    "fillOpacity": [
                      {"test": "datum === tooltip", "value": 0},
                      {"value": 1}
                    ]
                  }
                }
              }
            ]
          }
        };

        const chart = new google.visualization.VegaChart(document.getElementById('chart-div'));
        chart.draw(dataTable, options);
      }
    </script>
  </head>

  <body>
    <div id="chart-div" style="width: 700px; height: 250px;"></div>
  </body>

</html>


Wird geladen

Der Paketname von google.charts.load lautet "vegachart".

google.charts.load("current", {packages: ["vegachart"]});

Der Klassenname der Visualisierung lautet google.visualization.VegaChart.

var visualization = new google.visualization.VegaChart(container);

Datenformat

Daten können auf ähnliche Weise an ein VegaChart übergeben werden wie über andere Google Charts unter Verwendung einer DataTable (oder DataView). Der Hauptunterschied besteht darin, dass sich VegaChart nicht auf die Reihenfolge der Spalten verlassen muss, um zu ermitteln, wie sie verwendet werden, sondern auch darauf, dass die ID jeder Spalte mit der erwarteten Darstellung für die angegebene Vega-Visualisierung übereinstimmt. Die folgende DataTable wird beispielsweise mit Spalten erstellt, die IDs für 'category' und 'amount' enthalten. In der „vega“-Option werden dieselben IDs verwendet, um auf diese Spalten zu verweisen.

Mit DataTable
        const dataTable = new google.visualization.DataTable();
        dataTable.addColumn({type: 'string', 'id': 'category'});
        dataTable.addColumn({type: 'number', 'id': 'amount'});
        dataTable.addRows([
          ['A', 28],
          ['B', 55],
          ['C', 43],
        ]);

        const options = {
          'vega': {
            ...
            // Here we create the Vega data object named 'datatable',
            // which will be passed in via the draw() call with a DataTable.
            'data': {'name': 'datatable'},

            'scales': [
              {
                'name': 'yscale',
                // Here is an example of how to use the 'amount' field from 'datatable'.
                'domain': {'data': 'datatable', 'field': 'amount'},
              }
            ]
          }
        };

        const chart = new google.visualization.VegaChart(
          document.getElementById('chart-div'));
        chart.draw(dataTable, options);
    
Inline-Daten aus Vega
        // A DataTable is required, but it may be empty.
        const dataTable = new google.visualization.DataTable();
        const options = {
          'vega': {
            // Here the data is specified inline in the Vega specification.
            "data": [
              {
               "name": "table",
                "values": [
                  {"category": "A", "amount": 28},
                  {"category": "B", "amount": 55},
                  {"category": "C", "amount": 43},
                ]
              }
            ],

            'scales': [
              {
                'name': 'yscale',
                // Here is how Vega normally uses the 'amount' field from 'table'.
                "domain": {"data": "table", "field": "category"},
              }
            ]
          }
        };

        const chart = new google.visualization.VegaChart(
          document.getElementById('chart-div'));
        chart.draw(dataTable, options);
    

Auf diese Weise kann jedoch nur eine solche DataTable an das VegaChart übergeben werden, während für einige Vega-Diagramme mehr als eine Datentabelle erforderlich ist. Wir werden diese Einschränkung in einer zukünftigen Version von Google Charts beheben.

In der Zwischenzeit können Sie bei Bedarf weitere Daten in der 'vega'-'data'-Option angeben, entweder durch Inline-Vorgang oder durch Laden aus einer URL. Beispiele dazu finden Sie unten.

Konfigurationsoptionen

Name
Diagrammbereich

Ein Objekt mit Mitgliedern zum Konfigurieren der Platzierung und Größe des Diagrammbereichs (wo das Diagramm selbst gezeichnet wird, ohne Achse und Legenden). Es werden zwei Formate unterstützt: eine Zahl oder eine Zahl gefolgt von %. Eine einfache Zahl ist ein Wert in Pixeln. Eine Zahl gefolgt von % ist ein Prozentsatz. Beispiel: chartArea:{left:20,top:0,width:'50%',height:'75%'}

Type: Objekt
Standard: null
Diagrammfläche.Unten

Gibt an, wie weit das Diagramm vom unteren Rand gezeichnet werden soll.

Typ: Zahl oder String
Standard: automatisch
Diagrammfläche links

Gibt an, wie weit das Diagramm vom linken Rand gezeichnet werden soll.

Typ: Zahl oder String
Standard: automatisch
ChartArea.right

Gibt an, wie weit das Diagramm vom rechten Rand gezeichnet werden soll.

Typ: Zahl oder String
Standard: automatisch
ChartArea.Oben

Gibt an, wie weit das Diagramm vom oberen Rand aus gezeichnet werden soll.

Typ: Zahl oder String
Standard: automatisch
Diagrammfläche.width

Breite des Diagrammbereichs.

Typ: Zahl oder String
Standard: automatisch
Diagrammfläche.height

Höhe des Diagrammbereichs.

Typ: Zahl oder String
Standard: automatisch
height

Höhe des Diagramms in Pixeln.

Typ:Zahl
Standard: Höhe des beinhaltenden Elements
width

Breite des Diagramms in Pixeln.

Typ: Zahl
Standard: Breite des beinhaltenden Elements

Methoden

Methode
draw(data, options)

Zeichnet das Diagramm. Im Diagramm sind weitere Methodenaufrufe erst möglich, nachdem das Ereignis ready ausgelöst wurde. Extended description

Rückgabetyp: Keine
getAction(actionID)

Gibt das Kurzinfo-Aktionsobjekt mit dem angeforderten actionID zurück.

Return Type: Objekt für die Rückgabe
getBoundingBox(id)

Gibt ein Objekt zurück, das links, oben, breit und hoch des Diagrammelements id ist. Das Format für id ist noch nicht dokumentiert. Es sind die Rückgabewerte von Ereignis-Handlern. Hier einige Beispiele:

var cli = chart.getChartLayoutInterface();

Höhe des Diagrammbereichs
cli.getBoundingBox('chartarea').height
Breite des dritten Balkens in der ersten Reihe eines Balken- oder Säulendiagramms
cli.getBoundingBox('bar#0#2').width
Begrenzungsrahmen im fünften Keil eines Kreisdiagramms
cli.getBoundingBox('slice#4')
Begrenzungsrahmen der Diagrammdaten eines vertikalen Diagramms (z.B. eines Spaltendiagramms):
cli.getBoundingBox('vAxis#0#gridline')
Begrenzungsrahmen der Diagrammdaten eines horizontalen Diagramms (z.B. Balkendiagramms):
cli.getBoundingBox('hAxis#0#gridline')

Die Werte beziehen sich auf den Container des Diagramms. Rufen Sie diese Methode auf, nachdem das Diagramm gezeichnet wurde.

Return Type: Objekt für die Rückgabe
getChartAreaBoundingBox()

Gibt ein Objekt zurück, das links, oben, breit und hoch des Diagramminhalts ist, d.h. ohne Labels und Legende:

var cli = chart.getChartLayoutInterface();

cli.getChartAreaBoundingBox().left
cli.getChartAreaBoundingBox().top
cli.getChartAreaBoundingBox().height
cli.getChartAreaBoundingBox().width

Die Werte beziehen sich auf den Container des Diagramms. Rufen Sie diese Methode auf, nachdem das Diagramm gezeichnet wurde.

Return Type: Objekt für die Rückgabe
getChartLayoutInterface()

Gibt ein Objekt zurück, das Informationen zur Platzierung des Diagramms und seiner Elemente auf dem Bildschirm enthält.

Die folgenden Methoden können für das zurückgegebene Objekt aufgerufen werden:

  • getBoundingBox
  • getChartAreaBoundingBox
  • getHAxisValue
  • getVAxisValue
  • getXLocation
  • getYLocation

Rufen Sie diese Methode auf, nachdem das Diagramm gezeichnet wurde.

Return Type: Objekt für die Rückgabe
getHAxisValue(xPosition, optional_axis_index)

Gibt den horizontalen Datenwert bei xPosition zurück. Dies ist ein Pixelversatz vom linken Rand des Diagrammcontainers. Kann negativ sein.

Beispiel: chart.getChartLayoutInterface().getHAxisValue(400).

Rufen Sie diese Methode auf, nachdem das Diagramm gezeichnet wurde.

Rückgabetyp: Nummer
getImageURI()

Gibt das serialisierte Diagramm als Bild-URI zurück.

Rufen Sie diese Methode auf, nachdem das Diagramm gezeichnet wurde.

Weitere Informationen finden Sie unter PNG-Diagramme drucken.

Rückgabetyp: String
getSelection()

Gibt ein Array der ausgewählten Diagrammentitäten zurück. Für dieses Diagramm kann jeweils nur eine Entität ausgewählt werden. Extended description.

Rückgabetyp:Array von Auswahlelementen
getVAxisValue(yPosition, optional_axis_index)

Gibt den vertikalen Datenwert bei yPosition zurück. Dies ist ein Pixelversatz vom oberen Rand des Diagrammcontainers. Kann negativ sein.

Beispiel: chart.getChartLayoutInterface().getVAxisValue(300).

Rufen Sie diese Methode auf, nachdem das Diagramm gezeichnet wurde.

Rückgabetyp: Nummer
getXLocation(dataValue, optional_axis_index)

Gibt die Pixel-x-Koordinate von dataValue relativ zum linken Rand des Containers des Diagramms zurück.

Beispiel: chart.getChartLayoutInterface().getXLocation(400).

Rufen Sie diese Methode auf, nachdem das Diagramm gezeichnet wurde.

Rückgabetyp: Nummer
getYLocation(dataValue, optional_axis_index)

Gibt die Pixel-y-Koordinate von dataValue relativ zum oberen Rand des Containers des Diagramms zurück.

Beispiel: chart.getChartLayoutInterface().getYLocation(300).

Rufen Sie diese Methode auf, nachdem das Diagramm gezeichnet wurde.

Rückgabetyp: Nummer
removeAction(actionID)

Entfernt die Kurzinfo-Aktion mit dem angeforderten actionID aus dem Diagramm.

Rückgabetyp: none
setAction(action)

Legt eine Kurzinfo-Aktion fest, die ausgeführt werden soll, wenn der Nutzer auf den Aktionstext klickt.

Für die Methode setAction wird ein Objekt als Aktionsparameter verwendet. Für dieses Objekt sollten drei Eigenschaften angegeben werden: id – die festgelegte ID, text – der Text, der in der Kurzinfo der Aktion angezeigt wird, und action – die Funktion, die ausgeführt werden soll, wenn ein Nutzer auf den Aktionstext klickt.

Alle Kurzinfo-Aktionen sollten vor dem Aufruf der draw()-Methode des Diagramms festgelegt werden. Erweiterte Beschreibung.

Rückgabetyp: none
setSelection()

Die angegebenen Diagrammentitäten werden ausgewählt. Die vorherige Auswahl wird abgebrochen. Für dieses Diagramm kann jeweils nur eine Entität ausgewählt werden. Extended description.

Rückgabetyp: Keine
clearChart()

Löscht das Diagramm und gibt alle zugehörigen Ressourcen frei.

Rückgabetyp: Keine

Ereignisse

Weitere Informationen zur Verwendung dieser Ereignisse finden Sie unter Grundlegende Interaktivität, Ereignisse verwalten und Auslösende Ereignisse.

Name
animationfinish

Wird ausgelöst, wenn die Umstellungsanimation beendet ist.

Eigenschaften: Keine
click

Wird ausgelöst, wenn der Nutzer in das Diagramm klickt Kann verwendet werden, um zu erkennen, wann auf den Titel, Datenelemente, Legendeneinträge, Achsen, Gitternetzlinien oder Labels geklickt wird.

Eigenschaften: targetID
error

Wird ausgelöst, wenn beim Rendern des Diagramms ein Fehler auftritt

Eigenschaften: ID, Nachricht
legendpagination

Wird ausgelöst, wenn der Nutzer auf Paginierungspfeile klickt Gibt den aktuellen nullbasierten Seitenindex und die Gesamtzahl der Seiten zurück.

Eigenschaften:currentPageIndex, totalPages
onmouseover

Wird ausgelöst, wenn der Nutzer den Mauszeiger auf eine visuelle Entität bewegt Gibt die Zeilen- und Spaltenindexe des entsprechenden Datentabellenelements zurück.

Attribute:Zeile, Spalte
onmouseout

Wird ausgelöst, wenn der Nutzer die Maus von einer visuellen Entität wegbewegt Gibt die Zeilen- und Spaltenindexe des entsprechenden Datentabellenelements zurück.

Attribute:Zeile, Spalte
ready

Das Diagramm ist bereit für externe Methodenaufrufe. Wenn Sie mit dem Diagramm interagieren und Methoden nach dem Zeichnen aufrufen möchten, sollten Sie einen Listener für dieses Ereignis einrichten, bevor Sie die Methode draw aufrufen. Sie sollten sie erst aufrufen, nachdem das Ereignis ausgelöst wurde.

Eigenschaften: Keine
select

Wird ausgelöst, wenn der Nutzer auf ein visuelles Element klickt. Rufen Sie getSelection() auf, um zu erfahren, was ausgewählt wurde.

Eigenschaften: Keine

Datenrichtlinie

Der gesamte Code und alle Daten werden im Browser verarbeitet und gerendert. Es werden keine Daten an einen Server gesendet.