Etkinlikleri İşleme

Bu sayfada, bir grafik tarafından tetiklenen etkinliklerin nasıl dinleneceği ve işleneceği açıklanmaktadır.

İçindekiler

  1. Genel bakış
  2. Etkinliğe Kaydolma ve Etkinlik Yönetme
  3. Etkinlik Bilgilerini Alma
  4. select Etkinliği
  5. Hazır Etkinliği
  6. Hata Etkinliği
  7. Etkinlik İşleme Örneği

Genel bakış

Google grafikleri, dinleyebileceğiniz etkinlikleri tetikleyebilir. Etkinlikler, kullanıcının bir grafiği tıklaması gibi kullanıcı işlemleri tarafından tetiklenebilir. Belirli etkinlikler tetiklendiğinde, muhtemelen söz konusu etkinliğe özel verilerle birlikte çağrılacak bir JavaScript yöntemini kaydedebilirsiniz.

Her grafik kendi etkinliklerini tanımlar. Bu matrisin belgelerinde her bir etkinliğin ne zaman tetiklendiği, ne anlama geldiği ve etkinlikle ilgili bilgilerin nasıl geri alınacağı açıklanmalıdır. Bu sayfada, bir grafikten etkinlik almak için nasıl kayıt yapılacağı ve bunların nasıl işleneceği açıklanmaktadır.

Seçilebilir bir grafiğin tetiklenmesi gereken bir etkinlik vardır: seçili etkinlik. Ancak bu etkinliğin davranışı ve anlamı her grafikle tanımlanır.

Grafik etkinliklerinin standart DOM etkinliklerinden ayrı ve farklı olduğunu unutmayın.

Etkinliğe Kaydolma ve Etkinlik Yönetme

Etkinlik işleyicilerinizi kaydetmek için google.visualization.events.addListener() veya addOneTimeListener() yöntemini çağırarak etkinliği gösteren grafiğin adını, dinlenecek etkinliğin dize adını ve bu etkinlik tetiklendiğinde çağrılacak işlevin adını belirtin. İşleviniz, tetiklenen etkinlik olan tek bir parametreyi kabul etmelidir. Bu etkinlik, grafik belgelerinde açıklandığı gibi etkinlikle ilgili özel bilgiler içerebilir.

Önemli: Grafiğinizde hazır bir etkinlik gösteriliyorsa yöntem göndermeye veya grafikten etkinlik almaya çalışmadan önce her zaman bu etkinliğin tetiklenmesini beklemeniz gerekir. Bu grafikler, hazır bir etkinlik gerçekleştirmeden önce çalışabilir ancak bu konuda garanti verilmez.

Aşağıdaki kod snippet'i, kullanıcı bir tablo satırını her tıkladığında bir uyarı kutusu gösteriyor:

// Create a table chart on your page.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

Bunun yalnızca bu belirli tablo nesnesine ilişkin etkinlikleri dinlemek için kaydedileceğini unutmayın. Yalnızca belirli bir nesneden etkinlik almak için kaydolabilirsiniz.

Burada gösterildiği gibi bir işlev tanımı da aktarabilirsiniz:

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Etkinlik Bilgilerini Alma

Etkinlikler genellikle bilgileri iki şekilde açığa çıkarır: bilgileri işleyici işlevine parametre olarak ileterek veya genel nesneye bilgi ekleyerek. Etkinliğin bilgileri açığa çıkarıp göstermediği ve nasıl göründüğü, ilgili grafik dokümanlarında açıklanmalıdır. Her iki bilgi türünü de şu şekilde alabilirsiniz:

İşleyicinize iletilen etkinlik bilgileri

Grafik, verileri işleme işlevinize parametre olarak iletirse bu verileri burada gösterildiği gibi alırsınız:

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

İşleyicinize iletilen parametre, grafik için belgelenmesi gereken bir özelliğe sahip olur. Etkinlik bilgilerini bu şekilde gösteren bir grafik örneği için Tablo grafiğinin sayfa etkinliğine bakın.

Global nesneye iletilen etkinlik bilgileri

Bunun yerine bazı etkinlikler, global nesnenin bir özelliğini değiştirir. Bunu daha sonra isteyebilirsiniz. Bunun yaygın bir örneği, kullanıcı bir grafiğin bir bölümünü seçtiğinde tetiklenen "select" etkinliğidir. Bu durumda, geçerli seçimin ne olduğunu öğrenmek için kodun grafikte getSelection() çağrısı yapması gerekir. Aşağıdaki seçme etkinliğiyle ilgili daha fazla bilgi verilmiştir.

// orgChart is my global orgchart chart variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');

select Etkinliği

Daha önce de belirtildiği gibi, seçilebilen tüm grafikler, seçili öğenin değerlerini grafikte almanızı sağlayacak standart bir şekilde çalışan bir "select" etkinliğini etkinleştirmelidir. (Ancak bir grafiğin bu şekilde davranması için mutlak bir gereksinim yoktur. Grafiğinizle ilgili dokümanları inceleyin).

Genel olarak, "select" etkinliğini gösteren grafikler aşağıdaki spesifikasyonlarla tasarlanmıştır:

  • Select etkinliği, işleyiciye herhangi bir özellik veya nesne iletmez (işlev işleyiciniz, kendisine herhangi bir parametrenin aktarılmasını beklememelidir).
  • Grafikte, seçilen veri öğelerini açıklayan bir nesne dizisi döndüren getSelection() yöntemi gösterilmelidir . Bu nesneler row ve column özelliklerine sahiptir. row ve column, DataTable içinde seçilen öğenin satır ve sütun dizinleridir. (Seçim etkinlikleri, grafikteki HTML öğelerini değil, grafikteki temel verileri açıklar.) Seçili öğenin verilerini almak için DataTable.getValue() veya getFormattedValue() numaralı telefonu aramanız gerekir.
    Hem row hem de column belirtilirse seçili öğe bir hücredir. Yalnızca row belirtilirse seçili öğe bir satır olur. Yalnızca column belirtilirse seçili öğe bir sütun olur.
  • Temel tabloda seçimi değiştirmek ve grafikte ilgili verileri seçmek için grafikte setSelection(selection) yöntemi gösterilmelidir . getSelection() dizisine benzer bir dizi olan selection parametresi. Burada her öğe row ve column özelliklerine sahip bir nesnedir. row özelliği, DataTable içinde seçili satırın dizinini, column özelliği ise seçili sütunun dizinini DataTable içinde tanımlar. Bu yöntem çağrıldığında, grafik yeni seçimin ne olduğunu görsel olarak belirtmelidir. setSelection() kullanımı, bir "select" etkinliğini tetiklememelidir.
    Hem row hem de column belirtilirse seçili öğe bir hücredir. Yalnızca row belirtilirse seçili öğe bir satır olur. Yalnızca column belirtilirse seçili öğe bir sütun olur.

Dikkat edilmesi gereken bazı noktalar:

  • Grafik, seçimin bir kısmını yoksayabilir. Örneğin, yalnızca seçili satırları gösterebilen bir tablo, setSelection uygulamasındaki hücre veya sütun öğelerini yoksayabilir.)
  • Bazı grafikler "select" etkinliğini tetiklemeyebilir ve bazı grafikler yalnızca tüm satır seçimini veya tüm sütun seçimini destekleyebilir. Her grafiğin belgeleri, desteklediği etkinlikleri ve yöntemleri tanımlar.
  • Çoklu seçim, farklı grafiklerde farklı şekilde işlenir (bazıları buna izin vermez).
  • Seçilen verileri okumak için işleyicinizde DataTable.getValue() yöntemini çağırmanız gerekir. Bunu etkinleştirmenin en basit yolu, DataTable nesnesini global hale getirmektir.

Aşağıdaki örnekte, bir tablo grafiği öğesi seçildiğinde seçili tablo öğelerini içeren bir uyarı kutusu açılır:

Tablo grafiğin yalnızca satır seçim etkinliklerini tetiklediğini unutmayın. Ancak kodun genel olduğunu ve satır, sütun ve hücre seçim etkinlikleri için kullanılabileceğini unutmayın.

Bu örnekteki işleyici kodu şöyledir:

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
function selectHandler() {
  var selection = table.getSelection();
  var message = '';
  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      var str = data.getFormattedValue(item.row, item.column);
      message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
    } else if (item.row != null) {
      var str = data.getFormattedValue(item.row, 0);
      message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
    } else if (item.column != null) {
      var str = data.getFormattedValue(0, item.column);
      message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

Hazır Etkinlik

Çoğu grafik eşzamansız olarak oluşturulur. Tüm Google grafikleri, siz üzerlerinde draw() çağırdıktan sonra, grafiğin oluşturulduğunu ve özellikleri döndürmeye veya diğer yöntem çağrılarını işlemeye hazır olduğunu belirtmek için hazır bir etkinlik gönderir. draw() işlevini çağırdıktan sonra, hazır etkinlikteki yöntemleri çağırmaya çalışmadan önce her zaman hazır etkinliği dinlemeniz gerekir.

Genel olarak, "hazır" etkinliğini gösteren grafikler aşağıdaki spesifikasyonlarla tasarlanmıştır:

  • Hazır etkinliği, işleyiciye herhangi bir özellik iletmez (işlev işleyiciniz, kendisine herhangi bir parametrenin aktarılmasını beklememelidir).
  • Grafik, etkileşime hazır hale geldikten sonra hazır etkinliği tetikler . Grafiğin çizimi eşzamansızsa etkinliğin yalnızca draw yöntemi sona erdiğinde değil, etkileşim yöntemleri gerçekten çağrılabildiği zaman tetiklenmesi önemlidir.
  • Bu etkinliğe işleyici eklenmesi, draw() yöntemi çağrılmadan önce yapılmalıdır. Aksi takdirde etkinlik, işleyici oluşturulmadan önce tetiklenebilir ve etkinliği yakalayamazsınız.
  • Hazır etkinlik tetiklenmeden önce etkileşim yöntemlerini çağırarak bu yöntemlerin düzgün çalışmama riskiyle karşı karşıya kalırsınız.

Bu kurala göre, "hazır" etkinliği tetiklemeyen grafikler, draw yöntemi sona erdikten hemen sonra etkileşim için hazır olur ve kontrolü kullanıcıya geri gönderir. Grafiğiniz hazır bir etkinlik tetikliyorsa burada gösterildiği gibi, üzerinde yöntemler çağırmadan önce etkinliğin atılmasını beklemeniz gerekir:

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

Hazır Etkinlik İşleyici Söz Dizimi

function myReadyHandler(){...}

Hazır etkinlik işleyiciye herhangi bir parametre iletilmedi.

Hata Etkinliği

Grafikler bir tür hatayla karşılaştıklarında sorunsuz bir şekilde başa çıkabilmeniz için hata etkinliği vermelidir. Etkinlik işleyiciye hatanın bir açıklaması ve her grafiğe özgü özel etkinlik özellikleri iletilir. Sonraki adımlarda oluşabilecek hataları yakalamak için grafiği örneklendirdikten hemen sonra bu etkinliğe abone olmanız gerekir.

Hataları kullanıcıya ayrıntılı şekilde göstermenize yardımcı olması için goog.visualization.errors yardımcı işlevlerini kullanabilirsiniz.

Hata Olay İşleyicisi Söz Dizimi

function myErrorHandler(err){...}

Hata etkinliği işleyicisine aşağıdaki üyelere sahip bir nesne iletilmelidir:

  • id [Zorunlu] - Grafiği içeren DOM öğesinin kimliği veya oluşturulamazsa grafik yerine görüntülenen bir hata mesajı.
  • message [Zorunlu] - Hatayı açıklayan kısa bir mesaj dizesi.
  • detailedMessage [İsteğe bağlı] - Hatanın ayrıntılı bir açıklaması.
  • options [İsteğe bağlı]- Bu hataya ve grafik türüne uygun özel parametreler içeren bir nesne.

Etkinlik İşleme Örneği

Aşağıdaki örnekte hem getSelection() hem de setSelection() gösterilmektedir. Bu örnek, aynı veri tablosunu kullanan iki grafik arasında seçimi senkronize eder. Diğer grafikteki seçimi senkronize etmek için iki grafikten birini tıklayın.

// Create our two charts.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, {});

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table chart.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Seçimi uygulamalı olarak görmek için aşağıdaki tablo satırlarında veya grafik öğelerinde bulunan grafikleri tıklayın: