Bibliotheken laden

Auf dieser Seite wird beschrieben, wie Sie die Google-Diagrammbibliotheken laden.

Einfaches Laden der Bibliothek

Abgesehen von wenigen Ausnahmen sollten alle Webseiten mit Google-Diagrammen 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>

Mit der ersten Zeile dieses Beispiels wird der Loader selbst geladen. Sie können das Ladeprogramm nur einmal laden, unabhängig davon, wie viele Diagramme Sie zeichnen möchten. Nach dem Laden des Ladeprogramms können Sie die google.charts.load-Funktion einmal oder mehrmals aufrufen, um Pakete für bestimmte Diagrammtypen zu laden.

Das erste Argument von google.charts.load ist der Versionsname oder die Versionsnummer als String. Wenn Sie 'current' angeben, wird die neueste offizielle Version von Google Charts geladen. Wenn Sie den Kandidaten für die nächste Version ausprobieren möchten, verwenden Sie stattdessen 'upcoming'. Im Allgemeinen besteht ein sehr geringer Unterschied zwischen den beiden und sie sind vollkommen identisch, außer wenn eine neue Version veröffentlicht wird. Ein häufiger Grund für die Verwendung von upcoming besteht darin, dass Sie einen neuen Diagrammtyp oder eine neue Funktion testen möchten, die Google in den nächsten ein oder zwei Monaten veröffentlichen wird. Bevorstehende Releases werden in unserem Forum angekündigt. Sie sollten sie nach der Ankündigung ausprobieren, um sich zu vergewissern, dass Änderungen an Ihren Diagrammen akzeptabel sind.

Im obigen Beispiel wird davon ausgegangen, dass Sie einen corechart darstellen möchten (Balken, Spalte, Linie, Fläche, Abgestufter Bereich, Blase, Kreis, Ring, Kombination, Kerze, Histogramm, Streuung). Wenn Sie einen anderen oder zusätzlichen Diagrammtyp verwenden möchten, ersetzen Sie corechart oben durch den entsprechenden Paketnamen oder fügen Sie ihn hinzu (z.B. {packages: ['corechart', 'table', 'sankey']}. Den Paketnamen finden Sie auf der Dokumentationsseite jedes Diagramms im Abschnitt „Wird geladen“.

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

Hinweis: In früheren Versionen von Google Charts wurde zum Laden der Bibliotheken Code verwendet, der sich vom obigen Code unterscheidet. Informationen zum Aktualisieren vorhandener Diagramme mit dem neuen Code finden Sie unter Code des Bibliotheksladeprogramms aktualisieren.

Hier ist ein vollständiges Beispiel für das Zeichnen eines Kreisdiagramms mit der grundlegenden Ladetechnik:

<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 zum Laden

Zuerst müssen Sie den Loader selbst laden. 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 während des Ladens oder nach Abschluss des Ladevorgangs dynamisch in das Dokument eingefügt werden. 

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

Nachdem das Ladeprogramm geladen wurde, können Sie google.charts.load aufrufen. Der Aufruf kann sich in einem script-Tag im head oder body des Dokuments befinden. Sie können ihn entweder aufrufen, während das Dokument noch geladen wird, oder zu einem beliebigen Zeitpunkt, nachdem es fertig geladen wurde.

Ab Version 45 können Sie google.charts.load mehr als einmal aufrufen, um zusätzliche Pakete zu laden. Es ist jedoch sicherer, wenn Sie dies vermeiden können. Sie müssen jedes Mal dieselbe Versionsnummer und dieselben Spracheinstellungen angeben.

Sie können jetzt den alten JSAPI-URL-Parameter autoload verwenden, aber für den Wert dieses Parameters müssen eine strikte JSON-Formatierung und URL-Codierung verwendet werden. In JavaScript kannst du jsonObject mit diesem Code codieren: encodeURIComponent(JSON.stringify(jsonObject)).

Einschränkungen

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

  1. Sie können google.charts.load nur einmal aufrufen. Sie können jedoch alle benötigten Pakete in einem Aufruf auflisten. Es sind also keine separaten Aufrufe erforderlich.
  2. Wenn Sie ein ChartWrapper verwenden, müssen Sie explizit alle benötigten Pakete laden, anstatt sich darauf zu verlassen, dass ChartWrapper sie automatisch für Sie lädt.
  3. Für Geochart und Map Chart müssen Sie sowohl das alte als auch das neue Bibliotheksladeprogramm laden. Auch dies gilt nur für ältere Versionen als Version 45 und sollte bei neueren Versionen nicht angewendet werden. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Versionsname oder -nummer laden

Das erste Argument des google.charts.load-Aufrufs ist der Versionsname oder die Versionsnummer. Derzeit gibt es nur zwei spezielle Versionsnamen sowie mehrere eingefrorene Versionen.

aktuell
Dies bezieht sich auf den neuesten offiziellen Release, der jedes Mal geändert wird, wenn wir einen neuen Release veröffentlichen. Diese Version ist idealerweise gut getestet und fehlerfrei. Sie können aber auch eine bestimmte eingefrorene Version angeben, wenn Sie sicher sind, dass sie funktioniert.
Anstehend
Dies ist für den nächsten Release, der sich noch in der Testphase befindet und bevor er zum offiziellen aktuellen Release wird. Testen Sie diese Version regelmäßig, damit Sie schnellstmöglich wissen, ob es Probleme gibt, die behoben werden sollten, bevor diese Version zur offiziellen Veröffentlichung wird.

Wenn wir neue Versionen von Google Charts veröffentlichen, sind einige der Änderungen umfangreich, zum Beispiel komplett neue Diagrammtypen. Andere Änderungen sind geringfügig, z. B. Verbesserungen am Erscheinungsbild oder Verhalten vorhandener Diagramme.

Viele Ersteller von Google-Diagrammen optimieren das Aussehen und Verhalten ihrer Diagramme, bis es genau das ist, was sie wollen. Einige Creator fühlen sich vielleicht sicherer, weil sie wissen, dass sich ihre Diagramme nie ändern werden, unabhängig davon, welche Verbesserungen wir in Zukunft vornehmen. Diese Nutzer unterstützen eingefrorene Google Charts.

Eingefrorene Diagrammversionen sind anhand ihrer Nummer gekennzeichnet und in unseren offiziellen Veröffentlichungen beschrieben. Ersetzen Sie current oder upcoming in Ihrem Aufruf von google.charts.load durch die Nummer der eingefrorenen Version, um eine eingefrorene Version zu laden:

<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 eingefrorene Versionen auf unbestimmte Zeit verfügbar bleiben, behalten uns aber vor, eingefrorene Versionen zu entfernen, die Sicherheitsbedenken haben. Normalerweise bieten wir keinen Support für eingefrorene Versionen an, außer wenn wir Ihnen nicht hilfreich vorschlagen, ein Upgrade auf eine neuere Version durchzuführen.

Einstellungen laden

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

Pakete
Ein Array mit null oder mehr Paketen. Jedes geladene Paket enthält den Code, der zur Unterstützung einer Reihe von Funktionen erforderlich ist. Dies ist in der Regel ein Diagrammtyp. Die zu ladenden Pakete sind in der Dokumentation für jeden Diagrammtyp aufgeführt. Sie können die Angabe von Paketen vermeiden, wenn Sie mit einem ChartWrapper das erforderliche automatisch laden.
language
Der Code für die Sprache oder Region, der zum Anpassen von Text verwendet werden soll, der Teil des Diagramms sein könnte. Weitere Informationen finden Sie unter Gebietsschemata.
callback
Eine Funktion, die aufgerufen wird, nachdem die Pakete geladen wurden. Alternativ können Sie diese Funktion durch Aufrufen von google.charts.setOnLoadCallback wie im obigen Beispiel angeben. Weitere Informationen finden Sie unter Callback. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(Version 45): Mit dieser Einstellung können Sie einen Schlüssel angeben, den Sie mit Geochart und Map Chart verwenden können. So vermeiden Sie es, das Standardverhalten zu verwenden, da dies zu einer gelegentlichen Dienstdrosselung 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 unter Schlüssel/Authentifizierung anfordern. Ihr Code sieht in etwa so aus: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(Version 47) Wenn die Richtlinie auf „true“ gesetzt ist, wird dieser in allen Diagrammen und Kurzinfos, die HTML aus von Nutzern bereitgestellten Daten generieren, bereinigt, indem unsichere Elemente und Attribute 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

Gebietsschemata werden verwendet, um Text für ein Land oder eine Sprache anzupassen und so die Formatierung von Werten wie Währungen, Datumsangaben und Zahlen zu beeinflussen.

Standardmäßig werden die Google-Diagramme mit der Sprache „en“ geladen. Sie können diese Standardeinstellung überschreiben, indem Sie in den Ladeeinstellungen explizit eine Sprache angeben.

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

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

Unter diesem Link sehen Sie ein Beispiel.

Rückruf

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

Beachten Sie, dass Sie bei all diesen Methoden eine Funktionsdefinition angeben müssen, anstatt die Funktion aufzurufen. Die Funktionsdefinition, die Sie angeben, kann entweder eine benannte Funktion (Sie geben einfach ihren Namen) oder eine anonyme Funktion sein. Wenn das Laden der Pakete abgeschlossen ist, wird diese Callback-Funktion ohne Argumente aufgerufen. Das Ladeprogramm wartet außerdem, bis das Dokument vollständig 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 in einer Funktion kombinieren. Weitere Informationen finden Sie unter Mehrere Diagramme auf einer Seite zeichnen. 

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

Callback über Promise

Eine andere Möglichkeit zur Registrierung deines Callbacks besteht darin, das Promise zu verwenden, das vom google.charts.load-Aufruf zurückgegeben wird. Dazu fügen Sie der Methode then() einen Aufruf mit folgendem Code hinzu. 

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

Ein Vorteil der Verwendung des Promise besteht darin, dass Sie ganz einfach mehr Diagramme zeichnen können, indem Sie mehr .then(anotherFunction)-Aufrufe verketten. Durch die Verwendung des Promise wird der Callback außerdem mit den spezifischen Paketen verknüpft, die für diesen Callback erforderlich sind. Dies ist wichtig, wenn Sie mit einem weiteren Aufruf von google.charts.load() mehr Pakete laden möchten.

Code zum Laden der Bibliothek aktualisieren

In früheren Versionen von Google Charts wurde zum Laden der Bibliotheken unterschiedlicher Code verwendet. In der folgenden Tabelle wird der alte Code zum Laden der Bibliothek im Vergleich zum neuen Code dargestellt.

Alter Code zum Laden der Bibliothek 
<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 Code zum Laden der Bibliothek 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

Um Ihre vorhandenen Diagramme zu aktualisieren, können Sie den alten Bibliotheks-Ladecode durch den neuen Code ersetzen. Beachten Sie jedoch die oben beschriebenen Einschränkungen beim Laden von Bibliotheken.