تنشيط الأحداث

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

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

يجب تشغيل أي حدث مرئي قابل للتحديد: الحدث المحدد. ومع ذلك، يتم تحديد سلوك هذا الحدث ومعنىه من خلال كل تصور.

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

من المهم ملاحظة أن أحداث واجهة برمجة التطبيقات الخاصة بالتمثيل البصري منفصلة عن أحداث DOM العادية ومنفصلة عنها.

المحتويات

  1. تنشيط حدث
  2. حدث الاختيار
  3. الفعالية الجاهزة
  4. مزيد من المعلومات

تنشيط حدث

لتنشيط حدث من التمثيل البصري، عليك باستدعاء الدالة google.visualization.events.trigger(). تتوقع الدالة المعلمات التالية:

  1. التمثيل البصري للمصدر (عادةً ما تكون هذه القيمة هي this).
  2. اسم الحدث (سلسلة).
  3. تفاصيل الحدث (كائن). خريطة اختيارية (الاسم/القيمة) لتفاصيل الحدث المحددة.

يوضح المثال التالي كيفية عرض التمثيل البصري للحدث المحدد: 

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Fire a select event.
  google.visualization.events.trigger(this, 'select', {});
};

يمكن تسجيل الصفحات المستضافة لتلقي أحداثك من خلال الاتصال بـ google.visualization.events.addListener() أو google.visualization.events.addOneTimeListener(). احرص على توثيق أي أحداث تشعلها بالكامل.

حدث التحديد

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

  1. نشِّط حدثًا بالاسم "اختيار" عندما يختار المستخدم بعض البيانات ضمن التمثيل البصري. لا يرسل الحدث أي وسيطات لدوال الاستماع.
  2. اعرِض طريقة getSelection() على النحو الموضّح في قسم المستند المرتبط. ومن المفترض أن تعرض هذه الطريقة فهارس عناصر البيانات التي اختارها المستخدم.
  3. قدِّم طريقة setSelection() على النحو الموضّح في القسم المرجع. يمكنك أيضًا مراجعة صفحة أحداث المناولة للاطّلاع على كيفية معالجة الأحداث.

الحدث الجاهز

ومن المفترض أن يؤدي أي عرض مرئي إلى تنشيط حدث "جاهز" يعمل بطريقة قياسية لإعلام مطوّر البرامج عندما يصبح التمثيل البصري جاهزًا للمعالجة المسماة طُرق. (ومع ذلك، ليس هناك أي مطلب مطلق بأنّ التمثيل البصري يتصرف على هذا النحو، راجِع مستندات التمثيل البصري.

بشكل عام، يتم تصميم العروض المرئية التي تعرض الحدث "الجاهز" وفقًا للمواصفات التالية:

  • لا يمرِّر الحدث الجاهز أي خصائص إلى المعالج (من المفترض ألا يتوقع معالج الدالات تمرير أي معلّمات إليها).
  • ويجب أن يعمل التمثيل البصري على تنشيط الحدث الجاهز بعد أن يكون التمثيل البصري جاهزًا للتفاعل. إذا كان رسم التمثيل البصري غير متزامن، من المهم تنشيط الحدث عندما يمكن استدعاء طرق التفاعل، وليس فقط عند انتهاء استخدام طريقة draw.
  • يجب إضافة مستمع إلى هذا الحدث قبل استدعاء الطريقة draw، وإلا قد يتم تنشيط الحدث قبل إعداد المستمع ولن تسمعه.
  • ومن خلال استدعاء طرق التفاعل قبل تنشيط الحدث الجاهز، فإنك تخاطر بعدم عمل هذه الطرق بشكلٍ صحيح.

تتمثّل القاعدة في أن التمثيلات البصرية التي لا تؤدي إلى تنشيط حدث "جاهز" جاهزة للتفاعل مباشرةً بعد انتهاء طريقة draw وإرجاع عنصر التحكم للمستخدم.

مزيد من المعلومات