يمكن للتمثيل البصري تنشيط الأحداث التي يمكن لصفحة المضيف تسجيلها لاستلامها. يمكن تنشيط الأحداث من خلال إجراءات المستخدم: على سبيل المثال، ينقر المستخدم على رسم بياني أو يمكن أن تكون داخلية: على سبيل المثال، تنشيط حدث كل 10 ثوانٍ. يمكنك تسجيل طريقة JavaScript ليتم طلبها عند تنشيط أحداث معيّنة، ويمكن أن يتم ذلك باستخدام بيانات خاصة بذلك الحدث.
يحدّد كل عرض مرئي فعالياته الخاصة، ويجب أن توضّح المستندات الخاصة بهذا العرض المرئي متى يتم تنشيط كل فعالية، ودلالتها، والمعلومات التي يرسلها إلى معالج الأحداث (على سبيل المثال، يمكنك الاطّلاع على التمثيل البصري للرسم البياني للمؤسسة). تصف هذه الصفحة كيف يمكن لمنشئ التصور تنشيط الأحداث. للتعرّف على كيفية تسجيل العملاء لتلقّي الأحداث، اطّلِع على صفحة معالجة الأحداث.
هناك حدث واحد يجب أن ينشطه أي تصور قابل للاختيار: الحدث المحدد. ومع ذلك، يتم تحديد سلوك ومعنى هذا الحدث من خلال كل تصور.
إذا لم يكن التمثيل البصري جاهزًا للتفاعل فورًا بعد أن تُرجع طريقة draw
عنصر التحكّم للمستخدم، يجب تنشيط التمثيل البصري: الحدث الجاهز.
يتم تعريف السلوك والمعنى الدقيق لهذا الحدث في القسم الحدث الجاهز.
تجدر الإشارة إلى أنّ أحداث Visualization API منفصلة ومتميّزة عن أحداث DOM العادية.
المحتويات
تنشيط حدث
لتنشيط حدث من التمثيل البصري، استدعِ الدالة google.visualization.events.trigger()
.
تتوقع الدالة المَعلمات التالية:
- التمثيل البصري للمصدر (تكون عادةً هذه القيمة هي
this
). - اسم الحدث (سلسلة نصية)
- تفاصيل الحدث (الكائن). خريطة اختيارية (الاسم/القيمة) لتفاصيل أحداث محدَّدة
يوضح المثال التالي كيف يعرض التصور الحدث select:
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" هو حدث عادي يعرضه العديد من المرئيات استجابةً لنقرة ماوس من قِبل المستخدم. إذا اختَرت تنشيط حدث استجابةً لنقرات الماوس، عليك تنفيذ حدث "select" بالطريقة العادية الموضّحة هنا:
- فعِّل حدثًا باسم "اختيار" عندما يختار المستخدم بعض البيانات ضمن العرض المرئي. ولا يرسل الحدث أي وسيطات إلى وظائف الاستماع.
- اعرض طريقة
getSelection()
كما هو موضّح في قسم المستندات المرتبطة. من المفترض أن تعرض هذه الطريقة فهارس عناصر البيانات التي اختارها المستخدم.
- اعرض طريقة
setSelection()
كما هو موضّح في قسم المراجع. يمكنك أيضًا الاطّلاع على صفحة التعامل مع الأحداث للتعرّف على كيفية التعامل مع الأحداث.
الحدث الجاهز
يجب أن ينشط أي عرض مرئي حدثًا "جاهزًا" يعمل بطريقة عادية لإعلام المطوّر عندما يكون التمثيل البصري جاهزًا للمعالجة التي تُعرف باسم "الطرق". (ورغم ذلك، ما مِن متطلبات مطلقة تطبّقها طريقة العرض على هذا النحو، لذا يُرجى مراجعة المستندات المتعلقة بالتمثيل البصري).
بشكل عام، يتم تصميم الرسومات البيانية التي تعرض الحدث "جاهز" وفقًا للمواصفات التالية:
- لا يمرر الحدث الجاهز أي سمات إلى المعالج (من المفترض ألا يتوقع أن يتم تمرير أي معلَمات إليه).
- من المفترض أن يطلق التمثيل البصري الحدث الجاهز بعد أن يكون التمثيل البصري جاهزًا للتفاعل.
إذا كان رسم التمثيل المرئي غير متزامن، من المهم أن يتم تنشيط الحدث عندما يمكن استدعاء طرق التفاعل فعليًا،
وليس فقط عند انتهاء طريقة
draw
. - يجب إضافة مستمع إلى هذا الحدث قبل استدعاء طريقة
draw
، وإلا قد يتم تنشيط الحدث قبل إعداد المستمع ولن تتمكن من تسجيله. - من خلال استدعاء طرق التفاعل قبل تنشيط الحدث الجاهز، فإنك تخاطر بعدم عمل هذه الطرق بشكلٍ سليم.
الاصطلاح هو أنّ العروض المرئية التي لا تنشّط حدث "جاهز" تكون جاهزة للتفاعل مباشرةً بعد انتهاء طريقة draw
وتعيد التحكّم للمستخدم.