Načítání knihoven
Tato stránka ukazuje, jak načíst knihovny grafů Google.
Základní načítání knihoven
Všechny webové stránky s grafy Google by měly až na výjimky obsahovat následující řádky v <head> webové stránky:
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('current', {packages: }); google.charts.setOnLoadCallback(drawChart); ...</script>
První řádek tohoto příkladu načítá samotný zavaděč. Zavaděč můžete načíst pouze jednou bez ohledu na to, kolik grafů plánujete vykreslit. Po načtení zavaděče můžete zavolat funkci google.charts.load jednou nebo vícekrát, abyste načetli balíčky pro jednotlivé typy grafů.
Prvním argumentem funkce google.charts.load je název nebo číslo verze,jako řetězec. Pokud zadáte 'current', způsobí to, že se načte nejnovější oficiální vydáníKarty Google. Pokud chcete vyzkoušet kandidátskou verzi pro dalšívydání, použijte místo toho 'upcoming'. Obecně mezi nimi bude velmi malý rozdíl a budou zcela identické s výjimkou případů, kdy se připravuje nová verze. Častým důvodem pro použití upcoming je, že chcete otestovat nový typ grafu nebo funkci, kterou se Google chystá vydat v příštím měsíci nebo dvou. (Chystané verze oznamujeme na našem fóru a doporučujeme, abyste si je po oznámení vyzkoušeli a ujistili se, že případné změny v grafech jsou přijatelné.)
Výše uvedený příklad předpokládá, že chcete zobrazit corechart(sloupcový, sloupcový, čárový, plošný, stupňovitý, bublinový, koláčový, koblihový, kombinovaný,svíčkový, histogramový, rozptylový). Pokud chcete jiný nebo další typ grafu, nahraďte nebo přidejte příslušný název balíčku za výše uvedený corechart (např. {packages: }. Název balíčku najdete v části „Načítání“ na stránce s dokumentací ke každému grafu.
Tento příklad také předpokládá, že máte někde na své webové stránce definovanou funkci JavaScriptu s názvem drawChart. Tuto funkci můžete pojmenovat, jak chcete, ale ujistěte se, že je globálně jedinečná a že je definována předtím, než na ni odkážete ve volání funkcegoogle.charts.setOnLoadCallback.
Poznámka: Předchozí verze Google Charts používaly k načítání knihoven kód, který se liší od výše uvedeného. Chcete-li aktualizovat stávající grafy tak, aby používaly nový kód, přečtěte si část Aktualizace kódu pro načítání knihoven.
Zde je kompletní příklad vykreslení koláčového grafu pomocí základní techniky načítání:
<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>
Podrobnosti o načítání
Nejprve musíte načíst samotný načítací program, což se provádí v samostatné značce script pomocí src="https://www.gstatic.com/charts/loader.js". Tento tag může být buď v head nebo body dokumentu, nebo může být do dokumentu vložen dynamicky během načítání nebo po dokončení načítání.
<script src="https://www.gstatic.com/charts/loader.js"></script>
Po načtení můžete volat google.charts.load. Místo, kde jej zavoláte, může být ve značce script v head nebo body dokumentu a můžete jej zavolat buď ještě během načítání dokumentu, nebo kdykoli po dokončení načítání.
Od verze 45 můžete volat google.charts.load vícekrát, abyste načetli další balíčky, i když je to bezpečnější, pokud se tomu můžete vyhnout. Pokaždé musíte zadat stejné číslo verze a nastavení jazyka.
Nyní můžete použít starý parametr URL JSAPI autoload, ale hodnota tohoto parametru musí používat přísné formátování JSON a kódování URL. V jazyce JavaScript můžete kódování jsonObject provést pomocí tohoto kódu: encodeURIComponent(JSON.stringify(jsonObject)).
Omezení
Pokud používáte verze před verzí v45, existuje několik drobných, ale důležitých omezení způsobu načítání grafů Google:
- Volání
google.charts.loadmůžete provést pouze jednou. Ale všechny balíčky, které budete potřebovat, můžete uvést v jednom volání, takže není třeba provádět samostatná volání. - Používáte-li ChartWrapper, musíte explicitně načíst všechny balíčky, které budete potřebovat, a nespoléhat se na to, že je ChartWrapper načte automaticky za vás.
- Pro Geochart a Map Chart musíte načíst jak starý, tak nový zavaděč knihoven. Opět platí pouze pro verze před verzí v45 a u pozdějších verzí byste to neměli dělat.
<script src="https://www.gstatic.com/charts/loader.js"></script><script src="https://www.google.com/jsapi"></script>
Načíst název nebo číslo verze
Prvním argumentem vašeho volání google.charts.load je název nebo číslo verze. V současné době existují pouze dva speciální názvy verzí a několik zmrazených verzí.
aktuální Jedná se o poslední oficiální verzi, která se mění při každém vydání nové verze. Tato verze je v ideálním případě dobře otestovaná a bez chyb, ale možná budete chtít místo ní zadat konkrétní zmrazenou verzi, jakmile se přesvědčíte, že je funkční. upcoming Toto je pro další verzi, dokud se ještě testuje a než se stane oficiální aktuální verzí. Tuto verzi pravidelně testujte, abyste co nejdříve věděli, zda se nevyskytly nějaké problémy, které je třeba řešit, než se tato verze stane oficiálním vydáním.
Když vydáváme nové verze grafů Google, některé změnyjsou velké, například zcela nové typy grafů. Jiné změny jsou malé, například vylepšení vzhledu nebo chování stávajících grafů.
Mnoho tvůrců grafů Google dolaďuje vzhled svých grafů, dokud není přesně podle jejich představ. Někteří tvůrci se mohou cítit pohodlněji, když vědí, že se jejich grafy nikdy nezmění,bez ohledu na to, jaká vylepšení v budoucnu provedeme. Pro tyto uživatele podporujeme zmrazené verze grafů Google.
Zmrazené verze grafů jsou označeny číslem a jsou popsány v našichOficiálních verzích.Chcete-li načíst zmrazenou verzi, nahraďte current nebo upcoming ve volání google.charts.load číslem zmrazené verze:
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('43', {packages: }); google.charts.setOnLoadCallback(drawChart); ...</script>
Očekáváme, že zmrazené verze zůstanou k dispozici po neomezenou dobu,i když zmrazené verze, které mají bezpečnostní problémy, můžeme vyřadit. Obvykle nebudeme poskytovat podporu pro zmrazené verze, kromě toho, že vám vstřícně doporučíme přechod na novější verzi.
Načíst nastavení
Druhým parametrem ve vašem volání google.charts.load je objekt pro zadání nastavení. Pro nastavení jsou podporovány následující vlastnosti.
balíčky Pole nula nebo více balíčků. Každý načtený balíček bude obsahovat kód potřebný k podpoře sady funkcí, typicky typu grafu. Balíček nebo balíčky, které je třeba načíst, jsou uvedeny v dokumentaci k jednotlivým typům grafů. Zadávání balíčků se můžete vyhnout, pokud použijete nástroj ChartWrapper, který automaticky načte to, co bude potřeba. language Kód jazyka nebo locale, který by měl být pro přizpůsobení textu, který může být součástí grafu. Další podrobnosti naleznete v části Locales. callback Funkce, která bude zavolána po načtení balíčků. Alternativně můžete tuto funkci zadat volánímgoogle.charts.setOnLoadCallback, jak je ukázáno v příkladu výše. Další podrobnosti viz Callback.
google.charts.load('current', { packages: , callback: drawChart });
mapsApiKey (v45) Toto nastavení umožňuje zadat klíč, který můžete použít s Geochartem a Map Chart. Možná to budete chtít udělat raději než používat výchozí chování, které může mít za následek občasné přiškrcení služby pro vaše uživatele. Zde se dozvíte, jak nastavit vlastní klíč pro používání služby „Google Maps JavaScript API“: Získat klíč / ověření. Váš kód bude vypadat asi takto:
var myMapsApiKey = 'SomeMagicToSetThis'; google.charts.load('45', { packages: , mapsApiKey: myMapsApiKey });
safeMode (v47) Je-li nastaveno na hodnotu true, budou všechny grafy a tooltipy, které generují HTML z dat zadaných uživatelem, sanitizovány odstraněním nebezpečných prvků a atributů. Alternativně (v49+) lze knihovnu načíst v bezpečném režimu pomocí zástupce, který akceptuje stejné nastavení načítání, ale vždy načte „aktuální“ verzi:
google.charts.safeLoad({ packages: });
Locales
Locales se používají k přizpůsobení textu pro danou zemi nebo jazyk a ovlivňují formátování hodnot, jako jsou měny, data a čísla.
Ve výchozím nastavení jsou grafy Google načteny s locale „en“. Toto výchozí nastavení můžete zrušit explicitním zadáním locale v nastavení načítání.
Chcete-li načíst graf formátovaný pro konkrétní locale, použijte nastavení language takto:
// Load Google Charts for the Japanese locale. google.charts.load('current', {'packages':, 'language': 'ja'});
Podle tohoto odkazu si můžete prohlédnout živý příklad.
Callback
Než budete moci použít některý z balíčků načtených pomocí google.charts.load, musíte počkat na dokončení načítání. Nestačí pouze počkat na dokončení načítání dokumentu. Protože může nějakou dobu trvat, než se toto načítání dokončí, je třeba zaregistrovat funkci zpětného volání. To lze provést třemi způsoby. Buď zadáte nastavení callback ve svém volání google.charts.load, nebo zavoláte setOnLoadCallback předáním funkce jako argumentu, nebo použijete slib, který je vrácen voláním google.charts.load.
Všimněte si, že u všech těchto způsobů je třeba zadat definici funkce, nikoli volat funkci. Definice funkce, kterou poskytnete, může být buď pojmenovaná funkce (takže stačí uvést její jméno), nebo anonymní funkce. Po dokončení načítání balíčků bude tato zpětná funkce zavolána bez argumentů. Zavaděč také počká, až se dokument dokončí načítání, a teprve potom zavolá zpětné volání.
Pokud chcete vykreslit více než jeden graf, můžete buď zaregistrovat více než jednu funkci zpětného volání pomocí setOnLoadCallback, nebo je můžete spojit do jedné funkce. Další informace o tom, jak vykreslit více grafů na jedné stránce.
google.charts.setOnLoadCallback(drawChart1); google.charts.setOnLoadCallback(drawChart2); // OR google.charts.setOnLoadCallback( function() { // Anonymous function that calls drawChart1 and drawChart2 drawChart1(); drawChart2(); });
Zpětné volání pomocí slibu
Dalším způsobem registrace zpětného volání je použití slibu, který je vrácen z volání google.charts.load. To provedete přidáním volání metody then() s kódem, který vypadá následovně.
google.charts.load('upcoming', {packages: }).then(drawChart);
Jednou z výhod použití Promise je, že pak můžete snadno vykreslit více grafů pouhým zřetězením více volání .then(anotherFunction). Použití slibu také váže zpětné volání na konkrétní balíčky požadované pro toto zpětné volání, což je důležité, pokud chcete načíst další balíčky pomocí dalšího volání google.charts.load().
Aktualizace kódu načítání knihoven
Předchozí verze Google Charts používaly k načítání knihoven jiný kód. Následující tabulka ukazuje starý kód načítání knihoven oproti novému.
<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>
Chcete-li aktualizovat stávající grafy, můžete nahradit starý kód načítání knihoven novým kódem, mějte však na paměti výše popsaná omezení načítání knihoven.
.
Leave a Reply