Kirjastojen lataaminen
Tällä sivulla näytetään, miten Googlen kaaviokirjastot ladataan.
Peruskirjastojen lataaminen
Vähäisiä poikkeuksia lukuun ottamatta kaikkien Google-kaavioita sisältävien WWW-sivujen tulisi sisällyttää seuraavat rivit WWW-sivun <head>-osaan:
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('current', {packages: }); google.charts.setOnLoadCallback(drawChart); ...</script>
Esimerkin ensimmäinen rivi lataa itse lataajan. Voit ladata lataajan vain kerran riippumatta siitä, kuinka monta kaaviota aiot piirtää. Kun olet ladannut lataajan, voit kutsua google.charts.load-funktiota yhden tai useamman kerran ladataksesi tiettyjen kaaviotyyppien paketteja.
google.charts.load:n ensimmäinen argumentti on version nimi tai numero,merkkijonona. Jos annat 'current', tämä saa aikaan sen, että ladataan Google Chartsin viimeisin virallinen versio. Jos haluat kokeilla seuraavan version ehdokasta, käytä sen sijaan 'upcoming'. Yleensä näiden kahden välillä on hyvin vähän eroa, ja ne ovat täysin identtisiä paitsi silloin, kun uusi julkaisu on tekeillä. Yleinen syy upcoming:n käyttämiseen on se, että haluat testata uutta kaaviotyyppiä tai ominaisuutta, jonka Google aikoo julkaista seuraavan kuukauden tai kahden aikana. (Ilmoitamme tulevista julkaisuista foorumillamme ja suosittelemme, että kokeilet niitä, kun ne julkistetaan, varmistaaksesi, että kaikki muutokset kaavioihisi ovat hyväksyttäviä.)
Yllä olevassa esimerkissä oletetaan, että haluat näyttää corechart(palkki, pylväs, viiva, viiva, pinta-ala, asteittainen pinta-ala, kupla, piiraa, donitsi, yhdistelmä, kynttilänjalkakuvio, histogrammi, sironta). Jos haluat toisen tai ylimääräisen kaaviotyypin, korvaa tai lisää asianmukainen pakettinimi yllä olevan corechart:n tilalle (esim. {packages: }. Löydät paketin nimen kunkin kaavion dokumentointisivun ”Loading”-osiosta.
Tässä esimerkissä oletetaan myös, että sinulla on JavaScript-funktio nimeltä drawChart määriteltynä jossakin web-sivullasi. Voit nimetä funktion miten haluat, mutta varmista, että se on globaalisti uniikki ja että se on määritelty ennen kuin viittaat siihen kutsussa google.charts.setOnLoadCallback.
Huomautus: Aiemmissa Google-kaavioiden versioissa käytettiin kirjastojen lataamiseen koodia, joka poikkeaa edellä esitetystä. Jos haluat päivittää olemassa olevat kaaviot käyttämään uutta koodia, katso kohtaa Update Library Loader Code.
Tässä on täydellinen esimerkki piirakkakaavion piirtämisestä peruslataustekniikalla:
<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>
Latauksen yksityiskohdat
Ensin on ladattava itse latausohjelma, mikä tehdään erillisessä script-tagissa, jossa on src="https://www.gstatic.com/charts/loader.js". Tämä tagi voi olla joko asiakirjan head tai body:ssä, tai se voidaan lisätä dynaamisesti asiakirjaan sen lataamisen aikana tai lataamisen päätyttyä.
<script src="https://www.gstatic.com/charts/loader.js"></script>
Kun lataaja on ladattu, voit vapaasti kutsua google.charts.load. Kutsukohta voi olla script-tunnisteessa asiakirjan head– tai body-kohdassa, ja voit kutsua sitä joko asiakirjan ollessa vielä latautumassa tai milloin tahansa sen jälkeen, kun lataaminen on päättynyt.
Versiosta 45 lähtien voit kutsua google.charts.load useammin kuin kerran, jotta voit ladata lisää paketteja, vaikka on turvallisempaa, jos voit välttää sitä. Sinun on annettava sama versionumero ja samat kieliasetukset joka kerta.
Voit nyt käyttää vanhaa JSAPI autoload URL-parametria, mutta tämän parametrin arvon on käytettävä tiukkaa JSON-muotoilua ja URL-koodausta. JavaScriptissä voit tehdä jsonObject:n koodauksen tällä koodilla: encodeURIComponent(JSON.stringify(jsonObject)).
Rajoitukset
Jos käytät versioita ennen v45, Google Chartsin lataamiseen liittyy pari pientä mutta tärkeää rajoitusta:
- Voit kutsua
google.charts.loadvain kerran. Voit kuitenkin luetella kaikki tarvitsemasi paketit yhdellä kutsulla, joten erillisiä kutsuja ei tarvitse tehdä. - Jos käytät ChartWrapperia, sinun on nimenomaisesti ladattava kaikki tarvitsemasi paketit sen sijaan, että luotat ChartWrapperin lataavan ne automaattisesti puolestasi.
- Geochart- ja Map Chart -kaavioita varten sinun on ladattava sekä vanha että uusi kirjastonlataaja. Tämä koskee taas vain versioita ennen v45, eikä tätä pitäisi tehdä myöhemmille versioille.
<script src="https://www.gstatic.com/charts/loader.js"></script><script src="https://www.google.com/jsapi"></script>
Lataa version nimi tai numero
google.charts.load-kutsun ensimmäinen argumentti on version nimi tai numero. Tällä hetkellä on vain kaksi erityistä versionimeä ja useita jäädytettyjä versioita.
current Tämä tarkoittaa viimeisintä virallista versiota, joka muuttuu joka kerta, kun julkaisemme uuden version. Tämä versio on mieluiten hyvin testattu ja virheetön, mutta saatat haluta määrittää sen sijaan tietyn jäädytetyn version, kun olet vakuuttunut siitä, että se toimii. upcoming Tämä on seuraavaa julkaisua varten, kun sitä vielä testataan ja ennen kuin siitä tulee virallinen nykyinen versio. Testaa tätä versiota säännöllisesti, jotta tiedät mahdollisimman pian, onko ongelmia, jotka pitäisi korjata ennen kuin versiosta tulee virallinen julkaisu.
Kun julkaisemme uusia versioita Google Chartsista, jotkut muutokset ovat suuria, kuten täysin uusia kaaviotyyppejä. Toiset muutokset ovat pieniä, kuten parannuksia olemassa olevien kaavioiden ulkoasuun tai käyttäytymiseen.
Monet Google-kaavioiden kehittäjät hienosäätävät kaavioidensa ulkoasua ja tuntumaa, kunnes ne ovat juuri sellaisia kuin he haluavat. Joillekin tekijöille saattaa olla mukavampaa tietää, että heidän kaavionsa eivät koskaan muutu riippumatta siitä, mitä parannuksia teemme tulevaisuudessa. Näitä käyttäjiä varten tuemme jäädytettyjä Google-kaavioita.
Jäädytetyt kaavioversiot tunnistetaan numerolla, ja ne on kuvattu virallisissa julkaisuissamme.Jos haluat ladata jäädytetyn version, korvaa google.charts.load-kutsussa current tai upcoming jäädytetyn version numerolla:
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('43', {packages: }); google.charts.setOnLoadCallback(drawChart); ...</script>
Odotamme, että jäädytetyt versiot pysyvät saatavilla määräämättömän ajan, vaikka saatammekin luopua jäädytetystä versiosta, jos siihen liittyy tietoturvaongelmia. Emme yleensä tarjoa tukea jäädytetyille versioille, paitsi ehdotamme avuliaasti, että päivität uudempaan versioon.
Lataa asetukset
Kutsun google.charts.load toinen parametri on objekti asetusten määrittämistä varten. Asetuksille tuetaan seuraavia ominaisuuksia.
packages Nollan tai useamman paketin joukko. Jokaisessa ladattavassa paketissa on koodia, jota tarvitaan tietyn toiminnallisuuden, tyypillisesti kaaviotyypin, tukemiseen. Ladattava paketti tai ladattavat paketit on lueteltu kunkin kaaviotyypin dokumentaatiossa. Voit välttää pakettien määrittelyn, jos käytät ChartWrapper-pakettia, joka lataa tarvittavat paketit automaattisesti. language Sen kielen tai lokaalin koodi, jonka pitäisi olla mukauttamassa tekstiä, joka voi olla osa kaaviota. Katso lisätietoja kohdasta Locales. callback Funktio, jota kutsutaan, kun paketit on ladattu. Vaihtoehtoisesti voit määrittää tämän funktion kutsumallagoogle.charts.setOnLoadCallback, kuten yllä olevassa esimerkissä on esitetty. Katso lisätietoja kohdasta Callback.
google.charts.load('current', { packages: , callback: drawChart });
mapsApiKey (v45) Tämän asetuksen avulla voit määrittää avaimen, jota voit käyttää Geochartin ja Map Chartin kanssa. Saatat haluta tehdä tämän sen sijaan, että käyttäisit oletuskäyttäytymistä, joka voi johtaa satunnaiseen palvelun kuristumiseen käyttäjillesi. Lue täältä, miten voit määrittää oman avaimen Google Maps JavaScript API -palvelun käyttöä varten: Hanki avain/tunnistus. Koodisi näyttää jotakuinkin tältä:
var myMapsApiKey = 'SomeMagicToSetThis'; google.charts.load('45', { packages: , mapsApiKey: myMapsApiKey });
safeMode (v47) Kun arvoksi asetetaan true, kaikki kaaviot ja työkaluvihjeet, jotka luovat HTML:ää käyttäjän antamista tiedoista, puhdistavat sen poistamalla turvattomat elementit ja attribuutit. Vaihtoehtoisesti (v49+) kirjasto voidaan ladata turvallisessa tilassa käyttämällä pikakuvaketta, joka hyväksyy samat latausasetukset, mutta lataa aina ”nykyisen” version:
google.charts.safeLoad({ packages: });
Lokaalit
Lokaaleja käytetään tekstin mukauttamiseen maata tai kieltä varten, mikä vaikuttaa arvojen, kuten valuuttojen, päivämäärien ja numeroiden, muotoiluun.
Oletusarvoisesti Google-kaaviot ladataan ”en”-lokaalilla. Voit ohittaa tämän oletusarvon määrittämällä nimenomaisesti lokaalin latausasetuksissa.
Lataaksesi kaavion, joka on muotoiltu tiettyä lokaalia varten, käytä language -asetusta seuraavasti:
// Load Google Charts for the Japanese locale. google.charts.load('current', {'packages':, 'language': 'ja'});
Seuraa tätä linkkiä live-esimerkin katsomiseksi.
Callback
Ennen kuin voit käyttää mitä tahansa google.charts.load:llä ladattuja paketteja, sinun on odotettava, että lataus päättyy. Ei riitä, että vain odotat, että dokumentti latautuu loppuun. Koska voi kestää jonkin aikaa ennen kuin lataus on valmis, sinun on rekisteröitävä callback-funktio. Tämä voidaan tehdä kolmella tavalla. Joko määrittelet callback-asetuksen google.charts.load-kutsussa, tai kutsut setOnLoadCallback:tä välittäen funktion argumenttina, tai käytät Promisea, jonka google.charts.load-kutsu palauttaa.
Huomaa, että kaikissa näissä tavoissa sinun täytyy antaa funktion määritelmä, eikä kutsua funktiota. Antamasi funktion määritelmä voi olla joko nimetty funktio (eli annat vain sen nimen) tai nimetön funktio. Kun pakettien lataaminen on päättynyt, tätä takaisinkutsufunktiota kutsutaan ilman argumentteja. Latausohjelma odottaa myös, että dokumentin lataus on päättynyt, ennen kuin se kutsuu takaisinkutsutoimintoa.
Jos haluat piirtää useamman kuin yhden kaavion, voit joko rekisteröidä useamman kuin yhden callback-funktion käyttämällä setOnLoadCallback tai voit yhdistää ne yhdeksi funktioksi. Lue lisää siitä, miten voit piirtää useita kaavioita yhdelle sivulle.
google.charts.setOnLoadCallback(drawChart1); google.charts.setOnLoadCallback(drawChart2); // OR google.charts.setOnLoadCallback( function() { // Anonymous function that calls drawChart1 and drawChart2 drawChart1(); drawChart2(); });
Takaisinkutsu lupauksen avulla
Toinen tapa rekisteröidä takaisinkutsu on käyttää lupausta, joka palautetaan google.charts.load-kutsusta. Tämä tehdään lisäämällä kutsu then()-metodiin koodilla, joka näyttää seuraavalta.
google.charts.load('upcoming', {packages: }).then(drawChart);
Yksi hyöty Promisen käyttämisestä on se, että tällöin voit helposti piirtää lisää kaavioita vain ketjuttamalla lisää .then(anotherFunction)-kutsuja. Promisen käyttäminen sitoo takaisinkutsun myös tiettyihin paketteihin, joita kyseinen takaisinkutsu vaatii, mikä on tärkeää, jos haluat ladata lisää paketteja toisella google.charts.load()-kutsulla.
Kirjastojen latauskoodin päivittäminen
Google Chartsin aiemmat versiot käyttivät eri koodia kirjastojen lataamiseen. Alla olevassa taulukossa näkyy vanha kirjastonlatauskoodi verrattuna uuteen.
<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>
Päivittääksesi olemassa olevat kaaviot voit korvata vanhan kirjastonlatauskoodin uudella koodilla.Pidä kuitenkin mielessäsi edellä kuvatut kirjastojen lataamiseen liittyvät rajoitukset.
Leave a Reply