Wczytaj biblioteki

Ta strona pokazuje, jak wczytać biblioteki wykresu Google.

Wczytywanie podstawowej biblioteki

Oprócz kilku wyjątków wszystkie strony internetowe z Wykresami Google powinny zawierać w wierszu <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 ładuje sam program wczytujący. Program wczytujący może być ładowany tylko raz bez względu na to, ile wykresów chcesz narysować. Po wczytaniu modułu możesz wywołać funkcję google.charts.load co najmniej raz, aby wczytać pakiety dla określonych typów wykresów.

Pierwszym argumentem funkcji google.charts.load jest nazwa lub numer wersji jako ciąg znaków. Jeśli podasz 'current', spowoduje to wczytanie najnowszej oficjalnej wersji Wykresów Google. Jeśli chcesz wypróbować kandydata do kolejnej wersji, zamiast tego użyj właściwości 'upcoming'. Ogólnie rzecz biorąc, nie ma dużej różnicy między nimi i będą one całkowicie identyczne, chyba że trwa wdrażanie nowej wersji. Częstym powodem użycia upcoming jest chęć przetestowania nowego typu wykresu lub funkcji, która zostanie udostępniona w Google w ciągu następnego lub dwóch miesięcy. Ogłosimy nadchodzące premiery na naszym forum i wypróbuj je z zapowiedzią, aby mieć pewność, że zmiany na wykresach są dopuszczalne.

W powyższym przykładzie zakładamy, że chcesz wyświetlić corechart (słupek, kolumnę, linię, obszar, obszar krokowy, dymek, koło, pierścień, mieszankę, świecę, histogram lub wykres punktowy). Jeśli chcesz użyć innego lub dodatkowego typu wykresu, zastąp odpowiednią nazwę pakietu corechart lub dodaj ją 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, że masz też funkcję JavaScript o nazwie drawChart zdefiniowaną w dowolnym miejscu na stronie internetowej. Możesz nadać tej funkcji dowolną nazwę, ale pamiętaj, aby była unikalna globalnie i zdefiniowana przed wywołaniem google.charts.setOnLoadCallback.

Uwaga: poprzednie wersje Wykresów Google używały kodu, który różni się od przedstawionego powyżej, aby załadować biblioteki. Aby zaktualizować dotychczasowe wykresy i uwzględnić nowy kod, przeczytaj artykuł Aktualizowanie kodu wczytującego bibliotekę.

Oto pełny przykład 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>

Szczegóły wczytywania

Najpierw musisz załadować sam program wczytujący w osobnym tagu script za pomocą src="https://www.gstatic.com/charts/loader.js". Ten tag może znajdować się w elemencie head lub body dokumentu albo można go wstawić dynamicznie w trakcie wczytywania lub po zakończeniu wczytywania. 

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

Po wczytaniu systemu możesz zadzwonić do aplikacji google.charts.load. Miejsce, w którym można to zrobić, może znajdować się w tagu script w obiekcie head lub body. Można to zrobić tak, gdy dokument nadal się wczytuje, lub w dowolnym momencie po jego załadowaniu.

Od wersji 45 możesz wywołać google.charts.load więcej niż raz, ale wczytanie dodatkowych pakietów jest bezpieczniejsze, jeśli tego nie zrobisz. Zawsze musisz podać ten sam numer wersji i ustawienia języka.

Możesz teraz używać starego parametru adresu URL autoload interfejsu JSAPI, ale jego wartość musi być zabezpieczona w formacie JSON i kodowaniu adresów URL. W języku JavaScript możesz wykonać kodowanie jsonObject za pomocą tego kodu: encodeURIComponent(JSON.stringify(jsonObject)).

Ograniczenia

Jeśli używasz wersji przed 44, istnieje kilka istotnych ograniczeń dotyczących wczytywania Wykresów Google:

  1. Możesz zadzwonić do firmy google.charts.load tylko raz. Możesz jednak wymienić wszystkie pakiety potrzebne w jednym wywołaniu, więc nie musisz wykonywać osobnych wywołań.
  2. Jeśli używasz ChartWrapper, musisz samodzielnie wczytać wszystkie potrzebne pakiety, zamiast polegać na automatycznym ładowaniu ich przez ChartWrapper.
  3. W przypadku Wykresu geograficznego i Wykresu mapy musisz wczytać zarówno stary moduł bibliotek, jak i nowy moduł. Zrób to tylko w przypadku wersji starszych niż 45 i nie należy robić tego w przypadku późniejszych wersji. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Nazwa lub numer wersji wczytywania

Pierwszym argumentem wywołania google.charts.load jest nazwa lub numer wersji. Obecnie dostępne są tylko 2 nazwy wersji specjalne i kilka zamrożonych wersji.

current
Jest to najnowsza wersja oficjalna, która zmienia się po każdym opublikowaniu nowej wersji. Ta wersja jest idealnie przetestowana i bez błędów, ale jeśli masz pewność, że działa, możesz ją wskazać.
następne
Jest to następna wersja, która jeszcze nie została jeszcze oficjalnie udostępniona i jest nadal testowana. Regularnie testuj tę wersję, aby jak najszybciej wiedzieć, czy występują problemy, które trzeba rozwiązać, zanim ta wersja stanie się oficjalną wersją.

