Kitaplıkları Yükle

Bu sayfada, Google Grafik kitaplıklarının nasıl yükleneceği gösterilmektedir.

Temel Kitaplık Yükleme

Birkaç istisna dışında, Google Grafikleri'ne sahip tüm web sayfaları, web sayfasının <head> bölümüne aşağıdaki satırları içermelidir:

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

Bu örneğin ilk satırı, yükleyicinin kendisini yükler. Kaç grafik çizmeyi planladığınızdan bağımsız olarak yükleyiciyi yalnızca bir kez yükleyebilirsiniz. Yükleyiciyi yükledikten sonra, belirli grafik türleri için paketleri yüklemek üzere google.charts.load işlevini bir veya daha fazla kez çağırabilirsiniz.

google.charts.load için ilk bağımsız değişken, dize olarak sürüm adı veya numarasıdır. 'current' değerini belirtirseniz bu, Google Charts'ın en son resmi sürümünün yüklenmesine neden olur. Bir sonraki yayın için adayı denemek istiyorsanız bunun yerine 'upcoming' politikasını kullanın. Genel olarak ikisi arasında çok küçük bir fark olur ve yeni bir sürümün kullanıma sunulduğu durumlar dışında bunlar tamamen aynı olur. upcoming özelliğini kullanmanın yaygın nedenlerinden biri, Google'ın önümüzdeki bir veya iki ay içinde kullanıma sunacağı yeni bir grafik türünü veya özelliği test etmek istemedir. (Yakında kullanıma sunulacak yayınları forumumuzda duyuruyoruz. Grafiklerinizde yapılan değişikliklerin kabul edilebilir olması için, duyurulduğunda bunları denemenizi öneririz.)

Yukarıdaki örnekte bir corechart (çubuk, sütun, çizgi, alan, basamaklı alan, balon, pasta, halka, birleşik, şamdan, histogram, dağılım) görüntülemek istediğiniz varsayılmıştır. Farklı veya ek bir grafik türü istiyorsanız yukarıdaki corechart yerine uygun paket adını değiştirin veya ekleyin (ör. {packages: ['corechart', 'table', 'sankey']}. Paket adını her grafiğin belgeler sayfasının "Yükleniyor" bölümünde bulabilirsiniz.

Bu örnekte ayrıca, web sayfanızın bir yerinde tanımlanmış drawChart adında bir JavaScript işlevinizin olduğu da varsayılır. Bu işlevi istediğiniz gibi adlandırabilirsiniz ancak işlevin küresel olarak benzersiz olduğundan ve google.charts.setOnLoadCallback çağrınızda belirtmeden önce tanımlandığından emin olun.

Not: Google Charts'ın önceki sürümlerinde, kitaplıkları yüklemek için yukarıdakinden farklı bir kod kullanılmıştır. Mevcut grafiklerinizi yeni kodu kullanacak şekilde güncellemek için Kitaplık Yükleyici Kodunu Güncelleme bölümüne bakın.

Temel yükleme tekniğini kullanarak pasta grafik çizmenin eksiksiz bir örneğini aşağıda bulabilirsiniz:

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

Ayrıntıları Yükleme

Önce yükleyicinin kendisini yüklemeniz gerekir. Bu işlem, src="https://www.gstatic.com/charts/loader.js" içeren ayrı bir script etiketi içinde yapılır. Bu etiket, belgenin head veya body içinde olabilir ya da yükleme sırasında veya yükleme tamamlandıktan sonra dokümana dinamik olarak eklenebilir. 

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

Yükleyici yüklendikten sonra google.charts.load numaralı telefonu arayabilirsiniz. Çağıracağınız yer, dokümanın head veya body bölümündeki bir script etiketinde olabilir ve doküman yüklenirken veya yüklendikten sonra herhangi bir zamanda bunu çağırabilirsiniz.

45 sürümünden itibaren, ek paket yüklemek için google.charts.load hizmetini birden fazla kez arayabilirsiniz. Ancak bunu yapmaktan kaçınmanız daha güvenli olacaktır. Her defasında aynı sürüm numarasını ve dil ayarlarını sağlamanız gerekir.

Artık eski JSAPI autoload URL parametresini kullanabilirsiniz ancak bu parametrenin değeri sıkı JSON biçimlendirmesi ve URL kodlaması kullanmalıdır. JavaScript'te, jsonObject kodlamasını şu kodla yapabilirsiniz: encodeURIComponent(JSON.stringify(jsonObject)).

Sınırlamalar

v45'ten önceki sürümleri kullanıyorsanız Google Grafiklerini nasıl yükleyeceğinizle ilgili birkaç küçük ama önemli sınırlama vardır:

  1. google.charts.load numaralı telefonu yalnızca bir kez arayabilirsiniz. Ancak ihtiyacınız olacak tüm paketleri tek bir görüşmede listeleyebilirsiniz. Böylece, ayrı çağrılar yapmanıza gerek kalmaz.
  2. ChartWrapper kullanıyorsanız ChartWrapper'ın bunları sizin için otomatik olarak yüklemesi yerine, ihtiyaç duyacağınız tüm paketleri açıkça yüklemeniz gerekir.
  3. Coğrafi grafik ve Harita Grafiği için hem eski kitaplık yükleyiciyi hem de yeni kitaplık yükleyicisini yüklemeniz gerekir. Bu durum yalnızca v45'ten önceki sürümler için geçerlidir ve sonraki sürümlerde bunu yapmamanız gerekir. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Sürüm Adı veya Numarası Yükleme

google.charts.load çağrınızın ilk bağımsız değişkeni sürüm adı veya numarasıdır. Şu anda yalnızca iki özel sürüm adı ve dondurulmuş birkaç sürüm vardır.

akım
Bu, her yeni sürüm yayınladığımızda değişen en son resmi sürüm içindir. Bu sürüm ideal olarak iyi test edilmiştir ve hatasızdır ancak çalıştığından emin olduktan sonra bunun yerine dondurulmuş belirli bir sürüm belirtebilirsiniz.
yaklaşan
Bu, bir sonraki sürüm için ve hâlâ test aşamasındadır ve resmi mevcut sürüm olmadan önce geçerlidir. Bu sürüm resmi sürüm haline gelmeden önce ele alınması gereken bir sorun olup olmadığını en kısa sürede öğrenmek için lütfen bu sürümü düzenli olarak test edin.

Google Grafikler'in yeni sürümlerini kullanıma sunduğumuzda, bazı değişiklikler (ör. yepyeni grafik türleri) büyüktür. Diğer değişiklikler, mevcut grafiklerin görünümü veya davranışındaki iyileştirmeler gibi küçük değişikliklerdir.

Google Grafik oluşturucularının çoğu, grafiklerinin görünümünde ve tarzında ince ayar yapar ve grafiklerini tam olarak istedikleri şeye ulaştırır. Bazı içerik üreticiler, gelecekte ne gibi iyileştirmeler yaparsak yapalım grafiklerinin hiçbir zaman değişmeyeceğini bilme konusunda kendilerini daha rahat hissedebilirler. Bu kullanıcılar için dondurulmuş Google Grafikleri desteklenmektedir.

Dondurulmuş grafik sürümleri sayıyla tanımlanır ve Resmi Yayınlar bölümümüzde açıklanmıştır. Dondurulmuş bir sürümü yüklemek için google.charts.load çağrınızdaki current veya upcoming değerini, dondurulmuş sürüm numarasıyla değiştirin:

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

Dondurulmuş sürümlerin süresiz olarak kullanılabilir durumda kalmasını bekliyoruz. Bununla birlikte, güvenlik açısından sorunlu olan dondurulmuş sürümleri kullanımdan kaldırabiliriz. Daha yeni bir sürüme geçmenizi önermediğimiz durumlar dışında, genellikle dondurulmuş sürümler için destek sağlanmaz.

Ayarları Yükleme

google.charts.load çağrınızdaki ikinci parametre, ayarları belirtmek için kullanılan bir nesnedir. Aşağıdaki özellikler ayarlar için desteklenir.

paketler
Sıfır veya daha fazla paket dizisi. Yüklenen her paket, bir dizi işlevi desteklemek için gereken koda sahiptir. Bu kod genellikle bir grafik türüdür. Yüklemeniz gereken paket veya paketler, her grafik türünün dokümanlarında listelenmiştir. Gerekli olacakları otomatik olarak yüklemek için ChartWrapper kullanıyorsanız hiçbir paket belirtmekten kaçınabilirsiniz.
language
Grafiğin parçası olabilecek metni özelleştirmek için kullanılması gereken dil veya yerel ayarın kodu. Daha fazla bilgi için Yerel Ayarlar'a bakın.
geri çağırma
Paketler yüklendikten sonra çağrılacak bir işlev. Alternatif olarak, yukarıdaki örnekte gösterildiği gibi google.charts.setOnLoadCallback öğesini çağırarak bu işlevi belirtebilirsiniz. Daha fazla bilgi için Geri Arama bölümüne bakın. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) Bu ayar, Coğrafi grafik ve Harita Grafiği ile kullanabileceğiniz bir anahtar belirtmenizi sağlar. Varsayılan davranışı kullanmak yerine bunu tercih edebilirsiniz. Bu durum, kullanıcılarınız için hizmetin zaman zaman kısıtlanmasına neden olabilir. "Google Maps JavaScript API" hizmetini kullanmak için kendi anahtarınızı nasıl oluşturacağınızı buradan öğrenebilirsiniz: Anahtar/Kimlik Doğrulama Alın Kodunuz aşağıdaki gibi görünecektir: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) Doğru değerine ayarlandığında, kullanıcı tarafından sağlanan verilerden HTML oluşturan tüm grafikler ve ipuçları, güvenli olmayan öğeleri ve özellikleri çıkararak grafiği temizler. Alternatif olarak (v49+) kitaplık, aynı yükleme ayarlarını kabul eden ancak her zaman "geçerli" sürümü yükleyen bir kısayol kullanılarak güvenli modda yüklenebilir: 
  google.charts.safeLoad({ packages: ['corechart'] });

Yerel ayarlar

Yerel ayarlar, bir ülkeye veya dile ilişkin metni özelleştirmek için kullanılır ve para birimleri, tarihler ve sayılar gibi değerlerin biçimlendirmesini etkiler.

Varsayılan olarak, Google Grafikleri "en" yerel ayarıyla yüklenir. Yükleme ayarlarında açıkça bir yerel ayar belirterek bu varsayılan ayarı geçersiz kılabilirsiniz.

Belirli bir yerel ayara göre biçimlendirilmiş bir grafiği yüklemek için language ayarını şu şekilde kullanın: 

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

Canlı bir örnek için bu bağlantıyı takip edin.

Geri Arama

google.charts.load tarafından yüklenen paketlerden herhangi birini kullanmadan önce yüklemenin tamamlanmasını beklemeniz gerekir. Belgenin yüklenmesinin tamamlanmasını beklemek yeterli değildir. Bu yüklemenin tamamlanması biraz zaman alabileceğinden bir geri çağırma işlevi kaydetmeniz gerekir. Bunu yapmanın üç yolu vardır. google.charts.load çağrınızda bir callback ayarı belirtin veya setOnLoadCallback bir işlevi bağımsız değişken olarak ileterek ya da google.charts.load çağrısıyla döndürülen Vaat'i kullanın.

Tüm bu yöntemler için işlevi çağırmak yerine işlev tanımını sağlamanız gerektiğini unutmayın. Sağladığınız işlev tanımı, adlandırılmış bir işlev (yani adını vermeniz yeterlidir) veya anonim bir işlev olabilir. Paketlerin yüklenmesi bittiğinde bu geri çağırma işlevi, bağımsız değişken olmadan çağrılır. Yükleyici, geri çağırmayı çağırmadan önce dokümanın yüklenmesinin tamamlanmasını da bekler.

Birden fazla grafik çizmek isterseniz setOnLoadCallback öğesini kullanarak birden fazla geri çağırma işlevi kaydedebilir veya bunları tek bir işlevde birleştirebilirsiniz. Bir Sayfada Birden Fazla Grafik Çizme hakkında daha fazla bilgi edinin. 

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

Promise aracılığıyla geri arama

Geri aramanızı kaydetmenin diğer bir yolu, google.charts.load çağrısından döndürülen Vaat'i kullanmaktır. Bunu, then() yöntemine aşağıdakine benzer bir koda sahip bir çağrı ekleyerek yapabilirsiniz. 

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

Promise'ı kullanmanın avantajlarından biri, sadece daha fazla .then(anotherFunction) çağrısı zincirlemesi halinde kolayca daha fazla grafik çizebilmenizdir. Promise'ın kullanılması, geri çağırmayı bu geri çağırma için gereken belirli paketlere de bağlar. Bu, başka bir google.charts.load() çağrısıyla daha fazla paket yüklemek istiyorsanız önemlidir.

Kitaplık Yükleyici Kodunu Güncelleme

Google Charts'ın önceki sürümleri, kitaplıkları yüklemek için farklı bir kod kullanıyordu. Aşağıdaki tabloda, yeni ve eski kitaplık yükleyici kodu karşılaştırılmıştır.

Eski Kitaplık Yükleyici Kodu 
<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>
Yeni Kitaplık Yükleyici Kodu 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

Mevcut grafiklerinizi güncellemek için eski kitaplık yükleyici kodunu yeni kodla değiştirebilirsiniz. Ancak, kitaplıkların yüklenmesiyle ilgili yukarıda açıklanan sınırlamaları göz önünde bulundurun.