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

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

المحتويات

1. Overview
2. التسجيل في فعالية ومعالجتها
3. استرداد معلومات الحدث
4. الحدث المحدد
5. الحدث الجاهز
6. حدث خطأ
7. مثال على التعامل مع الحدث

نظرة عامة

يمكن للرسوم البيانية من 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" يعمل بطريقة عادية للسماح لك باسترداد قيم العنصر المحدّد في الرسم البياني. (ورغم ذلك، ما مِن متطلبات مطلقة لاستخدام الرسم البياني على هذا النحو، لذا يمكنك مراجعة المستندات الخاصة بالرسم البياني).

بشكل عام، يتم تصميم الرسوم البيانية التي تعرض الحدث "select" باستخدام المواصفات التالية:

• لا يمرر حدث 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).
• قد لا تؤدي بعض الرسومات البيانية إلى تشغيل حدث "select"، وقد تتيح بعض الرسوم البيانية اختيار الصف بأكمله فقط أو اختيار الأعمدة بأكملها. تحدّد مستندات كل رسم بياني الأحداث والطرق التي يتوافق معها.
• يتم التعامل مع ميزة الاختيار المتعدد بشكل مختلف في رسوم بيانية مختلفة (بعضها لا يسمح بذلك).
• لقراءة البيانات المحدّدة، يجب استدعاء 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());
});

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