رسیدگی به رویدادها

این صفحه نحوه گوش دادن و رسیدگی به رویدادهایی که توسط نمودار منتشر می شوند را شرح می دهد.

فهرست

1. بررسی اجمالی
2. ثبت نام و مدیریت یک رویداد
3. بازیابی اطلاعات رویداد
4. رویداد را انتخاب کنید
5. رویداد آماده
6. رویداد خطا
7. مثال مدیریت رویداد

بررسی اجمالی

نمودارهای گوگل می‌توانند رویدادهایی را که می‌توانید به آن‌ها گوش دهید فعال کنند. رویدادها می‌توانند با اقدامات کاربر، مانند زمانی که کاربر روی نمودار کلیک می‌کند، فعال شوند. می‌توانید یک متد جاوا اسکریپت را ثبت کنید تا هر زمان که رویدادهای خاصی فعال می‌شوند، احتمالاً با داده‌های خاص آن رویداد، فراخوانی شود.

هر نمودار رویدادهای خود را تعریف می‌کند، و مستندات مربوط به آن نمودار باید زمان اجرا شدن هر رویداد، معنای آن و نحوه بازگرداندن اطلاعات مرتبط با رویداد را شرح دهد. این صفحه نحوه ثبت نام برای دریافت رویدادها از نمودار و نحوه رسیدگی به آنها را شرح می دهد.

یک رویداد وجود دارد که هر نمودار قابل انتخابی باید فعال شود: رویداد انتخاب. با این حال، رفتار و معنای این رویداد توسط هر نمودار تعریف می شود.

توجه به این نکته مهم است که رویدادهای نمودار جدا و متمایز از رویدادهای استاندارد DOM هستند.

ثبت نام و مدیریت یک رویداد

برای ثبت کنترل کننده رویداد خود، google.visualization.events.addListener() یا addOneTimeListener() را با نام نموداری که رویداد را نشان می دهد، نام رشته رویدادی که باید به آن گوش دهید، و نام تابعی را که باید هنگام فراخوانی فراخوانی کنید، فراخوانی کنید. آن رویداد اخراج می شود. تابع شما باید یک پارامتر واحد را بپذیرد که همان رویدادی است که اجرا شده است. این رویداد می‌تواند اطلاعات سفارشی درباره رویداد داشته باشد، همانطور که در مستندات نمودار توضیح داده شده است.

مهم: اگر نمودار شما یک رویداد آماده را نشان می‌دهد، همیشه باید قبل از ارسال روش‌ها یا دریافت رویدادها از نمودار منتظر بمانید تا آن رویداد فعال شود. این نمودارها ممکن است قبل از ایجاد یک رویداد آماده کار کنند، اما این رفتار تضمینی نیست.

قطعه کد زیر هر بار که کاربر روی یک ردیف جدول کلیک می کند یک جعبه هشدار را نشان می دهد:

// 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');
}

توجه داشته باشید که این فقط برای گوش دادن به رویدادها برای این شی جدول خاص ثبت می شود. شما فقط می توانید برای دریافت رویدادها از یک شی خاص ثبت نام کنید.

همانطور که در اینجا نشان داده شده است، می توانید یک تعریف تابع را نیز ارسال کنید:

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

بازیابی اطلاعات رویداد

رویدادها عموماً اطلاعات را به دو طریق در معرض نمایش می‌گذارند: با ارسال اطلاعات به تابع handler به عنوان یک پارامتر. یا با افزودن اطلاعات به یک شی سراسری. اگر و چگونه رویداد اطلاعات را در معرض دید قرار می دهد باید در مستندات آن نمودار توضیح داده شود. در اینجا نحوه بازیابی هر دو نوع اطلاعات آمده است:

اطلاعات رویداد به مدیریت کننده شما ارسال شد

اگر نمودار داده ها را به عنوان یک پارامتر به تابع مدیریت شما ارسال می کند، آن را همانطور که در اینجا نشان داده شده است بازیابی خواهید کرد:

// 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']);
}

پارامتری که به کنترل کننده شما منتقل می شود دارای ویژگی است که باید برای نمودار مستند شود. برای مثالی از نموداری که اطلاعات رویداد را به این شکل نشان می‌دهد، به رویداد صفحه نمودار جدول مراجعه کنید.

اطلاعات رویداد به یک شی سراسری ارسال می شود

برخی از رویدادها در عوض یک ویژگی از یک شی جهانی را تغییر می دهند که می توانید آن را درخواست کنید. یک مثال رایج از آن رویداد "انتخاب" است که زمانی که کاربر بخشی از نمودار را انتخاب می کند، فعال می شود. در این حالت، کد باید getSelection() را در نمودار فراخوانی کند تا انتخاب فعلی چیست. اطلاعات بیشتر در مورد رویداد انتخابی در زیر داده شده است.

// 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 هیچ خاصیت یا شیئی را به کنترل کننده ارسال نمی کند (کنترل کننده تابع شما نباید انتظار داشته باشد که هیچ پارامتری به آن ارسال شود).
• نمودار باید متد getSelection() را نشان دهد که آرایه ای از اشیاء را که عناصر داده انتخاب شده را توصیف می کند، برمی گرداند. این اشیا دارای خصوصیات row و column هستند. row و column نمایه های سطر و ستون آیتم انتخاب شده در DataTable هستند. (رویدادهای انتخابی، داده‌های اساسی در نمودار را توصیف می‌کنند، نه عناصر HTML در نمودار.) برای دریافت داده‌های مورد انتخاب شده، باید DataTable.getValue() یا getFormattedValue() را فراخوانی کنید.
  اگر هر دو row و column مشخص شده باشند، عنصر انتخاب شده یک سلول است. اگر فقط row مشخص شده باشد، عنصر انتخاب شده یک ردیف است. اگر فقط column مشخص شده باشد، عنصر انتخاب شده یک ستون است.
• نمودار باید روش setSelection(selection) را برای تغییر انتخاب در جدول زیر و انتخاب داده های مربوطه در نمودار نشان دهد. پارامتر انتخاب که آرایه ای شبیه به آرایه getSelection() است که در آن هر عنصر یک شی با ویژگی های row و column است. ویژگی row نمایه سطر انتخاب شده را در DataTable و ویژگی column نمایه ستون انتخابی را در DataTable تعریف می کند. هنگامی که این روش فراخوانی می شود، نمودار باید به صورت بصری نشان دهد که انتخاب جدید چیست. اجرای setSelection() نباید باعث ایجاد یک رویداد 'select' شود.
  اگر هر دو row و column مشخص شده باشند، عنصر انتخاب شده یک سلول است. اگر فقط row مشخص شده باشد، عنصر انتخاب شده یک ردیف است. اگر فقط column مشخص شده باشد، عنصر انتخاب شده یک ستون است.

برخی از هشدارها:

• نمودار ممکن است بخشی از انتخاب را نادیده بگیرد. به عنوان مثال، جدولی که می تواند فقط ردیف های انتخاب شده را نشان دهد، ممکن است عناصر سلول یا ستون را در اجرای setSelection خود نادیده بگیرد.)
• برخی نمودارها ممکن است رویداد "انتخاب" را راه اندازی نکنند، و برخی نمودارها ممکن است فقط از کل انتخاب ردیف یا کل انتخاب ستون پشتیبانی کنند. مستندات هر نمودار، رویدادها و روش هایی را که پشتیبانی می کند، تعریف می کند.
• انتخاب چندگانه در نمودارهای مختلف به طور متفاوتی انجام می شود (برخی حتی اجازه نمی دهند).
• برای خواندن داده های انتخاب شده، باید DataTable.getValue() را در کنترلر خود فراخوانی کنید. ساده ترین راه برای فعال کردن آن، جهانی کردن شی DataTable است.

هنگامی که یک عنصر از نمودار جدول انتخاب می شود، مثال زیر یک جعبه هشدار با عناصر جدول انتخاب شده ظاهر می شود:

توجه داشته باشید که نمودار جدول فقط رویدادهای انتخاب ردیف را فعال می کند. با این حال، کد عمومی است و می تواند برای رویدادهای انتخاب سطر، ستون و سلول استفاده شود.

