Wczytaj biblioteki

Na tej stronie dowiesz się, jak wczytać biblioteki wykresów Google.

Wczytywanie biblioteki podstawowej

Poza nielicznymi wyjątkami, wszystkie strony zawierające Wykresy Google powinny zawierać w elemencie <head> te wiersze:

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

Pierwszy wiersz tego przykładu wczytuje sam moduł ładowania. Moduł ładujący możesz wczytać tylko raz, niezależnie od tego, ile wykresów chcesz narysować. Po wczytaniu modułu ładującego możesz wywołać funkcję google.charts.load co najmniej raz, aby wczytać pakiety dla określonych typów wykresów.

Pierwszy argument funkcji google.charts.load to nazwa lub numer wersji w postaci ciągu znaków. Jeśli wybierzesz 'current', spowoduje to załadowanie najnowszej oficjalnej wersji Wykresów Google. Jeśli chcesz wypróbować tę kandydaturę w kolejnej wersji, zamiast tego użyj 'upcoming'. Zasadniczo będą one bardzo mało różnie i całkowicie różnią się, z wyjątkiem przypadków, gdy powstaje nowa wersja. Funkcja upcoming często jest używana, jeśli chcesz przetestować nowy typ wykresu lub nową funkcję, którą Google opublikuje w ciągu najbliższych miesięcy lub 2 miesięcy. (Informujemy o nadchodzących wersjach na naszym forum i zachęcamy do ich wypróbowania po ogłoszeniu, aby mieć pewność, że wszelkie zmiany w wykresach są dopuszczalne).

