Memuat Library

Halaman ini menunjukkan cara memuat library Google Chart.

Pemuatan Library Dasar

Dengan beberapa pengecualian, semua halaman web dengan Google Chart 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 akan digambar. Setelah memuat loader, Anda dapat memanggil fungsi google.charts.load satu kali atau beberapa kali untuk memuat paket bagi jenis diagram tertentu.

Argumen pertama untuk 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, hanya akan ada sedikit perbedaan di antara keduanya, dan keduanya akan benar-benar identik, kecuali saat rilis baru sedang berlangsung. Alasan umum untuk menggunakan upcoming adalah Anda ingin menguji jenis atau fitur diagram baru yang akan dirilis Google dalam satu atau dua bulan ke depan. (Kami mengumumkan rilis mendatang di forum kami dan menyarankan Anda untuk mencobanya saat diumumkan, untuk memastikan perubahan pada diagram 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 'Memuat' pada halaman dokumentasi untuk setiap diagram.

Contoh ini juga mengasumsikan bahwa Anda memiliki fungsi JavaScript dengan nama 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 Chart versi sebelumnya menggunakan kode yang berbeda dengan kode di atas untuk memuat library. Untuk memperbarui diagram yang ada agar dapat 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>

Memuat Detail

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 dalam 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 dilakukan dalam tag script di head atau body dokumen, dan Anda dapat memanggilnya saat dokumen masih dimuat atau kapan saja setelah dokumen selesai dimuat.

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

Sekarang Anda dapat menggunakan parameter URL autoload JSAPI lama, tetapi nilai parameter ini harus menggunakan pemformatan 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 yang penting terkait cara Anda memuat Google Chart:

  1. Anda hanya dapat menelepon google.charts.load satu kali. Namun, Anda dapat membuat daftar semua paket yang diperlukan 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, setelan ini hanya tersedia 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>

Memuat Nama atau Nomor Versi

Argumen pertama panggilan google.charts.load Anda adalah nama atau nomor versi. Hanya ada dua nama versi khusus saat ini, dan beberapa versi frozen.

current
Ini untuk rilis resmi terbaru yang berubah setiap kali kami meluncurkan rilis baru. Versi ini idealnya diuji dengan baik dan bebas bug, tetapi Anda sebaiknya menentukan versi frozen tertentu setelah yakin bahwa versi tersebut berfungsi dengan baik.
mendatang
Ini untuk rilis berikutnya, saat masih dalam tahap pengujian dan sebelum menjadi rilis resmi saat ini. Uji versi ini secara rutin agar Anda dapat segera mengetahui apakah ada masalah yang harus diatasi 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 Tangga Lagu Google menyesuaikan tampilan dan nuansa diagram mereka sampai terlihat seperti yang mereka inginkan. Beberapa kreator mungkin merasa lebih nyaman mengetahui bahwa tangga lagu mereka tidak akan pernah berubah, terlepas dari peningkatan yang kami lakukan di masa mendatang. Untuk pengguna tersebut, kami mendukung Google Chart yang dibekukan.

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.

Memuat Setelan

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

paket
Array yang berisi nol paket atau lebih. Setiap paket yang dimuat akan memiliki kode yang diperlukan untuk mendukung serangkaian fungsi, biasanya berupa jenis diagram. Paket atau paket yang perlu Anda muat tercantum dalam dokumentasi untuk setiap jenis diagram. Anda dapat menghindari penetapan paket apa pun jika menggunakan ChartWrapper untuk memuat apa yang diperlukan secara otomatis.
language
Kode untuk bahasa atau lokalitas yang diperlukan untuk menyesuaikan teks yang mungkin menjadi 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 mengetahui detail selengkapnya. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) Setelan ini memungkinkan Anda menentukan kunci yang dapat digunakan dengan Geochart dan Diagram Peta. Anda mungkin perlu menggunakan tindakan ini daripada menggunakan perilaku default yang dapat mengakibatkan 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 Anda 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'] });

Lokal

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

Secara default, Google Chart dimuat dengan lokal "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 berikut: 

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

Ikuti link ini untuk contoh langsung.

Telepon Balik

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

Perhatikan bahwa dengan semua cara ini, Anda perlu memberikan definisi fungsi, bukan memanggil fungsi. Definisi fungsi yang Anda berikan dapat berupa fungsi bernama (jadi Anda cukup menyebutkan 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 Anda adalah dengan menggunakan Promise yang ditampilkan dari panggilan google.charts.load. Anda dapat 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 merangkai 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 kode loader 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.