Memuat Library

Halaman ini menunjukkan cara memuat library Google Chart.

Pemuatan Library Dasar

Dengan beberapa pengecualian, semua halaman web dengan Google Charts harus menyertakan baris berikut di <head> halaman web:

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

Baris pertama contoh ini memuat loader itu sendiri. Anda hanya dapat memuat loader satu kali, berapa pun jumlah diagram yang ingin Anda gambar. Setelah memuat loader, Anda dapat memanggil fungsi google.charts.load satu kali atau beberapa kali untuk memuat paket bagi jenis diagram tertentu.

Argumen pertama ke google.charts.load adalah nama atau nomor versi, sebagai string. Jika Anda menentukan 'current', rilis resmi terbaru Google Chart akan dimuat. Jika Anda ingin mencoba kandidat untuk rilis berikutnya, gunakan 'upcoming'. Secara umum, akan ada perbedaan yang sangat kecil antara keduanya, dan keduanya akan sepenuhnya identik kecuali saat rilis baru sedang berlangsung. Alasan umum untuk menggunakan upcoming adalah Anda ingin menguji jenis diagram atau fitur baru yang akan dirilis Google dalam satu atau dua bulan ke depan. (Kami mengumumkan rilis mendatang di forum kami dan sebaiknya Anda mencobanya saat diumumkan, untuk memastikan bahwa perubahan apa pun pada diagram Anda dapat diterima.)

