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 Grafikler içeren tüm web sayfaları, web sayfasının <head> bölümünde 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. Ne kadar 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ürlerine ait paketleri yüklemek için 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 sürümün aday sürümünü denemek istiyorsanız bunun yerine 'upcoming' seçeneğini 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 seçeneğini kullanmanın yaygın bir nedeni, Google'ın önümüzdeki bir veya iki ay içinde kullanıma sunacağı yeni bir grafik türünü ya da özelliği test etmek istemenizdir. (Yakında kullanıma sunulacak sürümleri forumumuzda duyururuz ve grafiklerinizde yapılan değişikliklerin kabul edilebilir olduğundan emin olmak için duyurulduktan sonra bunları denemenizi öneririz.)

Yukarıdaki örnekte, bir corechart (çubuk, sütun, çizgi, alan, basamaklı alan, kabarcık, pasta, halka, karma, şamdan, histogram, dağılım) göstermek istediğiniz varsayılmaktadı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 doküman sayfasındaki "Yükleme" bölümünde bulabilirsiniz.

Bu örnekte, web sayfanızda bir yerde drawChart adlı bir JavaScript işlevi tanımlandığı da varsayılmıştı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 Grafikler'in önceki sürümleri, kitaplıkları yüklemek için yukarıdakinden farklı kodlar kullanıyordu. Mevcut grafiklerinizi yeni kodu kullanacak şekilde güncellemek için Kitaplık Yükleyici Kodunu Güncelleme başlıklı makaleyi inceleyin.

Temel yükleme tekniğini kullanarak pasta grafiği çizmeyle ilgili eksiksiz bir örneği 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>

Yükleme Ayrıntıları

Öncelikle yükleyiciyi yüklemeniz gerekir. Bu, src="https://www.gstatic.com/charts/loader.js" ile ayrı bir script etiketinde yapılır. Bu etiket, dokümanın head veya body bölümünde olabilir ya da doküman yüklenirken veya yükleme tamamlandıktan sonra dinamik olarak dokümana eklenebilir. 

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

Yükleyici yüklendikten sonra google.charts.load numarayı arayabilirsiniz. Bu işlevi çağırdığınız yer, dokümanın head veya body bölümündeki bir script etiketi olabilir. Ayrıca, doküman hâlâ yüklenirken veya yükleme işlemi tamamlandıktan sonra dilediğiniz zaman bu işlevi ç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'yi yalnızca bir kez arayabilirsiniz. Ancak tek bir aramada ihtiyacınız olan tüm paketleri listeleyebilirsiniz. Böylece ayrı aramalar yapmanız gerekmez.
  2. ChartWrapper kullanıyorsanız ChartWrapper'ın sizin için otomatik olarak yüklemesini beklemek yerine ihtiyacınız olan 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ükleyiciyi yüklemeniz gerekir. Bu işlem yalnızca 45 sürümünden önceki sürümler için geçerlidir ve sonraki sürümlerde yapılmamalıdır. 
    <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 birkaç dondurulmuş sürüm mevcuttur.

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, henüz test aşamasında olan ve resmi güncel sürüm haline gelmeden önce sonraki sürüm içindir. 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 öğrenebilmek için lütfen bu sürümü düzenli olarak test edin.

Google Grafikler'in yeni sürümlerini yayınladığımızda, bazı değişiklikler büyük olur (ör. tamamen yeni grafik türleri). Diğer değişiklikler, mevcut grafiklerin görünümü veya davranışındaki iyileştirmeler gibi küçük değişikliklerdir.

Birçok Google Grafiği oluşturucusu, grafiklerinin görünüm ve tarzını tam istedikleri gibi olana kadar ince ayar yapar. Gelecekte yapacağımız iyileştirmelerden bağımsız olarak, bazı içerik üreticiler listelerinin hiçbir zaman değişmeyeceğini bilmenin rahatlığını yaşayabilir. Bu kullanıcılar için dondurulmuş Google Grafikler'i destekliyoruz.

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ılabileceğini umuyoruz ancak güvenlikle ilgili endişeler taşıyan dondurulmuş sürümleri kullanımdan kaldırabiliriz. Genellikle, dondurulmuş sürümler için destek sağlamayız. Bununla birlikte, yeni bir sürüme geçmenizi önerebiliriz.

Yükleme Ayarları

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

paketler
Sıfır veya daha fazla paketten oluşan bir dizi. 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 listelenir. Gerekli olanları otomatik olarak yüklemek için bir ChartWrapper kullanırsanız paket belirtmekten kaçınabilirsiniz.
language
Grafiğin parçası olabilecek metni özelleştirmek için kullanılacak dilin veya yerel ayarın kodu. Daha fazla bilgi için Yerel Ayarlar bölümüne 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 değerini ç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 belirtmenize olanak tanır. Kullanıcılarınız için hizmetin zaman zaman kısıtlanmasıyla sonuçlanabilecek varsayılan davranışı kullanmak yerine bunu tercih edebilirsiniz. "Google Haritalar JavaScript API'si" hizmetini kullanmak için kendi anahtarınızı nasıl oluşturacağınızı buradan öğrenebilirsiniz: Anahtar Alma/Kimlik Doğrulama. Kodunuz aşağıdaki gibi görünür: 
  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 ve sonraki sürümler), kitaplık aynı yükleme ayarlarını kabul eden ancak her zaman "mevcut" sürümü yükleyen bir kısayol kullanılarak güvenli modda yüklenebilir: 
  google.charts.safeLoad({ packages: ['corechart'] });

Yerel ayarlar

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

Google Grafikler varsayılan olarak "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 grafik yüklemek için language ayarını aşağıdaki gibi 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 kullanabilmek için 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 bağımsız değişken olarak bir işlev göndererek setOnLoadCallback'yi çağırın ya da google.charts.load çağrısı tarafından döndürülen Promise'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ış işlev (bu durumda işlevin adını belirtirsiniz) veya anonim işlev olabilir. Paketler yüklendiğinde bu geri çağırma işlevi hiçbir bağımsız değişken olmadan çağrılır. Yükleyici, geri çağırma işlevini çağırmadan önce dokümanın yüklenmesinin tamamlanmasını da bekler.

Birden fazla grafik çizmek istiyorsanız setOnLoadCallback kullanarak birden fazla geri çağırma işlevi kaydedebilir veya bunları tek bir işlevde birleştirebilirsiniz. Bir Sayfada Birden Çok 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 üzerinden geri arama

Geri çağırma işlevinizi kaydetmenin bir diğer yolu da google.charts.load çağrısından döndürülen Promise'i kullanmaktır. Bunu, aşağıdaki gibi görünen bir kodla then() yöntemine çağrı ekleyerek yaparsınız. 

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

Promise'ı kullanmanın avantajlarından biri, yalnızca daha fazla .then(anotherFunction) çağrısı zincirlemesi halinde kolayca daha fazla grafik çizebilmenizdir. Promise'i kullanmak, geri aramayı bu geri arama için gereken belirli paketlere de bağlar. Bu, google.charts.load() çağrısıyla daha fazla paket yüklemek istiyorsanız önemlidir.

Kitaplık Yükleyici Kodunu Güncelleme

Google Grafikler'in önceki sürümleri, kitaplıkları yüklemek için farklı kod kullanıyordu. Aşağıdaki tabloda, eski kitaplık yükleyici kodu ile yeni kod 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 LibraryLoader 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.