Wczytaj biblioteki

Na tej stronie znajdziesz instrukcje wczytywania bibliotek wykresów Google.

Ładowanie podstawowej biblioteki

Z niewielkimi wyjątkami wszystkie strony internetowe z użyciem Google Charts powinny zawierać te linie w sekcji <head> strony internetowej:

<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 loader. Niezależnie od tego, ile wykresów planujesz narysować, możesz wczytać ładowarkę tylko raz. Po załadowaniu programu wczytującego możesz wywołać funkcję google.charts.load raz lub więcej razy, aby załadować pakiety dla poszczególnych typów wykresów.

Pierwszym argumentem funkcji google.charts.load jest nazwa lub numer wersji podany jako ciąg 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. Najczęstszą przyczyną korzystania z opcji upcoming jest chęć przetestowania nowego typu wykresu lub funkcji, które Google wprowadzi w ciągu najbliższych 1–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ć wykres corechart (słupkowy, kolumnowy, liniowy, obszarowy, stopniowany, punktowy, kołowy, donutowy, kombinowany, świecowy, histogramowy lub punktowy). Jeśli chcesz użyć innego lub dodatkowego typu wykresu, zastąp lub dodaj odpowiednią nazwę pakietu zamiast corechart (np. {packages: ['corechart', 'table', 'sankey']}. Nazwę pakietu znajdziesz w sekcji „Ładowanie” na stronie dokumentacji danego wykresu.

W tym przykładzie zakładamy też, że masz zdefiniowaną gdzieś na stronie internetowej 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 funkcji google.charts.setOnLoadCallback.

Uwaga: do wczytywania bibliotek w poprzednich wersjach Wykresów Google używany był kod różniący się od tych 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 za pomocą 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>

Wczytuję szczegóły

Najpierw musisz załadować sam loader, 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 załadowaniu programu ładującego możesz zadzwonić na numer google.charts.load. Możesz ją wywołać 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 opcjonalnie wywoływać funkcję google.charts.load więcej niż raz, aby wczytywać dodatkowe pakiety. Lepiej jednak tego unikać. Za każdym razem musisz podać ten sam numer wersji i te same ustawienia języka.

Możesz teraz używać starego parametru URL autoload JSAPI, ale wartość tego parametru musi być sformatowana zgodnie ze ścisłymi zasadami formatowania kodu JSON i musi być zakodowana w postaci adresu URL. W JavaScript kodowanie wartościjsonObject możesz wykonać za pomocą tego kodu:encodeURIComponent(JSON.stringify(jsonObject)).

Ograniczenia

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

  1. Do google.charts.load możesz zadzwonić tylko raz. Możesz jednak wymienić wszystkie pakiety, których potrzebujesz, w jednym połączeniu, więc nie musisz nawiązywać osobnych połączeń.
  2. Jeśli używasz elementu ChartWrapper, musisz jawnie wczytać wszystkie potrzebne pakiety, zamiast polegać na automatycznym wczytywaniu ich przez ChartWrapper.
  3. W przypadku diagramu geograficznego i diagramu mapy musisz załadować zarówno stary, jak i nowy ładownik biblioteki. Ponownie: dotyczy to tylko wersji starszych niż 45. 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>

Załaduj nazwę lub numer wersji

Pierwszym argumentem wywołania w usłudze google.charts.load jest nazwa lub numer wersji. Obecnie istnieją tylko 2 nazwy wersji specjalnych i kilka wersji zamrożonych.

obecnie
Dotyczy to najnowszej oficjalnej wersji, która zmienia się za każdym razem, gdy wydajemy 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ę, aby jak najszybciej dowiedzieć się, czy występują jakieś problemy, które należy rozwiązać, zanim ta wersja stanie się oficjalną wersją.

Gdy udostępniamy nowe wersje Google Charts, niektóre zmiany są duże, np. zupełnie nowe typy wykresów. Inne zmiany są niewielkie, na przykład ulepszenia wyglądu lub działania dotychczasowych wykresów.

Wielu twórców wykresów Google dostosowuje wygląd i wygląd swoich wykresów, aż będą dokładnie takie, jak sobie wyobrażają. Niektórzy twórcy mogą czuć się bardziej komfortowo, wiedząc, że ich wykresy nigdy się nie zmienią, niezależnie od tego, jakie ulepszenia wprowadzimy w przyszłości. W przypadku tych użytkowników obsługujemy zamrożone wykresy Google.

Zamrożone wersje wykresów są identyfikowane za pomocą numeru i opisane w oficjalnych wersjach. Aby wczytać zamrożoną wersję, w wywołaniu funkcji google.charts.load zastąp parametr current lub upcoming numerem zamrożonej wersji:

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

Zamierzamy udostępniać wersje zamrożone przez nieokreślony czas, ale możemy wycofać te, które mogą stanowić zagrożenie dla bezpieczeństwa. Zazwyczaj nie zapewniamy pomocy w przypadku zamrożonych wersji, chyba że sugerujemy przejście na nowszą wersję.

Wczytaj ustawienia

Drugi parametr wywołania funkcji google.charts.load to obiekt do określania ustawień. W przypadku ustawień obsługiwane są te właściwości:

przesyłki
Tablica zawierająca co najmniej 1 element. Każdy wczytywany pakiet będzie zawierać kod wymagany do obsługi zestawu funkcji, zwykle typu wykresu. Pakiety, które musisz załadować, są wymienione w dokumentacji dotyczącej poszczególnych typów wykresów. Nie musisz określać żadnych pakietów, jeśli używasz ChartWrapper do automatycznego wczytywania wymaganych elementó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ż wywołać tę funkcję, wywołując funkcję google.charts.setOnLoadCallback, jak pokazano w przykładzie powyżej. Więcej informacji znajdziesz w sekcji Połączenie zwrotne. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(w wersji 45) To ustawienie umożliwia określenie klucza, którego możesz używać w wykresach geoprzestrzennych i wykresach mapowych. Możesz to zrobić zamiast używać domyślnego zachowania, które może spowodować sporadyczne ograniczanie usługi dla użytkowników. Dowiedz się, jak skonfigurować własny klucz do korzystania z usługi „Google Maps JavaScript API”: Pobierz klucz/uwierzytelnienie. 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. Alternatywnie (w wersji 49 i nowszych) bibliotekę można wczytać w trybie bezpiecznym 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 i wpływają na formatowanie wartości takich jak waluty, daty i liczby.

Domyślnie Google Charts jest ładowany z użyciem ustawień językowych „en”. Wartość domyślną można zastąpić, wyraźnie określając język w ustawieniach wczytywania.

Aby załadować wykres sformatowany pod kątem określonego regionu, użyj ustawienia language w ten sposób: 

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

Aby zobaczyć przykład, kliknij ten link.

Oddzwanianie

Zanim zaczniesz korzystać z pakietów załadowanych przez google.charts.load, musisz zaczekać na zakończenie wczytywania. Nie wystarczy poczekać, aż dokument się w pełni wczyta. Ponieważ zakończenie wczytywania może trochę potrwać, musisz zarejestrować funkcję wywołania zwrotnego. Możesz to zrobić na 3 sposoby. Określ ustawienie callback w wywołaniu google.charts.load lub wywołaj funkcję setOnLoadCallback, która przekazuje funkcję jako argument, albo użyj funkcji Promise zwróconej przez wywołanie google.charts.load.

Pamiętaj, że w przypadku wszystkich tych sposobów musisz podać definicję funkcji, a nie ją wywoływać. Podana definicja funkcji może być funkcją nazwaną (czyli podajesz tylko jej nazwę) lub funkcją anonimową. Po zakończeniu wczytywania pakietów zostanie wywołana ta funkcja wywołania zwrotnego 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 jedną 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 rejestracji wywołania zwrotnego jest użycie obietnicy zwracanej przez wywołanie google.charts.load. Aby to zrobić, dodaj wywołanie metody then() za pomocą kodu podobnego do tego: 

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

Jedną z zalet korzystania z obietnicy jest to, że możesz łatwo tworzyć więcej wykresów, łącząc ze sobą kolejne wywołania funkcji .then(anotherFunction). Użycie obietnicy wiąże wywołanie zwrotne z określonymi pakietami wymaganymi do tego wywołania zwrotnego. Jest to ważne, jeśli chcesz załadować więcej pakietów za pomocą kolejnego wywołania google.charts.load().

Aktualizowanie kodu programu ładującego bibliotekę

Wcześniejsze wersje Google Charts używały innego kodu do wczytywania bibliotek. Tabela poniżej przedstawia stary i nowy kod ładowarki biblioteki.

Kod starej biblioteki ładowania 
<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 ładowarki biblioteki 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

Aby zaktualizować dotychczasowe wykresy, możesz zastąpić stary kod ładowania biblioteki nowym. Pamiętaj jednak o ograniczeniach dotyczących wczytywania bibliotek opisanych powyżej.