Contoh di atas mengasumsikan bahwa Anda ingin menampilkan corechart (batang, kolom, garis, area, area berundak, balon, lingkaran, donat, kombinasi, batang lilin, histogram, sebar). Jika Anda menginginkan jenis diagram yang berbeda atau tambahan, ganti atau tambahkan nama paket yang sesuai untuk corechart di atas (mis., {packages: ['corechart', 'table', 'sankey']}. Anda dapat menemukan nama paket di bagian 'Pemuatan' pada halaman dokumentasi untuk setiap diagram.

Contoh ini juga mengasumsikan bahwa Anda memiliki fungsi JavaScript bernama drawChart yang ditentukan di suatu tempat di halaman web Anda. Anda dapat memberi nama fungsi tersebut sesuai keinginan, tetapi pastikan fungsi tersebut unik secara global dan ditentukan sebelum Anda mereferensikannya dalam panggilan ke google.charts.setOnLoadCallback.

Catatan: Google Charts versi sebelumnya menggunakan kode yang berbeda dari kode di atas untuk memuat library. Untuk memperbarui diagram yang ada agar menggunakan kode baru, lihat Memperbarui Kode Loader Library.

Berikut adalah contoh lengkap menggambar diagram lingkaran menggunakan teknik pemuatan dasar:

<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>

Detail Pemuatan

Pertama, Anda harus memuat loader itu sendiri, yang dilakukan dalam tag script terpisah dengan src="https://www.gstatic.com/charts/loader.js". Tag ini dapat berada di head atau body dokumen, atau dapat disisipkan secara dinamis ke dalam dokumen saat sedang dimuat atau setelah pemuatan selesai. 

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

Setelah loader dimuat, Anda bebas memanggil google.charts.load. Tempat Anda memanggilnya dapat berupa tag script di head atau body dokumen, dan Anda dapat memanggilnya saat dokumen masih dimuat atau kapan saja setelah selesai dimuat.

Mulai versi 45, Anda dapat memanggil google.charts.load lebih dari satu kali untuk memuat paket tambahan, meskipun akan lebih aman jika Anda dapat menghindarinya. Anda harus memberikan nomor versi dan setelan bahasa yang sama setiap kali.

Anda kini dapat menggunakan parameter URL autoload JSAPI lama, tetapi nilai parameter ini harus menggunakan format JSON dan encoding URL yang ketat. Di JavaScript, Anda dapat melakukan encoding jsonObject dengan kode ini: encodeURIComponent(JSON.stringify(jsonObject)).

Batasan

Jika Anda menggunakan versi sebelum v45, ada beberapa batasan kecil tetapi penting terkait cara memuat Google Charts:

  1. Anda hanya dapat memanggil google.charts.load sekali. Namun, Anda dapat mencantumkan semua paket yang akan Anda perlukan dalam satu panggilan, sehingga tidak perlu melakukan panggilan terpisah.
  2. Jika menggunakan ChartWrapper, Anda harus secara eksplisit memuat semua paket yang diperlukan, bukan mengandalkan ChartWrapper untuk memuatnya secara otomatis untuk Anda.
  3. Untuk Geochart dan Map Chart, Anda harus memuat loader library lama dan loader library baru. Sekali lagi, ini hanya untuk versi sebelum v45, dan Anda tidak boleh melakukannya untuk versi yang lebih baru. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Muat Nama atau Nomor Versi

Argumen pertama panggilan google.charts.load Anda adalah nama atau nomor versi. Saat ini hanya ada dua nama versi khusus, dan beberapa versi yang dibekukan.

current
Ini untuk rilis resmi terbaru yang berubah setiap kali kami merilis rilis baru. Versi ini idealnya telah diuji dengan baik dan bebas bug, tetapi Anda dapat menentukan versi frozen tertentu setelah merasa puas bahwa versi tersebut berfungsi.
mendatang
Ini untuk rilis berikutnya, saat masih diuji dan sebelum menjadi rilis resmi saat ini. Uji versi ini secara rutin agar Anda mengetahui sesegera mungkin apakah ada masalah yang harus ditangani sebelum versi ini menjadi rilis resmi.

Saat kami merilis versi baru Google Chart, beberapa perubahannya besar, seperti jenis diagram yang benar-benar baru. Perubahan lainnya bersifat kecil, seperti peningkatan pada tampilan atau perilaku diagram yang ada.

Banyak pembuat Diagram Google menyesuaikan tampilan dan nuansa diagram mereka hingga sesuai dengan keinginan mereka. Beberapa kreator mungkin merasa lebih nyaman mengetahui bahwa tangga lagu mereka tidak akan pernah berubah, terlepas dari peningkatan apa pun yang kami lakukan di masa mendatang. Untuk pengguna tersebut, kami mendukung Google Charts beku.

Versi diagram frozen diidentifikasi berdasarkan angka, dan dijelaskan dalam Rilis Resmi kami. Untuk memuat versi beku, ganti current atau upcoming dalam panggilan google.charts.load dengan nomor versi beku:

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

Kami memperkirakan bahwa versi frozen akan tetap tersedia tanpa batas waktu, meskipun kami dapat menghentikan versi frozen yang memiliki masalah keamanan. Kami biasanya tidak akan memberikan dukungan untuk versi yang dibekukan, kecuali untuk menyarankan agar Anda mengupgrade ke versi yang lebih baru.

Setelan Muat

Parameter kedua dalam panggilan google.charts.load Anda adalah objek untuk menentukan setelan. Properti berikut didukung untuk setelan.

paket
Array yang berisi nol atau beberapa paket. Setiap paket yang dimuat akan memiliki kode yang diperlukan untuk mendukung serangkaian fungsi, biasanya jenis diagram. Paket atau paket yang perlu Anda muat tercantum dalam dokumentasi untuk setiap jenis diagram. Anda dapat menghindari penentuan paket apa pun jika menggunakan ChartWrapper untuk memuat secara otomatis apa yang akan diperlukan.
language
Kode untuk bahasa atau lokalitas yang harus digunakan untuk menyesuaikan teks yang mungkin merupakan bagian dari diagram. Lihat Lokal untuk detail selengkapnya.
callback
Fungsi yang akan dipanggil setelah paket dimuat. Atau, Anda dapat menentukan fungsi ini dengan memanggil google.charts.setOnLoadCallback seperti yang ditunjukkan dalam contoh di atas. Lihat Callback untuk detail selengkapnya. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) Setelan ini memungkinkan Anda menentukan kunci yang dapat digunakan dengan Geochart dan Map Chart. Sebaiknya lakukan hal ini, bukan menggunakan perilaku default yang dapat menyebabkan throttling layanan sesekali untuk pengguna Anda. Pelajari cara menyiapkan kunci Anda sendiri untuk menggunakan layanan 'Google Maps JavaScript API' di sini: Mendapatkan Kunci/Autentikasi. Kode akan terlihat seperti ini: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) Jika ditetapkan ke true, semua diagram dan tooltip yang menghasilkan HTML dari data yang disediakan pengguna akan membersihkannya dengan menghapus elemen dan atribut yang tidak aman. Atau (v49+), library dapat dimuat dalam mode aman menggunakan pintasan yang menerima setelan pemuatan yang sama, tetapi selalu memuat versi "saat ini": 
  google.charts.safeLoad({ packages: ['corechart'] });