Gdy wprowadzamy nowe Wykresy Google, niektóre zmiany, tak jak zupełnie nowe typy wykresów, są duże. Inne zmiany są małe, np. ulepszenia wyglądu lub działania istniejących wykresów.

Wielu twórców Wykresów Google dostosowuje wygląd i sposób działania wykresów, dopóki nie będą one oczekiwane przez użytkowników. Niektórzy twórcy czują 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 zablokowane Wykresy Google.

Zablokowane wersje wykresu są wskazywane przez numery. Opisaliśmy je w naszych oficjalnych wersjach. Aby wczytać zamrożoną 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>

Spodziewamy się, że zablokowane wersje pozostaną dostępne bezterminowo, ale możemy zrezygnować z tych wersji, które mogą być niebezpieczne. Zwykle nie zapewniamy pomocy w przypadku zablokowanych wersji, z wyjątkiem sytuacji, w których nie zalecamy przydatnego uaktualnienia.

Ustawienia ładowania

Drugi parametr w wywołaniu google.charts.load jest obiektem do określania ustawień. Te ustawienia są obsługiwane w przypadku ustawień.

przesyłki
Tablica z zerem lub większą liczbą pakietów. Każdy wczytany pakiet zawiera kod wymagany do obsługi zestawu funkcji, zwykle typu wykresu. Pakiety lub pakiety, które musisz załadować, znajdziesz w dokumentacji dotyczącej poszczególnych typów wykresów. Możesz uniknąć określania pakietów, jeśli używasz ChartWrapper do automatycznego wczytywania wymaganych treści.
language,
Kod języka lub regionu, który powinien być dostosowany do tekstu, który jest częścią wykresu. Więcej informacji znajdziesz w sekcji Język.
wywołanie zwrotne
Funkcja, która zostanie wywołana po załadowaniu pakietów. Możesz też określić tę funkcję, wywołując właściwość google.charts.setOnLoadCallback zgodnie z przykładem powyżej. Więcej informacji znajdziesz w sekcji Wywołanie zwrotne. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
Klucz Map Google
(v45) To ustawienie pozwala określić klucz, którego możesz używać z wykresem geograficznym i wykresem mapy. Możesz to zrobić zamiast stosować domyślne działanie, które może czasami ograniczać użytkownikom usługi. Aby dowiedzieć się, jak skonfigurować własny klucz na potrzeby usługi „Google Maps JavaScript API”, kliknij tutaj: Pobierz klucz/uwierzytelnianie Twój kod będzie wyglądać mniej więcej tak: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
tryb awaryjny
(v47) Jeśli ustawisz wartość „true”, wszystkie wykresy i etykietki, które generują kod HTML na podstawie danych przekazywanych przez użytkowników, zostaną oczyszczone przez usunięcie niebezpiecznych elementów i atrybutów. Możesz też wczytać bibliotekę w trybie awaryjnym, korzystając ze skrótu, który obsługuje te same ustawienia wczytywania. Zawsze będzie jednak bieżąca wersja:
  google.charts.safeLoad({ packages: ['corechart'] });

Języki

Język służy do dostosowywania tekstu dla kraju lub języka, co wpływa na formatowanie wartości takich jak waluty, daty i liczby.

Domyślnie wykres Google jest ładowany z ustawieniem „en”. Możesz zastąpić to ustawienie domyślne, określając język w ustawieniach wczytywania.

Aby wczytać wykres w konkretnym języku, użyj ustawienia language w ten sposób: 

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

Kliknij ten link, aby zobaczyć przykład opublikowanej wersji.

Oddzwanianie

Aby użyć pakietów wczytanych do google.charts.load, musisz zaczekać na zakończenie wczytywania. Nie wystarczy poczekać, aż dokument się wczyta. Ponieważ ładowanie może zająć trochę czasu, 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 przekazującą funkcję jako argument lub użyj obietnicy zwracanej przez wywołanie funkcji google.charts.load.

W obu przypadkach musisz podać definicję funkcji, a nie ją wywołać. Podana przez Ciebie definicja funkcji może być funkcją nazwaną (dlatego nadasz jej nazwę) lub anonimową. Gdy pakiety zostaną wczytane, ta funkcja wywołania zwrotnego zostanie wywołana bez argumentów. Przed wczytaniem wywołania musi też zaczekać, aż dokument się wczyta.

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ę, 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();
      });

Wywołanie zwrotne przez obietnicę

Innym sposobem zarejestrowania wywołania zwrotnego jest wykorzystanie obietnicy zwróconej w trakcie wywołania google.charts.load. W tym celu dodaj do metody then() wywołanie z kodem, który wygląda tak: 

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

Jedną z zalet korzystania z tej funkcji jest to, że możesz łatwo rysować więcej wykresów, tworząc tylko łańcuchy wywołań .then(anotherFunction). Użycie obietnicy powoduje też powiązanie wywołania zwrotnego z określonymi pakietami wymaganymi dla tego wywołania zwrotnego, co jest ważne, jeśli chcesz wczytać więcej pakietów z innym wywołaniem google.charts.load().

Zaktualizuj kod wczytujący bibliotekę

Poprzednie wersje Wykresów Google używały innego kodu do wczytywania bibliotek. W tabeli poniżej znajdziesz stary kod wczytujący bibliotekę.

Stary kod wczytujący 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 wczytujący bibliotekę 
<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 bibliotekiem nowym. Pamiętaj jednak o ograniczeniach opisanych powyżej.