در اینجا کد کنترل کننده برای آن مثال آمده است:

// 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);
}

رویداد آماده

اکثر نمودارها به صورت ناهمزمان ارائه می شوند. همه نمودارهای Google پس از فراخوانی draw() روی آن‌ها یک رویداد آماده می‌فرستند، که نشان می‌دهد نمودار رندر شده است، و آماده برای برگرداندن ویژگی‌ها یا رسیدگی به فراخوانی‌های متد بیشتر است. همیشه باید قبل از فراخوانی متدهای روی رویداد آماده پس از فراخوانی draw() به رویداد آماده گوش دهید.

به طور کلی نمودارهایی که رویداد "آماده" را نشان می دهند با مشخصات زیر طراحی می شوند:

• رویداد آماده هیچ خاصیتی را به کنترل کننده منتقل نمی کند (کنترل کننده تابع شما نباید انتظار داشته باشد که هیچ پارامتری به آن ارسال شود).
• پس از آماده شدن نمودار برای تعامل، نمودار باید رویداد آماده را فعال کند. اگر رسم نمودار ناهمزمان باشد، مهم است که رویداد زمانی اجرا شود که متدهای تعامل عملاً بتوان فراخوانی کرد، نه فقط زمانی که متد draw به پایان می رسد.
• افزودن شنونده به این رویداد باید قبل از فراخوانی متد draw() انجام شود، زیرا در غیر این صورت ممکن است رویداد قبل از تنظیم شنونده فعال شود و شما آن را نگیرید.
• با فراخوانی متدهای تعامل قبل از اجرا شدن رویداد آماده، این خطر را دارید که این روش ها به درستی کار نکنند.

قرارداد این است که نمودارهایی که رویداد "آماده" را اجرا نمی کنند بلافاصله پس از پایان روش draw آماده تعامل هستند و کنترل را به کاربر باز می گرداند. اگر نمودار شما یک رویداد آماده را اجرا می‌کند، باید منتظر بمانید تا قبل از فراخوانی متدها روی آن، همانطور که در اینجا نشان داده شده است:

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

دستور مدیریت رویداد آماده

function myReadyHandler(){...}

کنترل کننده رویداد آماده هیچ پارامتری دریافت نمی کند.

رویداد خطا

نمودارها باید زمانی که با نوعی خطا مواجه می‌شوند، یک رخداد خطا ایجاد کنند تا شما را قادر سازد تا به خوبی آن را مدیریت کنید. توضیحی از خطا و همچنین ویژگی‌های رویداد سفارشی مختص هر نمودار به کنترل‌کننده رویداد ارسال می‌شود. شما باید بلافاصله پس از نمونه سازی نمودار در این رویداد مشترک شوید تا هرگونه خطای ممکن در مراحل بعدی رخ دهد.

می توانید از توابع کمکی goog.visualization.errors استفاده کنید تا به شما کمک کند هر گونه خطا را به زیبایی به کاربر نشان دهید.

نحو کنترل رویداد خطا

function myErrorHandler(err){...}

کنترل کننده رویداد خطا باید یک شی با اعضای زیر ارسال شود:

• id [ لازم است] - شناسه عنصر DOM حاوی نمودار، یا یک پیام خطایی که به جای نمودار نمایش داده می شود، اگر قابل ارائه نباشد.
• پیام [ الزامی ] - یک رشته پیام کوتاه که خطا را توصیف می کند.
• detailsMessage [ اختیاری ] - توضیح دقیق خطا.
• گزینه ها [ اختیاری ] - یک شی حاوی پارامترهای سفارشی متناسب با این خطا و نوع نمودار.

مثال مدیریت رویداد

مثال زیر هم getSelection() و هم setSelection() را نشان می دهد. این انتخاب بین دو نمودار که از یک جدول داده استفاده می کنند، همگام می کند. برای همگام سازی انتخاب در نمودار دیگر، روی هر یک از نمودارها کلیک کنید.

// 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());
});

روی نمودارهای زیر در ردیف‌های جدول یا عناصر نمودار کلیک کنید تا انتخاب را در عمل ببینید: