Bibliotheken laden

Auf dieser Seite wird beschrieben, wie die Google Chart-Bibliotheken geladen werden.

Einfache Bibliothek wird geladen

Abgesehen von allen Ausnahmen sollten alle Webseiten mit Google Charts die folgenden Zeilen im <head> der Webseite enthalten:

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
  ...
</script>

In der ersten Zeile dieses Beispiels wird der Lader selbst geladen. Sie können den Lader nur einmal laden, unabhängig davon, wie viele Diagramme Sie zeichnen möchten. Nachdem Sie den Lader geladen haben, können Sie die Funktion google.charts.load ein- oder mehrmals aufrufen, um Pakete für bestimmte Diagrammtypen zu laden.

Das erste Argument für google.charts.load ist der Versionsname oder die Versionsnummer als String. Wenn Sie 'current' angeben, wird die letzte offizielle Version von Google Charts geladen. Wenn Sie den Kandidaten für den nächsten Release ausprobieren möchten, verwenden Sie stattdessen 'upcoming'. Im Allgemeinen wird es nur sehr wenige Unterschiede zwischen den beiden geben. Sie sind völlig identisch, es sei denn, eine neue Version wird veröffentlicht. Ein häufiger Grund für die Verwendung von upcoming ist, dass du einen neuen Diagrammtyp oder eine neue Funktion testen möchtest, die Google in den nächsten ein oder zwei Monaten veröffentlicht. Wir kündigen bevorstehende Veröffentlichungen in unserem Forum an und empfehlen, sie auszuprobieren, wenn sie angekündigt wurden, um sicherzustellen, dass Änderungen an Ihren Diagrammen akzeptabel sind.

Im obigen Beispiel wird davon ausgegangen, dass Sie corechart (Bar, Spalte, Linie, Fläche, abgestufte Fläche, Blase, Kuchen, Ring, Kombination, Kerzen-Strich, Histogramm, Streuung) darstellen lassen möchten. Wenn Sie einen anderen oder zusätzlichen Diagrammtyp verwenden möchten, ersetzen Sie corechart oben durch den entsprechenden Paketnamen (z.B. {packages: ['corechart', 'table', 'sankey']}. Sie finden den Paketnamen im Abschnitt „Wird geladen“ auf der Dokumentationsseite für jedes Diagramm.

In diesem Beispiel wird außerdem davon ausgegangen, dass Sie eine JavaScript-Funktion namens drawChart auf Ihrer Webseite definiert haben. Sie können dieser Funktion einen beliebigen Namen geben. Sie muss jedoch global eindeutig sein und definiert sein, bevor Sie in Ihrem Aufruf von google.charts.setOnLoadCallback darauf verweisen.

Hinweis: In früheren Versionen von Google Charts wurde Code verwendet, der sich von den oben genannten unterscheidet, um die Bibliotheken zu laden. Wie Sie Ihre bestehenden Diagramme so aktualisieren, dass sie den neuen Code verwenden, erfahren Sie unter Bibliotheksladecode aktualisieren.

Hier ein vollständiges Beispiel für ein Kreisdiagramm, das die grundlegende Ladetechnik verwendet:

<head>
  <script src="https://www.gstatic.com/charts/loader.js"></script>
  <script>
    google.charts.load('current', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);

    function drawChart() {
      // Define the chart to be drawn.
      var data = new google.visualization.DataTable();
      data.addColumn('string', 'Element');
      data.addColumn('number', 'Percentage');
      data.addRows([
        ['Nitrogen', 0.78],
        ['Oxygen', 0.21],
        ['Other', 0.01]
      ]);

      // Instantiate and draw the chart.
      var chart = new google.visualization.PieChart(document.getElementById('myPieChart'));
      chart.draw(data, null);
    }
  </script>
</head>
<body>
  <!-- Identify where the chart should be drawn. -->
  <div id="myPieChart"/>
</body>

Details werden geladen

Zuerst muss der Lader selbst geladen werden. Dies erfolgt in einem separaten script-Tag mit src="https://www.gstatic.com/charts/loader.js". Dieses Tag kann sich entweder im head oder body des Dokuments befinden oder dynamisch in das Dokument eingefügt werden, während es geladen wird oder nachdem der Ladevorgang abgeschlossen wurde.

<script src="https://www.gstatic.com/charts/loader.js"></script>

Nachdem der Lader geladen wurde, können Sie google.charts.load aufrufen. An dieser Stelle kann es sich in einem script-Tag im head oder body des Dokuments befinden. Du kannst es aufrufen, während das Dokument noch geladen wird, oder nach dem Laden.

Ab Version 45 kann du google.charts.load mehrmals aufrufen, um zusätzliche Pakete zu laden. Das ist aber sicherer, wenn du das vermeiden kannst. Du musst jedes Mal dieselbe Versionsnummer und Sprache angeben.

Sie können jetzt den alten JSAPI-URL-Parameter autoload verwenden. Beim Wert dieses Parameters müssen jedoch die strenge JSON-Formatierung und URL-Codierung verwendet werden. In JavaScript kannst du die Codierung von jsonObject mit dem folgenden Code vornehmen: encodeURIComponent(JSON.stringify(jsonObject)).

Einschränkungen

Wenn Sie Versionen vor Version 45 verwenden, gibt es einige kleinere, aber wichtige Einschränkungen beim Laden von Google-Diagrammen:

  1. Sie können google.charts.load nur einmal aufrufen. Sie können aber alle Pakete auflisten, die Sie in einem einzigen Aufruf benötigen, sodass Sie keine separaten Aufrufe tätigen müssen.
  2. Wenn Sie einen ChartWrapper verwenden, müssen Sie alle erforderlichen Pakete explizit laden und können nicht darauf verzichten, dass sie automatisch für Sie geladen werden.
  3. Für Geochart und Map Chart müssen Sie sowohl den alten als auch den neuen Bibliotheken laden. Dies gilt nur für Versionen vor Version 45. Bei späteren Versionen sollte dies nicht geschehen.
    <script src="https://www.gstatic.com/charts/loader.js"></script>
    <script src="https://www.google.com/jsapi"></script>

Name oder Nummer der Ladeversion

Das erste Argument Ihres google.charts.load-Aufrufs ist der Versionsname oder die Versionsnummer. Derzeit gibt es nur zwei Sonderversionen und mehrere Sonderversionen.

aktuell
Dies bezieht sich auf den neuesten offiziellen Release, der sich jedes Mal ändert, wenn wir einen neuen Release veröffentlichen. Idealerweise ist diese Version gut getestet und fehlerfrei. Sie können jedoch auch eine bestimmte eingefrorene Version angeben, wenn Sie zufrieden sind.
Anstehend
Dies gilt für den nächsten Release, solange er noch getestet wird, bevor er der offizielle aktuelle Release wird. Bitte testen Sie diese Version regelmäßig, damit Sie so schnell wie möglich erfahren, ob es Probleme gibt, die behoben werden müssen, bevor diese Version zum offiziellen Release wird.

Wenn wir neue Versionen von Google Charts veröffentlichen, gibt es einige große Änderungen, wie etwa neue Diagrammtypen. Andere kleine Änderungen wie Verbesserungen an der Darstellung oder am Verhalten vorhandener Diagramme

Viele Google Chart-Ersteller optimieren das Erscheinungsbild ihrer Diagramme, bis es genau das ist, was sie wollen. Einige Creator fühlen sich wohler, wenn sie wissen, dass sich ihre Diagramme nie ändern werden, unabhängig davon, welche Verbesserungen wir in Zukunft vornehmen. Für diese Nutzer unterstützen wir eingefrorene Google Charts.

Eingefrorene Diagrammversionen sind durch die Nummer gekennzeichnet und werden in unseren offiziellen Releases beschrieben. Um eine eingefrorene Version zu laden, ersetzen Sie current oder upcoming im Aufruf von google.charts.load durch die eingefrorene Versionsnummer:

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
    google.charts.load('43', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);
    ...
</script>

Wir gehen davon aus, dass die eingefrorenen Versionen auf unbestimmte Zeit verfügbar bleiben, auch wenn sie aus Sicherheitsgründen möglicherweise eingefroren sind. In der Regel bieten wir keinen Support für eingefrorene Versionen, es sei denn, Sie schlagen ein Upgrade auf eine neuere Version vor.

Einstellungen laden

Der zweite Parameter in Ihrem Aufruf von google.charts.load ist ein Objekt zum Festlegen von Einstellungen. Die folgenden Properties werden für Einstellungen unterstützt.

Pakete
Ein Array von null oder mehr Paketen. Jedes geladene Paket enthält den Code, der für eine Reihe von Funktionen erforderlich ist, normalerweise eine Art von Diagramm. Die Pakete, die Sie laden müssen, sind in der Dokumentation für jeden Diagrammtyp aufgeführt. Sie können die Angabe von Paketen vermeiden, wenn Sie einen ChartWrapper verwenden, um die erforderlichen Elemente automatisch zu laden.
language
Der Code für die Sprache oder Sprache, die zur Anpassung von Text im Diagramm verwendet werden soll. Weitere Informationen
callback
Eine Funktion, die aufgerufen wird, nachdem die Pakete geladen wurden. Alternativ können Sie diese Funktion angeben, indem Sie google.charts.setOnLoadCallback wie im obigen Beispiel aufrufen. Weitere Informationen findest du unter Callback.
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
MapsApiKey
(v45) Mit dieser Einstellung können Sie einen Schlüssel angeben, den Sie mit Geodiagramm und Kartendiagramm verwenden können. Wir empfehlen Ihnen, stattdessen das Standardverhalten zu verwenden, das zu einer Drosselung des Dienstes für Ihre Nutzer führen kann. Informationen zum Einrichten eines eigenen Schlüssels für die Verwendung des Dienstes „Google Maps JavaScript API“ finden Sie hier: Schlüssel/Authentifizierung anfordern Der Code sieht in etwa so aus:
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
sicherer Modus
(v47) Wird die Richtlinie auf „true“ gesetzt, werden sie in allen Diagrammen und Kurzinfos, die HTML aus von Nutzern gelieferten Daten generieren, bereinigt, indem Elemente mit unsicheren Elementen und Attributen entfernt werden. Alternativ (ab Version 49) kann die Bibliothek im abgesicherten Modus über eine Verknüpfung geladen werden, die dieselben Ladeeinstellungen akzeptiert, aber immer die „aktuelle“ Version lädt:
  google.charts.safeLoad({ packages: ['corechart'] });

Sprachen

Sprachen werden zur Anpassung von Text für ein Land oder eine Sprache verwendet. Dies wirkt sich auf die Formatierung von Werten wie Währungen, Datumsangaben und Zahlen aus.

Standardmäßig wird in den Google Charts die Sprache „en“ geladen. Sie können diese Standardeinstellung überschreiben, indem Sie in den Ladeeinstellungen explizit ein Gebietsschema angeben.

Wenn Sie ein Diagramm laden möchten, das für eine bestimmte Sprache formatiert ist, verwenden Sie die Einstellung language so:

  // Load Google Charts for the Japanese locale.
  google.charts.load('current', {'packages':['corechart'], 'language': 'ja'});

Unter diesem Link finden Sie ein Live-Beispiel.

Rückruf

Bevor Sie eines der von google.charts.load geladenen Pakete verwenden können, müssen Sie warten, bis der Ladevorgang abgeschlossen ist. Es reicht nicht aus, einfach zu warten, bis das Dokument vollständig geladen wurde. Da es einige Zeit dauern kann, bis das Laden abgeschlossen ist, müssen Sie eine Callback-Funktion registrieren. Dafür gibt es drei Möglichkeiten. Gib entweder eine callback-Einstellung in deinem google.charts.load-Aufruf an oder rufe setOnLoadCallback auf und übergib eine Funktion als Argument oder verwende das Versprechen, das durch den Aufruf von google.charts.load zurückgegeben wird.

Beachten Sie, dass Sie für all diese Möglichkeiten eine Funktionsdefinition angeben müssen, anstatt die Funktion aufzurufen. Die von Ihnen angegebene Funktionsdefinition kann entweder eine benannte Funktion (also nur deren Name) oder eine anonyme Funktion sein. Wenn die Pakete vollständig geladen wurden, wird diese Callback-Funktion ohne Argumente aufgerufen. Der loader wartet außerdem, bis das Dokument fertig geladen ist, bevor der Callback aufgerufen wird.

Wenn Sie mehr als ein Diagramm zeichnen möchten, können Sie entweder mehrere Callback-Funktionen mit setOnLoadCallback registrieren oder sie zu einer Funktion kombinieren. Weitere Informationen zum Zeichnen mehrerer Diagramme auf einer Seite

  google.charts.setOnLoadCallback(drawChart1);
  google.charts.setOnLoadCallback(drawChart2);
  // OR
  google.charts.setOnLoadCallback(
    function() { // Anonymous function that calls drawChart1 and drawChart2
         drawChart1();
         drawChart2();
      });

Callback über Versprechen

Eine andere Möglichkeit zum Registrieren deines Callbacks ist die Verwendung des Versprechens, das vom google.charts.load-Aufruf zurückgegeben wird. Fügen Sie dazu der Methode then() einen Aufruf mit dem folgenden Code hinzu.

  google.charts.load('upcoming', {packages: ['corechart']}).then(drawChart);

Ein Vorteil des Versprechens besteht darin, dass du ganz einfach mehr Diagramme zeichnen kannst, indem du mehr .then(anotherFunction)-Aufrufe verkettest. Durch das Versprechen wird auch der Callback mit den für diesen Callback erforderlichen spezifischen Paketen verknüpft. Dies ist wichtig, wenn du weitere Pakete mit einem anderen Aufruf von google.charts.load() laden möchtest.

Ladecode der Bibliothek aktualisieren

In früheren Versionen von Google Charts wurde zum Laden der Bibliotheken ein anderer Code verwendet. In der folgenden Tabelle sind die alten und die neuen Bibliotheksladecodes aufgeführt.

Alter Bibliotheks-Ladecode
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
  google.load("visualization", "1", {packages:["corechart"]});
  google.setOnLoadCallback(drawChart);
</script>
      
Neuer Bibliotheks-Ladecode
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>
      

Wenn Sie Ihre vorhandenen Diagramme aktualisieren möchten, können Sie den alten Code der Bibliothek durch den neuen Code ersetzen. Beachten Sie jedoch die oben beschriebenen Einschränkungen beim Laden von Bibliotheken.