Memuat Library

Halaman ini menunjukkan cara memuat library Google Chart.

Pemuatan Library Dasar

Dengan sedikit 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 bisa memuat loader satu kali, berapa pun diagram yang ingin Anda gambar. Setelah memuat loader, Anda dapat memanggil fungsi google.charts.load satu atau beberapa kali untuk memuat paket untuk jenis diagram tertentu.

Argumen pertama untuk google.charts.load adalah nama atau nomor versi, sebagai string. Jika Anda menentukan 'current', hal ini menyebabkan rilis resmi terbaru Google Chart dimuat. Jika Anda ingin mencoba kandidat untuk rilis berikutnya, gunakan 'upcoming'. Secara umum, akan ada sedikit perbedaan di antara keduanya, dan keduanya akan menjadi sangat identik kecuali saat rilis baru sedang berlangsung. Alasan umum untuk menggunakan upcoming adalah karena 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 sebaiknya Anda mencobanya saat diumumkan, untuk memastikan bahwa perubahan apa pun pada diagram dapat diterima.)

Contoh di atas mengasumsikan bahwa Anda ingin menampilkan corechart (kolom, kolom, garis, area, area bertahap, balon, lingkaran, donat, kombinasi, candlestick, histogram, sebar). Jika Anda menginginkan jenis diagram yang berbeda atau tambahan, ganti atau tambahkan nama paket yang sesuai untuk corechart di atas (misalnya, {packages: ['corechart', 'table', 'sankey']}. Anda dapat menemukan nama paket di bagian 'Memuat' 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 ditetapkan sebelum merujuknya dalam panggilan Anda ke google.charts.setOnLoadCallback.

Catatan: Versi Google Chart sebelumnya menggunakan kode yang berbeda dari yang 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>

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 head atau body, atau dapat disisipkan secara dinamis ke dokumen saat dimuat atau setelah pemuatan selesai.

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

Setelah loader dimuat, Anda dapat memanggil google.charts.load. Ketika dipanggil, tag tersebut dapat berada di tag script di head atau body, 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 lebih aman jika Anda dapat menghindarinya. Anda harus memberikan nomor versi dan setelan bahasa yang sama setiap saat.

Sekarang Anda 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 Anda memuat Google Chart:

  1. Anda hanya dapat memanggil google.charts.load satu kali. Namun, Anda dapat mencantumkan semua paket yang diperlukan dalam satu panggilan, sehingga tidak perlu melakukan panggilan terpisah.
  2. Jika menggunakan ChartWrapper, Anda harus memuat semua paket yang diperlukan secara eksplisit, bukan mengandalkan ChartWrapper untuk otomatis memuatnya bagi Anda.
  3. Untuk Geochart dan Diagram Peta, 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>

Memuat Nama atau Nomor Versi

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

current
Ini adalah rilis resmi terbaru yang berubah setiap kali kami meluncurkan rilis baru. Versi ini idealnya diuji dengan baik dan bebas bug, tetapi sebaiknya Anda menentukan versi beku tertentu setelah Anda merasa puas.
mendatang
Ini untuk rilis berikutnya, selagi masih diuji dan sebelum menjadi rilis resmi saat ini. Uji versi ini secara rutin sehingga 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 berukuran besar, seperti jenis diagram yang benar-benar baru. Perubahan kecil lainnya, seperti peningkatan tampilan atau perilaku diagram yang ada.

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

Versi diagram yang dibekukan akan diidentifikasi menurut angka, dan dijelaskan dalam Rilis Resmi kami. Untuk memuat versi frozen, ganti current atau upcoming dalam panggilan google.charts.load Anda 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 berharap versi frozen akan tetap tersedia tanpa batas waktu, meskipun kami dapat menghentikan versi beku yang memiliki masalah keamanan. Kami biasanya tidak akan memberikan dukungan untuk versi frozen, kecuali untuk membantu 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 nol atau beberapa paket. Setiap paket yang dimuat akan memiliki kode yang diperlukan untuk mendukung serangkaian fungsi, biasanya jenis diagram. Paket atau beberapa paket yang perlu Anda muat tercantum dalam dokumentasi untuk setiap jenis diagram. Anda dapat menghindari menetapkan paket apa pun jika menggunakan ChartWrapper untuk otomatis memuat apa yang diperlukan.
language
Kode untuk bahasa atau lokalitas yang harus menyesuaikan teks yang mungkin menjadi bagian dari diagram. Lihat Lokal untuk mengetahui detail selengkapnya.
callback
Fungsi yang akan dipanggil setelah paket dimuat. Atau, Anda dapat menentukan fungsi ini dengan memanggil google.charts.setOnLoadCallback seperti yang ditunjukkan pada contoh di atas. Lihat Callback untuk detail selengkapnya.
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
apiApiKey
(v45) Setelan ini memungkinkan Anda menentukan kunci yang dapat digunakan dengan Geografis dan Diagram Peta. Anda mungkin ingin melakukan hal ini, bukan menggunakan perilaku default yang dapat mengakibatkan throttling layanan sesekali bagi pengguna. 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  });
Mode aman
(v47) Jika ditetapkan ke benar, 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 untuk negara atau bahasa, yang memengaruhi pemformatan nilai seperti mata uang, tanggal, dan angka.

Secara default, Google Chart dimuat dengan lokalitas "en". Anda dapat mengganti default ini dengan menentukan lokal secara eksplisit dalam 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 melihat contoh langsung.

Callback

Sebelum Anda dapat menggunakan paket yang dimuat oleh google.charts.load, Anda harus menunggu pemuatan selesai. Anda tidak perlu menunggu dokumen selesai dimuat. Karena perlu waktu beberapa saat sebelum pemuatan ini selesai, Anda harus 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 untuk semua cara ini, Anda harus memberikan definisi fungsi, bukan memanggil fungsi. Definisi fungsi yang Anda berikan dapat berupa fungsi bernama (sehingga Anda hanya memberikan namanya) atau fungsi anonim. Jika paket telah 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 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). Menggunakan Promise juga mengaitkan 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 ini menunjukkan kode loader library lama dan 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 library pemuatan yang dijelaskan di atas.