Bibliotheken laden

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

Einfaches Laden der Bibliothek

Mit 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>

In der ersten Zeile dieses Beispiels wird der Lader selbst geladen. Sie können den Loader nur einmal laden, unabhängig davon, wie viele Diagramme Sie zeichnen möchten. Nachdem Sie den Loader geladen haben, können Sie die Funktion google.charts.load einmal 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 neueste offizielle Version von Google Charts geladen. Wenn Sie den Release-Kandidaten ausprobieren möchten, verwenden Sie stattdessen 'upcoming'. Im Allgemeinen gibt es nur sehr wenige Unterschiede zwischen den beiden Versionen. Sie sind nur dann völlig identisch, wenn eine neue Version in Arbeit ist. Ein häufiger Grund für die Verwendung von upcoming ist, dass Sie einen neuen Diagrammtyp oder eine neue Funktion testen möchten, die Google in den nächsten ein bis zwei Monaten veröffentlicht. Wir geben anstehende Releases in unserem Forum bekannt und empfehlen, sie nach der Ankündigung auszuprobieren, um sicherzustellen, dass alle Änderungen an Ihren Diagrammen akzeptabel sind.

Im Beispiel oben wird davon ausgegangen, dass Sie ein corechart-Diagramm (Balken-, Säulen-, Linien-, Flächen-, abgestuftes Flächen-, Blasen-, Kreis-, Donut-, Kombinations-, Kerzen-, Histogramm- oder Streudiagramm) anzeigen möchten. Wenn Sie einen anderen oder zusätzlichen Diagrammtyp verwenden möchten, ersetzen Sie corechart durch den entsprechenden Paketnamen oder fügen Sie ihn hinzu (z.B. {packages: ['corechart', 'table', 'sankey']}. Den Paketnamen finden Sie auf der Seite mit der Dokumentation für jedes Diagramm im Abschnitt „Laden“.

In diesem Beispiel wird außerdem davon ausgegangen, dass Sie irgendwo auf Ihrer Webseite eine JavaScript-Funktion namens drawChart 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 zum Laden der Bibliotheken ein anderer Code verwendet. Informationen zum Aktualisieren vorhandener Diagramme mit dem neuen Code finden Sie unter Code des Bibliotheks-Ladeprogramms 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 werden geladen

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

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

Nachdem der Lader geladen ist, können Sie google.charts.load anrufen. Sie können es in einem script-Tag in der head oder body des Dokuments aufrufen. Sie können es entweder aufrufen, während das Dokument noch geladen wird, oder jederzeit nach Abschluss des Ladevorgangs.

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

Sie können jetzt den alten JSAPI-URL-Parameter autoload verwenden. Der Wert dieses Parameters muss jedoch streng JSON-formatiert und URL-codiert sein. In JavaScript können Sie die Codierung von jsonObject mit diesem Code durchführen: encodeURIComponent(JSON.stringify(jsonObject)).

Einschränkungen

Wenn Sie eine Version 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 anrufen. Sie können jedoch alle Pakete, die Sie benötigen, in einem einzigen Aufruf auflisten, sodass Sie nicht mehrere Aufrufe ausführen müssen.
  2. Wenn Sie einen ChartWrapper verwenden, müssen Sie alle benötigten Pakete explizit laden, anstatt darauf zu vertrauen, dass der 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. Das gilt nur für Versionen vor Version 45. Bei neueren Versionen sollten Sie das nicht tun. 
    <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 Name oder die Nummer der Version. Derzeit gibt es nur zwei spezielle Versionsnamen und mehrere eingefrorene Versionen.

aktuell
Dieser Link bezieht sich auf die neueste offizielle Version, die sich jedes Mal ändert, wenn wir eine neue Version veröffentlichen. Diese Version ist idealerweise gut getestet und frei von Fehlern. Sie können aber auch eine bestimmte eingefrorene Version angeben, sobald Sie sicher sind, dass sie funktioniert.
Anstehend
Dieser Wert bezieht sich auf die nächste Version, die noch getestet wird und noch nicht die offizielle aktuelle Version ist. Bitte testen Sie diese Version regelmäßig, damit Sie so schnell wie möglich wissen, ob es Probleme gibt, die behoben werden sollten, bevor diese Version offiziell veröffentlicht wird.

Wenn wir neue Versionen von Google-Diagrammen veröffentlichen, sind einige der Änderungen groß, z. B. völlig neue Diagrammtypen. Andere Änderungen sind kleiner, z. B. Verbesserungen am Aussehen oder Verhalten vorhandener Diagramme.

Viele Google-Diagramm-Ersteller optimieren das Erscheinungsbild ihrer Diagramme, bis sie genau das gewünschte Ergebnis erzielen. 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.

Die Versionen der eingefrorenen Charts werden durch eine Nummer gekennzeichnet und in unseren offiziellen Releases 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. Versionen, die Sicherheitsrisiken bergen, werden jedoch möglicherweise eingestellt. Wir bieten in der Regel keinen Support für eingefrorene Versionen, außer dass wir Ihnen empfehlen, auf eine neuere Version zu aktualisieren.

Einstellungen laden

Der zweite Parameter in Ihrem Aufruf von google.charts.load ist ein Objekt zum Angeben von Einstellungen. Die folgenden Properties 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. Welche Pakete Sie laden müssen, wird in der Dokumentation für jeden Diagrammtyp aufgeführt. Sie können Pakete vermeiden, wenn Sie einen ChartWrapper verwenden, um die erforderlichen Elemente automatisch zu laden.
Sprache
Der Code für die Sprache oder das Gebietsschema, mit dem Text angepasst werden soll, der Teil des Diagramms sein könnte. Weitere Informationen finden Sie unter Sprachen.
callback
Eine Funktion, die aufgerufen wird, sobald die Pakete geladen wurden. Alternativ können Sie diese Funktion auch durch Aufrufen von google.charts.setOnLoadCallback angeben, wie im Beispiel oben gezeigt. 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 für Geokarten und Kartendiagramme verwenden können. Das ist besser als das Standardverhalten, das zu gelegentlichen 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: Einen Schlüssel/Authentifizierung abrufen. 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 (Version 49 und höher) kann die Bibliothek über eine Verknüpfung im abgesicherten Modus geladen werden. Dabei werden dieselben Ladeeinstellungen verwendet, aber immer die „aktuelle“ Version geladen: 
  google.charts.safeLoad({ packages: ['corechart'] });

Sprachen

Mit Gebietsschemata können Sie Text für ein Land oder eine Sprache anpassen. Das wirkt sich auf die Formatierung von Werten wie Währungen, Datumsangaben und Zahlen aus.

Standardmäßig werden Google-Diagramme mit der Sprache „en“ (Englisch) geladen. Sie können diese Standardeinstellung überschreiben, indem Sie in den Ladeeinstellungen explizit eine Sprache 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 Livebeispiel.

Rückruf

Bevor Sie die von google.charts.load geladenen Pakete verwenden können, müssen Sie warten, bis der Ladevorgang abgeschlossen ist. Es reicht nicht aus, nur 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. Gib entweder eine callback-Einstellung in deinem google.charts.load-Aufruf an oder rufe setOnLoadCallback auf und übergebe eine Funktion als Argument oder verwende das Versprechen, das vom 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 von Ihnen angegebene Funktionsdefinition kann entweder eine benannte Funktion (Sie geben also nur den Namen an) oder eine anonyme Funktion sein. Wenn das Laden der Pakete abgeschlossen ist, wird diese Callback-Funktion ohne Argumente aufgerufen. Der Lader wartet außerdem, bis das Dokument vollständig geladen ist, bevor er den Rückruf aufruft.

Wenn Sie mehr als ein Diagramm zeichnen möchten, können Sie entweder mehrere Rückruffunktionen mit setOnLoadCallback registrieren oder sie in 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 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 einen Aufruf der Methode then() mit dem folgenden Code hinzu. 

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

Ein Vorteil der Verwendung des Promise besteht darin, dass Sie ganz einfach weitere Diagramme erstellen können, indem Sie weitere .then(anotherFunction)-Aufrufe verketten. Durch die Verwendung des Promise wird der Rückruf auch mit den für diesen Rückruf erforderlichen Paketen verknüpft. Das ist wichtig, wenn Sie weitere Pakete mit einem weiteren Aufruf von google.charts.load() laden möchten.

Code zum Laden der Bibliothek aktualisieren

In früheren Versionen von Google Charts wurde ein anderer Code zum Laden der Bibliotheken verwendet. In der folgenden Tabelle wird der alte Bibliotheksladecode mit dem neuen verglichen.

Alter Library Loader-Code 
<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 Library Loader-Code 
<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 des Bibliotheksladeprogramms durch den neuen Code ersetzen. Beachten Sie jedoch die oben beschriebenen Einschränkungen beim Laden von Bibliotheken.