W przykładzie powyżej zakładamy, że chcesz wyświetlić corechart (słupkowy, kolumna, linia, obszar, obszar krokowy, dymek, kołowy, pierścieniowy, kombinację, świecznik, histogram, punkt). Jeśli chcesz zobaczyć inny lub dodatkowy typ wykresu, zastąp lub dodaj odpowiednią nazwę pakietu w polu corechart powyżej (np. {packages: ['corechart', 'table', 'sankey']}. Nazwę pakietu znajdziesz w sekcji „Wczytywanie” na stronie dokumentacji każdego wykresu.

W tym przykładzie zakładamy też, że gdzieś na swojej stronie masz zdefiniowaną funkcję JavaScript o nazwie drawChart. Nazwa funkcji może być dowolna, ale dopilnuj, aby była globalnie unikalna i została zdefiniowana, zanim odwołasz się do niej w wywołaniu google.charts.setOnLoadCallback.

Uwaga: do wczytywania bibliotek w poprzednich wersjach Chartów Google używany był kod inny niż powyżej. Informacje o aktualizowaniu istniejących wykresów pod kątem nowego kodu znajdziesz w sekcji Aktualizowanie kodu wczytywania biblioteki.

Oto pełny przykład rysowania wykresu kołowego przy użyciu podstawowej metody wczytywania:

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

Wczytywanie szczegółów

Najpierw musisz wczytać sam moduł ładujący, co odbywa się w osobnym tagu script z parametrem src="https://www.gstatic.com/charts/loader.js". Ten tag może znajdować się w sekcji head lub body dokumentu albo można go wstawić dynamicznie do dokumentu podczas jego wczytywania lub po zakończeniu. 

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

Po wczytaniu modułu możesz wywołać funkcję google.charts.load. Ta metoda może znajdować się w tagu script w tagu head lub body dokumentu. Możesz to zrobić podczas ładowania dokumentu lub po jego zakończeniu.

Od wersji 45 możesz wywoływać google.charts.load więcej niż raz, by załadować dodatkowe pakiety, choć bezpieczniej jest tego uniknąć, jeśli możesz tego uniknąć. Za każdym razem musisz podać ten sam numer wersji i ustawienia języka.

Możesz teraz używać starego parametru adresu URL JSAPI autoload, ale jego wartość musi używać rygorystycznego formatowania JSON i kodowania adresów URL. W języku JavaScript możesz użyć kodu jsonObject, korzystając z tego kodu: encodeURIComponent(JSON.stringify(jsonObject)).

Ograniczenia

Jeśli używasz wersji starszych niż 45, musisz zwrócić uwagę na kilka niewielkich, ale ważnych ograniczeń dotyczących sposobu wczytywania Wykresów Google:

  1. Możesz zadzwonić do firmy google.charts.load tylko raz. Wszystkie pakiety, które będą Ci potrzebne, możesz wymienić w jednym wywołaniu, więc nie trzeba wykonywać osobnych wywołań.
  2. Jeśli używasz komponentu ChartWrapper, musisz jawnie wczytywać wszystkie potrzebne pakiety, zamiast polegać na automatycznym wczytywaniu ich przez komponent ChartWrapper.
  3. W przypadku wykresów geograficznych i wykresu mapy musisz wczytać zarówno stary, jak i nowy program wczytujący bibliotekę. Pamiętaj, że dotyczy to tylko wersji starszych niż 45 i nie należy tego robić w przypadku nowszych wersji. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Nazwa lub numer wersji do wczytania

Pierwszym argumentem wywołania w usłudze google.charts.load jest nazwa lub numer wersji. Obecnie są tylko dwie specjalne nazwy wersji i kilka zablokowanych wersji.

obecnie
Dotyczy to najnowszej oficjalnej wersji, która zmienia się za każdym razem, gdy publikujemy nową wersję. Ta wersja jest dobrze przetestowana i nie zawiera błędów, ale jeśli uznasz, że działa, możesz wskazać konkretną zamrożoną wersję.
następne
Dotyczy to następnej wersji, która wciąż jest testowana, zanim stanie się oficjalną wersją bieżącą. Regularnie testuj tę wersję, by wiedzieć, czy nie występują jakieś problemy, które trzeba rozwiązać, zanim stanie się ona oficjalną wersją.

Gdy publikujemy nowe wersje list przebojów Google, pewne zmiany są duże, np. zupełnie nowe typy wykresów. Inne drobne zmiany, takie jak ulepszenia wyglądu lub działania istniejących wykresów.

Wielu twórców list przebojów Google dostosowuje wygląd i styl swoich wykresów do momentu, aż uzyska dokładnie to, czego chcą. Niektórzy twórcy mogą czuć się pewniej, wiedząc, że ich wykresy nigdy się nie zmienią, niezależnie od tego, co wprowadzimy w przyszłości. W przypadku tych użytkowników obsługiwane są zablokowane Wykresy Google.

Zablokowane wersje listy przebojów są identyfikowane według liczby i są opisane w naszych oficjalnych wersjach. Aby wczytać zablokowaną wersję, zastąp current lub upcoming w wywołaniu funkcji google.charts.load numerem zablokowanej wersji:

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

Oczekujemy, że zablokowane wersje pozostaną dostępne bezterminowo, ale możemy wycofać zablokowane wersje mające problemy z bezpieczeństwem. Zazwyczaj nie zapewniamy pomocy w przypadku zablokowanych wersji z wyjątkiem sytuacji, gdy zasugerujemy uaktualnienie do nowszej wersji.

Wczytaj ustawienia

Drugi parametr w wywołaniu funkcji google.charts.load jest obiektem do określania ustawień. Poniższe właściwości są obsługiwane w przypadku ustawień.

przesyłki
Tablica z zerową liczbą pakietów lub większą ich liczbą. Każdy wczytywany pakiet będzie zawierał kod wymagany do obsługi zestawu funkcji, zwykle jest to typ wykresu. Pakiety lub pakiety, które musisz wczytać, znajdziesz w dokumentacji każdego typu wykresu. Możesz uniknąć określania pakietów, jeśli używasz komponentu ChartWrapper do automatycznego wczytywania wymaganych pakietów.
language,
Kod języka lub regionu, który powinien dostosowywać tekst, który może być częścią wykresu. Więcej informacji znajdziesz w sekcji Języki.
wywołanie zwrotne
Funkcja, która zostanie wywołana po wczytaniu pakietów. Możesz też określić tę funkcję, wywołując funkcję google.charts.setOnLoadCallback w sposób przedstawiony w powyższym przykładzie. Więcej informacji znajdziesz w sekcji Oddzwanianie. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) To ustawienie umożliwia określenie klucza, którego można używać z wykresem geograficznym i wykresem mapy. Warto to zrobić, zamiast korzystać z domyślnego działania, które może czasami powodować ograniczanie dostępu do usługi dla użytkowników. Dowiedz się, jak skonfigurować własny klucz na potrzeby usługi „Google Maps JavaScript API”: Uzyskaj klucz/uwierzytelnianie. Twój kod będzie wyglądał mniej więcej tak: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) Jeśli zasada ma wartość Prawda, wszystkie wykresy i etykietki, które generują kod HTML na podstawie danych przekazywanych przez użytkowników, będą oczyszczać je, usuwając niebezpieczne elementy i atrybuty. (w wersji 49 lub nowszej) bibliotekę można też wczytać w trybie awaryjnym za pomocą skrótu, który akceptuje te same ustawienia wczytywania, ale zawsze wczytuje „bieżącą” wersję:
  google.charts.safeLoad({ packages: ['corechart'] });

Języki

Języki pozwalają dostosować tekst pod kątem kraju lub języka, co wpływa na formatowanie wartości takich jak waluty, daty i liczby.

Domyślnie Wykresy Google są wczytywane z językiem „en”. Tę wartość domyślną można zastąpić, wyraźnie określając język w ustawieniach wczytywania.

Aby wczytać wykres sformatowany pod kątem określonego języka, użyj ustawienia language w następujący sposób: 

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

Kliknij ten link, aby zobaczyć przykład na żywo.

Oddzwanianie

Zanim użyjesz któregoś z pakietów wczytanych przez google.charts.load, musisz poczekać na zakończenie wczytywania. Nie wystarczy tylko czekać na zakończenie wczytywania dokumentu. Ponieważ zakończenie wczytywania może trochę potrwać, musisz zarejestrować funkcję wywołania zwrotnego. Można to zrobić na 3 sposoby. Określ ustawienie callback w wywołaniu google.charts.load lub wywołaj setOnLoadCallback przekazującą funkcję jako argument albo użyj funkcji Promise zwracanej przez wywołanie google.charts.load.

Pamiętaj, że w przypadku wszystkich tych sposobów musisz podać definicję funkcji, a nie ją wywoływać. Podaną przez Ciebie definicją funkcji może być funkcja nazwana (po prostu nadaj jej nazwę) lub funkcję anonimową. Po zakończeniu wczytywania pakietów ta funkcja wywołania zwrotnego zostanie wywołana bez argumentów. Moduł ładowania zaczeka też na zakończenie wczytywania dokumentu, zanim wywoła wywołanie zwrotne.

Jeśli chcesz narysować więcej niż 1 wykres, możesz zarejestrować więcej niż 1 funkcję wywołania zwrotnego za pomocą funkcji setOnLoadCallback lub połączyć je w 1 funkcję. Dowiedz się więcej o tym, jak rysować wiele wykresów na jednej stronie. 

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

Oddzwanianie przez Promise

Innym sposobem zarejestrowania wywołania zwrotnego jest użycie wartości Promise zwróconej z wywołania google.charts.load. Aby to zrobić, dodaj wywołanie do metody then() z kodem wyglądającym tak jak poniżej. 

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

Jedną z zalet korzystania z Promise jest to, że dzięki temu możesz łatwo tworzyć kolejne wykresy, łącząc więcej wywołań .then(anotherFunction). Użycie Promise wiąże również wywołanie zwrotne do konkretnych pakietów wymaganych w przypadku tego wywołania zwrotnego. Jest to ważne, jeśli chcesz wczytać więcej pakietów przy użyciu innego wywołania google.charts.load().

Zaktualizuj kod programu uruchamiającego bibliotekę

Poprzednie wersje Wykresów Google używały innego kodu do wczytywania bibliotek. Poniższa tabela przedstawia porównanie starego i nowego kodu wczytującego bibliotekę.

Stary kod programu wczytującego bibliotekę 
<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>
Nowy kod programu Library Loader 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

Aby zaktualizować istniejące wykresy, możesz zastąpić stary kod wczytujący bibliotekę nowym kodem. Pamiętaj jednak o ograniczeniach dotyczących wczytywania bibliotek opisanych powyżej.