Lokalitas

Lokal digunakan untuk menyesuaikan teks bagi suatu negara atau bahasa, sehingga memengaruhi format nilai seperti mata uang, tanggal, dan angka.

Secara default, Google Charts dimuat dengan lokalitas "en". Anda dapat mengganti setelan default ini dengan menentukan lokalitas secara eksplisit di setelan pemuatan.

Untuk memuat diagram yang diformat untuk lokalitas tertentu, gunakan setelan language seperti ini: 

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

Ikuti link ini untuk melihat contoh langsung.

Telepon Balik

Sebelum dapat menggunakan paket apa pun yang dimuat oleh google.charts.load, Anda harus menunggu pemuatan selesai. Tidak cukup hanya menunggu dokumen selesai dimuat. Karena pemuatan ini mungkin memerlukan waktu beberapa saat sebelum selesai, Anda perlu mendaftarkan fungsi callback. Ada tiga cara untuk melakukannya. Tentukan setelan callback dalam panggilan google.charts.load, atau panggil setOnLoadCallback yang meneruskan fungsi sebagai argumen, atau gunakan Promise yang ditampilkan oleh panggilan google.charts.load.

Perhatikan bahwa untuk semua cara ini, Anda perlu memberikan definisi fungsi, bukan memanggil fungsi. Definisi fungsi yang Anda berikan dapat berupa fungsi bernama (jadi Anda hanya perlu memberikan namanya) atau fungsi anonim. Setelah paket selesai dimuat, fungsi callback ini akan dipanggil tanpa argumen. Loader juga akan menunggu dokumen selesai dimuat sebelum memanggil callback.

Jika ingin menggambar lebih dari satu diagram, Anda dapat mendaftarkan lebih dari satu fungsi callback menggunakan setOnLoadCallback, atau menggabungkannya menjadi satu fungsi. Pelajari lebih lanjut cara Menggambar Beberapa Diagram di Satu Halaman. 

  google.charts.setOnLoadCallback(drawChart1);
  google.charts.setOnLoadCallback(drawChart2);
  // OR
  google.charts.setOnLoadCallback(
    function() { // Anonymous function that calls drawChart1 and drawChart2
         drawChart1();
         drawChart2();
      });

Callback melalui Promise

Cara lain untuk mendaftarkan callback adalah dengan menggunakan Promise yang ditampilkan dari panggilan google.charts.load. Anda melakukannya dengan menambahkan panggilan ke metode then() dengan kode yang terlihat seperti berikut. 

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

Salah satu manfaat menggunakan Promise adalah Anda dapat dengan mudah menggambar lebih banyak diagram hanya dengan merantai lebih banyak panggilan .then(anotherFunction). Penggunaan Promise juga akan mengikat callback ke paket tertentu yang diperlukan untuk callback tersebut, yang penting jika Anda ingin memuat lebih banyak paket dengan panggilan google.charts.load() lainnya.

Memperbarui Kode Loader Library

Google Chart versi sebelumnya menggunakan kode yang berbeda untuk memuat library. Tabel di bawah menunjukkan kode loader library lama versus yang baru.

Kode Loader Library Lama 
<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>
Kode Loader Library Baru 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

Untuk memperbarui diagram yang ada, Anda dapat mengganti kode loader library lama dengan kode baru. Namun, perhatikan batasan pada library pemuatan yang dijelaskan di atas.