Ładowanie bibliotek
Na tej stronie pokazano, jak ładować biblioteki Google Chart.
Podstawowe ładowanie bibliotek
Z kilkoma wyjątkami wszystkie strony internetowe z wykresami Google powinny zawierać następujące wiersze w <head> strony internetowej:
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('current', {packages: }); google.charts.setOnLoadCallback(drawChart); ...</script>
Pierwszy wiersz tego przykładu ładuje sam program ładujący. Program ładujący można załadować tylko jeden raz, bez względu na to, ile wykresów planujemy narysować. Po załadowaniu programu ładującego można wywołać funkcję google.charts.load jeden 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, w postaci łańcucha znaków. Jeśli podasz 'current', spowoduje to załadowanie najnowszego oficjalnego wydania Google Charts. Jeśli chcesz wypróbować wersję kandydującą do następnego wydania, użyj zamiast tego 'upcoming'. Ogólnie rzecz biorąc, różnica między nimi będzie bardzo niewielka i będą one całkowicie identyczne, z wyjątkiem sytuacji, gdy nowe wydanie jest w toku. Częstym powodem użycia upcoming jest chęć przetestowania nowego typu wykresu lub funkcji, którą Google ma zamiar wydać w ciągu najbliższego miesiąca lub dwóch. (Ogłaszamy nadchodzące wydania na naszym forum i zalecamy wypróbowanie ich po ogłoszeniu, aby upewnić się, że wszelkie zmiany w wykresach są do przyjęcia.)
Powyższy przykład zakłada, że chcesz wyświetlić corechart(słupek, kolumna, linia, obszar, obszar stopniowany, bąbel, placek, pączek, combo, świecznik, histogram, rozrzut). Jeśli chcesz uzyskać inny lub dodatkowy typ wykresu, zastąp lub dodaj odpowiednią nazwę pakietu do corechart powyżej (np. {packages: }. Nazwę pakietu można znaleźć w sekcji „Ładowanie” na stronie dokumentacji każdego wykresu.
Ten przykład zakłada również, że masz funkcję JavaScript o nazwie drawChart zdefiniowaną gdzieś na swojej stronie internetowej. Możesz nazwać tę funkcję jakkolwiek chcesz, ale upewnij się, że jest ona globalnie unikalna i że jest zdefiniowana zanim odwołasz się do niej w swoim wywołaniu dogoogle.charts.setOnLoadCallback.
Uwaga: Poprzednie wersje Google Charts używały kodu, który różni się od powyższego, aby załadować biblioteki. Aby zaktualizować istniejące wykresy do nowego kodu, zobacz Update Library Loader Code.
Tutaj znajduje się kompletny przykład rysowania wykresu kołowego przy użyciu podstawowej techniki ładowania:
<head> <script src="https://www.gstatic.com/charts/loader.js"></script> <script> google.charts.load('current', {packages: }); 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(, , ]); // 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/></body>
Szczegóły ładowania
Najpierw musisz załadować sam program ładujący, co robi się w oddzielnym znaczniku script z src="https://www.gstatic.com/charts/loader.js". Ten znacznik może być albo w head lub body dokumentu, albo może być wstawiony dynamicznie do dokumentu podczas jego ładowania lub po zakończeniu ładowania.
<script src="https://www.gstatic.com/charts/loader.js"></script>
Po załadowaniu programu ładującego, możesz swobodnie wywołać google.charts.load. Miejsce wywołania może znajdować się w znaczniku script w head lub body dokumentu, i można go wywołać albo podczas ładowania dokumentu, albo w dowolnym momencie po zakończeniu ładowania.
Od wersji 45, możesz wywołać google.charts.load więcej niż jeden raz w celu załadowania dodatkowych pakietów, choć bezpieczniej jest, jeśli możesz tego uniknąć. Za każdym razem musisz podać ten sam numer wersji i ustawienia językowe.
Możesz teraz używać starego parametru URL JSAPI autoload, ale wartość tego parametru musi używać ścisłego formatowania JSON i kodowania URL. W JavaScript możesz wykonać kodowanie jsonObject za pomocą tego kodu: encodeURIComponent(JSON.stringify(jsonObject)).
Ograniczenia
Jeśli używasz wersji wcześniejszych niż v45, istnieje kilka drobnych, ale ważnych ograniczeń dotyczących sposobu ładowania Google Charts:
- Możesz tylko raz wywołać
google.charts.load. Ale możesz wymienić wszystkie pakiety, których będziesz potrzebował w jednym wywołaniu, więc nie ma potrzeby wykonywania oddzielnych wywołań. - Jeśli używasz ChartWrappera, musisz jawnie załadować wszystkie pakiety, których będziesz potrzebował, zamiast polegać na ChartWrapperze, aby automatycznie załadował je dla ciebie.
- Dla Geochart i Map Chart, musisz załadować zarówno stary program ładujący biblioteki jak i nowy program ładujący biblioteki. Ponownie, to jest tylko dla wersji wcześniejszych niż v45, i nie powinieneś tego robić dla późniejszych wersji.
<script src="https://www.gstatic.com/charts/loader.js"></script><script src="https://www.google.com/jsapi"></script>
Wczytaj nazwę lub numer wersji
Pierwszym argumentem twojego wywołania google.charts.load jest nazwa lub numer wersji. W tym momencie istnieją tylko dwie specjalne nazwy wersji i kilka wersji zamrożonych.
current To jest dla najnowszego oficjalnego wydania, które zmienia się za każdym razem, gdy wypuszczamy nowe wydanie. Ta wersja jest idealnie dobrze przetestowana i wolna od błędów, ale możesz chcieć podać konkretną wersję zamrożoną zamiast niej, gdy jesteś pewien, że działa. upcoming To jest dla następnej wersji, gdy jest jeszcze testowana i zanim stanie się oficjalnym bieżącym wydaniem. Proszę testuj tę wersję regularnie, abyś wiedział jak najszybciej, czy są jakieś problemy, którymi należy się zająć zanim ta wersja stanie się oficjalnym wydaniem.
Kiedy wydajemy nowe wersje Wykresów Google, niektóre zmiany są duże, jak na przykład zupełnie nowe typy wykresów. Inne zmiany są niewielkie, jak ulepszenia wyglądu lub zachowania istniejących wykresów.
Wielu twórców Map Google dopracowuje wygląd i działanie swoich wykresów, dopóki nie będą one dokładnie takie, jak chcą. 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. Dla tych użytkowników obsługujemy zamrożone wersje wykresów Google.
Zamrożone wersje wykresów są identyfikowane za pomocą numeru i są opisane w naszych oficjalnych wydaniach.Aby załadować zamrożoną wersję, zastąp current lub upcoming w wywołaniu google.charts.load numerem zamrożonej wersji:
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('43', {packages: }); google.charts.setOnLoadCallback(drawChart); ...</script>
Spodziewamy się, że zamrożone wersje pozostaną dostępne na czas nieokreślony, chociaż możemy wycofać zamrożone wersje, które mają problemy z bezpieczeństwem. Zazwyczaj nie zapewniamy wsparcia dla zamrożonych wersji, z wyjątkiem sugestii uaktualnienia do nowszej wersji.
Załaduj ustawienia
Drugi parametr w twoim wywołaniu google.charts.load jest obiektem do określania ustawień. Dla ustawień obsługiwane są następujące właściwości.
pakiety Tablica zawierająca zero lub więcej pakietów. Każdy pakiet, który zostanie załadowany, będzie posiadał kod wymagany do obsługi zestawu funkcjonalności, zazwyczaj typu wykresu. Pakiet lub pakiety, które należy załadować są wymienione w dokumentacji dla każdego typu wykresu. Możesz uniknąć określania pakietów, jeśli użyjesz ChartWrappera, który automatycznie załaduje to, co będzie wymagane. language Kod języka lub locale, który powinien być dostosowany do tekstu, który może być częścią wykresu. Zobacz Locales, aby uzyskać więcej szczegółów. callback Funkcja, która zostanie wywołana po załadowaniu pakietów. Alternatywnie, możesz określić tę funkcję przez wywołanie
google.charts.setOnLoadCallback, jak pokazano w powyższym przykładzie. Zobacz Callback, aby uzyskać więcej szczegółów.
google.charts.load('current', { packages: , callback: drawChart });
mapsApiKey (v45) To ustawienie pozwala określić klucz, który może być używany z Geochart i Map Chart. Możesz to zrobić zamiast używać domyślnego zachowania, które może spowodować sporadyczne dławienie usług dla użytkowników. Dowiedz się, jak skonfigurować własny klucz do korzystania z usługi 'Google Maps JavaScript API’ tutaj: Get a Key/Authentication. Twój kod będzie wyglądał mniej więcej tak:
var myMapsApiKey = 'SomeMagicToSetThis'; google.charts.load('45', { packages: , mapsApiKey: myMapsApiKey });
safeMode (v47) Gdy ustawiony na true, wszystkie wykresy i etykiety narzędzi, które generują HTML z danych dostarczonych przez użytkownika, oczyszczą go przez usunięcie niebezpiecznych elementów i atrybutów. Alternatywnie (v49+), biblioteka może być ładowana w trybie bezpiecznym za pomocą skrótu, który akceptuje te same ustawienia ładowania, ale zawsze ładuje „aktualną” wersję:
google.charts.safeLoad({ packages: });
Lokale
Lokale są używane do dostosowywania tekstu do kraju lub języka, wpływając na formatowanie wartości takich jak waluty, daty i liczby.
Domyślnie, Google Charts jest ładowany z locale „en”. Możesz zastąpić to ustawienie domyślne przez jawne określenie locale w ustawieniach ładowania.
Aby załadować wykres sformatowany dla określonego locale, użyj ustawienia language w następujący sposób:
// Load Google Charts for the Japanese locale. google.charts.load('current', {'packages':, 'language': 'ja'});
Podążaj za tym linkiem, aby zobaczyć przykład na żywo.
Callback
Przed użyciem któregokolwiek z pakietów załadowanych przez google.charts.load musisz poczekać na zakończenie ładowania. Nie wystarczy po prostu poczekać, aż dokument skończy się ładować. Ponieważ może minąć trochę czasu zanim to ładowanie się zakończy, musisz zarejestrować funkcję wywołania zwrotnego. Można to zrobić na trzy sposoby. Albo określić ustawienie callback w swoim wywołaniu google.charts.load, albo wywołać setOnLoadCallback przekazując funkcję jako argument, albo użyć obietnicy, która jest zwracana przez wywołanie google.charts.load.
Zauważ, że dla wszystkich tych sposobów, musisz podać definicję funkcji, zamiast wywoływać funkcję. Definicja funkcji, którą podajesz może być albo funkcją nazwaną (więc po prostu podajesz jej nazwę) albo funkcją anonimową. Kiedy pakiety skończą się ładować, ta funkcja zwrotna zostanie wywołana bez żadnych argumentów. Program ładujący będzie również czekał na zakończenie ładowania dokumentu przed wywołaniem wywołania zwrotnego.
Jeśli chcesz narysować więcej niż jeden wykres, możesz albo zarejestrować więcej niż jedną funkcję wywołania zwrotnego za pomocą setOnLoadCallback, albo możesz połączyć je w jedną funkcję. Dowiedz się więcej o tym, jak narysować 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 użycie obietnicy, która jest zwracana z wywołania google.charts.load. Robisz to poprzez dodanie wywołania do metody then() z kodem, który wygląda jak poniższy.
google.charts.load('upcoming', {packages: }).then(drawChart);
Jedną z korzyści używania obietnicy jest to, że możesz łatwo narysować więcej wykresów, po prostu łącząc więcej wywołań .then(anotherFunction). Użycie obietnicy wiąże również wywołanie zwrotne z konkretnymi pakietami wymaganymi dla tego wywołania zwrotnego, co jest ważne, jeśli chcesz załadować więcej pakietów za pomocą innego wywołania google.charts.load().
Update Library Loader Code
Poprzednie wersje Google Charts używały innego kodu do ładowania bibliotek. W poniższej tabeli przedstawiono stary kod programu ładującego biblioteki i nowy kod.
<script type="text/javascript" src="https://www.google.com/jsapi"></script><script type="text/javascript"> google.load("visualization", "1", {packages:}); google.setOnLoadCallback(drawChart);</script>
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('current', {packages: }); google.charts.setOnLoadCallback(drawChart);</script>
Aby zaktualizować istniejące wykresy, można zastąpić stary kod programu ładującego biblioteki nowym kodem.Należy jednak pamiętać o ograniczeniach ładowania bibliotek opisanych powyżej.
Leave a Reply