معالجة الأحداث

توضّح هذه الصفحة كيفية الاستماع إلى الأحداث التي يتم إطلاقها من خلال رسم بياني ومعالجتها.

الفهرس

نظرة عامة

يمكن لمخططات Google تنشيط أحداث يمكنك الاستماع إليها. يمكن تشغيل الأحداث من خلال إجراءات المستخدم، على سبيل المثال، عندما ينقر المستخدم على رسم بياني. يمكنك تسجيل أسلوب JavaScript ليتم استدعاؤه في كل مرة يتم فيها تنشيط أحداث معيّنة، ويمكن أن يتم ذلك من خلال بيانات خاصة بهذه الفعالية.

يحدّد كل رسم بياني الأحداث الخاصة به، ويجب أن توضّح المستندات الخاصة بهذا الرسم البياني وقت إطلاق كل فعالية، ومعنى ذلك، وكيفية استعادة أي معلومات مرتبطة بالفعالية. توضّح هذه الصفحة كيفية التسجيل للحصول على الفعاليات من رسم بياني وطريقة معالجتها.

يجب أن يتم تنشيط حدث واحد في أي رسم بياني قابل للاختيار: الحدث المحدد. ومع ذلك، يحدِّد كل رسم بياني سلوك هذا الحدث ومعنىه.

من المهم ملاحظة أن أحداث الرسم البياني منفصلة ومتميزة عن أحداث 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());
});

استرداد معلومات الحدث

تكشف الأحداث بشكل عام عن المعلومات بطريقتين: عن طريق تمرير المعلومات إلى دالة المعالج باعتبارها معلَمة، أو عن طريق إضافة معلومات إلى كائن عام. إذا كانت الفعالية تتضمّن معلومات وطريقة عرضها، يجب وصفها في المستندات الخاصة بهذا الرسم البياني. إليك كيفية استرداد كلا النوعين من المعلومات:

تمرير معلومات الحدث إلى المعالج

إذا مرّر الرسم البياني البيانات كمعلمة إلى دالة المناولة، ستستردها كما هو موضّح هنا:

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

ستحتوي المعلمة التي تم تمريرها إلى المعالج على خاصية يجب توثيقها للرسم البياني. للاطّلاع على مثال على رسم بياني يعرض معلومات الفعالية بهذه الطريقة، يمكنك الاطّلاع على حدث صفحة الرسم البياني في الجدول.

معلومات الحدث التي يتم تمريرها إلى كائن عام

وبدلاً من ذلك، تغيّر بعض الأحداث خاصية لكائن عام، ويمكنك بعد ذلك طلبها. ومن الأمثلة الشائعة على ذلك الحدث "select" الذي يتم تنشيطه عندما يختار أحد المستخدمين جزءًا من رسم بياني. في هذه الحالة، يجب أن يستدعي الرمز 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) لتغيير الاختيار في الجدول الأساسي واختيار البيانات المقابلة في الرسم البياني. معلمة 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 الذي يحتوي على الرسم البياني أو رسالة خطأ معروضة بدلاً من الرسم البياني في حال تعذّر عرضها.
  • message [مطلوبة] - سلسلة رسائل قصيرة تصف الخطأ.
  • detailedMessage [اختيارية] - شرح تفصيلي للخطأ.
  • options [اختيارية]- كائن يحتوي على مَعلمات مخصّصة مناسبة لهذا الخطأ ونوع الرسم البياني.

مثال على التعامل مع الأحداث

يوضح المثال التالي كلاً من 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());
});

انقر على المخططات التالية على صفوف الجدول أو على عناصر المخطط للاطلاع على التحديد عمليًا: