Etkinlikleri İşleme

Bu sayfada, bir grafikte tetiklenen etkinlikler nasıl dinleneceği ve işleneceği açıklanmaktadır.

İçindekiler

Genel bakış

Google grafikleri, dinleyebileceğiniz etkinlikleri tetikleyebilir. Etkinlikler, kullanıcı grafiğiyle tetiklenebilir. Örneğin, kullanıcı bir grafiği tıkladığında. Belirli etkinlikler tetiklendiğinde, muhtemelen o etkinliğe özel verilerle birlikte çağrılacak bir JavaScript yöntemi kaydedebilirsiniz.

Her grafik kendi etkinliklerini tanımlar. Bu grafikteki dokümanlarda, her etkinliğin ne zaman tetiklendiği, ne anlama geldiği ve etkinlikle ilişkili tüm bilgilerin nasıl geri alınacağı açıklanmalıdır. Bu sayfada, bir grafikten etkinlik almak için nasıl kaydolacağınız ve bu işlemleri nasıl gerçekleştireceğiniz açıklanmaktadır.

Seçilebilir herhangi bir grafiğin tetikleneceği bir etkinlik vardır: seçili etkinlik. Ancak, bu etkinliğin davranışı ve anlamı her grafik tarafından tanımlanır.

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

Etkinliğe Kaydolma ve İşleme

Etkinlik işleyicilerinizi kaydetmek için google.visualization.events.addListener() veya addOneTimeListener() yöntemini, etkinliği gösteren grafiğin adıyla, dinlenecek etkinliğin dize adıyla ve etkinlik tetiklendiğinde çağırılacak işlevin adıyla birlikte çağırırsınız. İşleviniz, tetiklenen etkinlik olan tek bir parametreyi kabul etmelidir. Bu etkinlik, grafik dokümanlarında açıklandığı gibi etkinlikle ilgili özel bilgilere sahip olabilir.

Önemli: Grafiğinizde hazır bir etkinlik gösteriliyorsa grafikten yöntem göndermeye veya etkinlik almaya başlamadan önce etkinliğin tetiklenmesini bekleyin. Bu grafikler hazır etkinlik yayınlamadan önce çalışabilir ancak bu davranış garanti edilmez.

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

// 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 söz konusu tablo nesnesindeki etkinlikleri dinlemek için kaydolacağını unutmayın. Yalnızca belirli bir nesneden etkinlik almak için kaydolabilirsiniz.

Aşağıda 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, bilgileri genellikle iki şekilde sunar: Bilgileri işleyici olarak parametreye iletme veya genel bir nesneye bilgi ekleme. Etkinliğin bilgileri açığa çıkarıp çıkarmadığı ve nasıl açığa çıkardığı, bu grafiğin dokümanlarında açıklanmalıdır. Her iki bilgi türünü de nasıl alabileceğiniz aşağıda açıklanmıştır:

Etkinliğinize işleyiciye iletilen etkinlik bilgileri

Grafikte kullanılan veriler, işleme işlevinize parametre olarak aktarılırsa aşağıdaki şekilde gösterilir:

// 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 parametrenin, grafik için belgelenmesi gereken bir özelliği olur. Etkinlik bilgilerini bu şekilde açığa çıkaran bir grafik örneği için Tablo grafiğinin sayfa etkinliğine bakın.

Global nesneye aktarılan etkinlik bilgileri

Bazı etkinlikler bunun yerine global bir nesnenin özelliğini değiştirir. Daha sonra bunu isteyebilirsiniz. Bunun yaygın bir örneği, kullanıcı bir grafiğin bir bölümünü seçtiğinde tetiklenen "seç" etkinliğidir. Bu durumda kod, mevcut seçimin ne olduğunu öğrenmek için grafikte getSelection() yöntemini çağırır. Aşağıda seçilen etkinlik hakkında 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çilebilecek tüm grafiklerde, seçilen öğenin değerlerini grafikte alabilmeniz için standart şekilde çalışan bir "select" etkinliği tetiklenmelidir. (Bununla birlikte, bir grafiğin bu şekilde davranması kesin olarak gerekmez; grafiğinizin dokümanlarına bakın.)

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

• Seçilen etkinlik, işleyiciye hiçbir özellik veya nesne iletmez (işlev işleyiciniz parametreye parametre aktarılmasını beklememelidir).
• Grafik, seçilen veri öğelerini açıklayan bir nesne dizisi döndüren getSelection() yöntemini kullanmalıdır. 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 temel verileri açıklar, grafikteki HTML öğelerini açıklamaz.) Seçili öğenin verilerini almak için DataTable.getValue() veya getFormattedValue() yöntemini aramanız gerekir.
  Hem row hem de column belirtilirse seçilen öğe bir hücredir. Yalnızca row belirtilirse seçilen öğe bir satırdır. Yalnızca column belirtilirse seçilen öğe bir sütundur.
• Grafik, temel tabloda seçilen seçimi değiştirmek için setSelection(selection) yöntemini kullanmalıdır ve grafikte ilgili verileri seçer. getSelection() dizisine benzer bir dizi olan selection parametresi. Burada her öğe row ve column özelliklerine sahip bir nesnedir. row özelliği, seçilen satırın dizinini DataTable içinde, column özelliği ise seçilen sütunun dizinini DataTable 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çilen öğe bir hücredir. Yalnızca row belirtilirse seçilen öğe bir satırdır. Yalnızca column belirtilirse seçilen öğe bir sütundur.

Bazı uyarılar:

• 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 bir "select" etkinliğini tetikleyemez ve bazı grafikler yalnızca satır seçimini veya sütun seçimini tamamen destekleyebilir. Grafiklerdeki dokümanlar, desteklediği etkinlikleri ve yöntemleri tanımlar.
• Çoklu seçim, farklı grafiklerde farklı şekilde işlenir (bazılarına izin verilmez).
• Seçili verileri okumak için işleyicinizde DataTable.getValue() işlevini çağırmanız gerekir. Bunu etkinleştirmenin en kolay yolu DataTable nesnesini genel yapmaktır.

Aşağıdaki örnekte, bir tablo grafiğindeki bir öğe seçildiğinde, seçilen tablo öğelerinin bulunduğu bir uyarı kutusu açılmaktadır:

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

Aşağıda bu örnek için işleyici kodu verilmiştir:

// 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, bu tablolarda draw() çağırmanızdan sonra hazır bir etkinlik oluşturarak grafiğin oluşturulduğunu ve özellikler döndürmeye veya diğer yöntem çağrılarını işlemeye hazır olduğunu gösterir. draw() yöntemini çağırdıktan sonra, yöntemi çağırmadan önce hazır etkinliği her zaman dinlemeniz gerekir.

Genel olarak, "hazır" etkinliğini ortaya çıkaran grafikler aşağıdaki spesifikasyonlarla tasarlanmıştır:

• Hazır etkinlik, işleyiciye hiçbir özellik iletmez (işlev işleyiciniz parametreye parametre aktarılmasını beklememelidir).
• Grafik, etkileşim için hazır olduktan sonra hazır etkinliği yanmalıdır. Grafiğin çizimi eşzamansızsa yalnızca draw yöntemi sona erdiğinde değil, etkileşim yöntemleri gerçekten çağrıldığında etkinliğin tetiklenmesi önemlidir.
• draw() yöntemini çağırmadan önce bu etkinliğe bir dinleyici eklemeniz gerekir. Aksi takdirde, dinleyici ayarlanıncaya kadar etkinlik tetiklenebilir ve siz yakalayamazsınız.
• Hazır etkinlik tetiklenmeden önce etkileşim yöntemlerini çağırarak bu yöntemlerin düzgün çalışmaması riskiyle karşı karşıya kalırsınız.

"Hazır" bir etkinliği tetiklemeyen grafikler, draw yöntemi sona erdikten hemen sonra etkileşime hazırdır ve kontrolü kullanıcıya döndürür. Grafiğiniz hazır bir etkinliği tetikliyorsa burada gösterildiği gibi, yöntemlerini çağırmadan önce 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 hiçbir parametre iletilmedi.

error etkinliği

Listeler bir şekilde sorunla karşılaşıldığında sorunsuz şekilde işlem yapabilmeniz için bir hata olayı vermelidir. Etkinlik işleyiciye, hatanın bir açıklaması ve her grafiğe özel özel etkinlik özellikleri iletilir. Sonraki adımlarda meydana gelebilecek hataları tespit etmek için grafiği örneklendirdikten hemen sonra bu etkinliğe abone olmanız gerekir.

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

Hata Etkinliği İşleyici Söz Dizimi

function myErrorHandler(err){...}

Hata etkinliği işleyici, aşağıdaki üyelerle birlikte bir nesne iletilmelidir:

• id [Zorunlu] - Grafiği içeren DOM öğesinin kimliği veya grafik oluşturulamadığı takdirde grafik yerine bir hata mesajı gösterilir.
• message [Zorunlu] - Hatayı açıklayan kısa bir mesaj dizesi.
• detailedMessage [İsteğe bağlı] - Hatanın ayrıntılı açıklaması.
• option [İ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 seçim, aynı veri tablosunu kullanan iki grafik arasında senkronize edilir. Seçimi diğer grafikte senkronize etmek için her iki grafiği de 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 çalışırken görmek için tablo satırlarında veya grafik öğelerinde aşağıdaki grafikleri tıklayın: