تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يمكن للتمثيل البصري تنشيط الأحداث التي يمكن لصفحة المضيف تسجيلها لاستلامها.
يمكن تنشيط الأحداث من خلال إجراءات المستخدم: على سبيل المثال، ينقر المستخدم على رسم بياني
أو يمكن أن تكون داخلية: على سبيل المثال، تنشيط حدث كل 10 ثوانٍ. يمكنك تسجيل طريقة JavaScript ليتم طلبها عند تنشيط أحداث معيّنة، ويمكن أن يتم ذلك باستخدام بيانات خاصة بذلك الحدث.
يحدّد كل عرض مرئي فعالياته الخاصة، ويجب أن توضّح المستندات الخاصة بهذا العرض المرئي متى يتم تنشيط كل فعالية، ودلالتها، والمعلومات التي يرسلها إلى معالج الأحداث (على سبيل المثال، يمكنك الاطّلاع على التمثيل البصري
للرسم البياني للمؤسسة). تصف هذه الصفحة كيف يمكن لمنشئ التصور تنشيط الأحداث.
للتعرّف على كيفية تسجيل العملاء لتلقّي الأحداث، اطّلِع على صفحة معالجة
الأحداث.
هناك حدث واحد يجب أن ينشطه أي تصور قابل للاختيار: الحدث المحدد.
ومع ذلك، يتم تحديد سلوك ومعنى هذا الحدث من خلال كل تصور.
إذا لم يكن التمثيل البصري جاهزًا للتفاعل فورًا بعد أن تُرجع طريقة draw عنصر التحكّم للمستخدم، يجب تنشيط التمثيل البصري: الحدث الجاهز.
يتم تعريف السلوك والمعنى الدقيق لهذا الحدث في القسم الحدث الجاهز.
تجدر الإشارة إلى أنّ أحداث Visualization API منفصلة ومتميّزة
عن أحداث DOM العادية.
التمثيل البصري للمصدر (تكون عادةً هذه القيمة هي 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', {});
};
الحدث "select" هو حدث عادي يعرضه العديد من المرئيات
استجابةً لنقرة ماوس من قِبل المستخدم. إذا اختَرت تنشيط حدث استجابةً لنقرات الماوس، عليك تنفيذ حدث "select" بالطريقة العادية الموضّحة هنا:
فعِّل حدثًا باسم "اختيار" عندما يختار المستخدم بعض البيانات ضمن
العرض المرئي. ولا يرسل الحدث أي وسيطات إلى وظائف الاستماع.
اعرض طريقة getSelection()
كما هو موضّح في قسم المستندات المرتبطة. من المفترض أن تعرض هذه الطريقة فهارس
عناصر البيانات
التي اختارها المستخدم.
يجب أن ينشط أي عرض مرئي حدثًا "جاهزًا" يعمل بطريقة عادية لإعلام المطوّر عندما يكون التمثيل البصري
جاهزًا للمعالجة التي تُعرف باسم "الطرق". (ورغم ذلك، ما مِن متطلبات مطلقة تطبّقها طريقة العرض على هذا النحو، لذا يُرجى مراجعة المستندات المتعلقة بالتمثيل البصري).
بشكل عام، يتم تصميم الرسومات البيانية التي تعرض الحدث "جاهز" وفقًا للمواصفات التالية:
لا يمرر الحدث الجاهز أي سمات إلى المعالج (من المفترض ألا يتوقع
أن يتم تمرير أي معلَمات إليه).
من المفترض أن يطلق التمثيل البصري الحدث الجاهز بعد أن يكون التمثيل البصري جاهزًا للتفاعل.
إذا كان رسم التمثيل المرئي غير متزامن، من المهم أن يتم تنشيط الحدث عندما يمكن استدعاء طرق التفاعل فعليًا،
وليس فقط عند انتهاء طريقة draw.
يجب إضافة مستمع إلى هذا الحدث قبل استدعاء طريقة draw، وإلا قد يتم تنشيط الحدث قبل إعداد المستمع ولن تتمكن من تسجيله.
من خلال استدعاء طرق التفاعل قبل تنشيط الحدث الجاهز، فإنك تخاطر بعدم عمل هذه الطرق بشكلٍ سليم.
الاصطلاح هو أنّ العروض المرئية التي لا تنشّط حدث "جاهز" تكون جاهزة للتفاعل مباشرةً بعد انتهاء طريقة draw وتعيد التحكّم للمستخدم.
تاريخ التعديل الأخير: 2024-07-10 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2024-07-10 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eVisualization creators can fire custom events or standard events like 'select' and 'ready' using \u003ccode\u003egoogle.visualization.events.trigger()\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe 'select' event is fired when a user interacts with data, requiring \u003ccode\u003egetSelection()\u003c/code\u003e and \u003ccode\u003esetSelection()\u003c/code\u003e methods for data retrieval and manipulation.\u003c/p\u003e\n"],["\u003cp\u003eThe 'ready' event signals that a visualization is ready for user interaction, typically fired after the \u003ccode\u003edraw()\u003c/code\u003e method completes; any interaction before this event might not work as expected.\u003c/p\u003e\n"],["\u003cp\u003eHost pages can listen for these events using \u003ccode\u003egoogle.visualization.events.addListener()\u003c/code\u003e or \u003ccode\u003egoogle.visualization.events.addOneTimeListener()\u003c/code\u003e to respond accordingly.\u003c/p\u003e\n"],["\u003cp\u003eWhile each visualization defines its own events, the 'select' and 'ready' events follow specific guidelines for consistency and usability.\u003c/p\u003e\n"]]],[],null,["# Firing Events\n\nYour visualization can fire events that a host page can register to receive.\nEvents can be fired by user actions: for example a user clicks on a chart,\nor can be internal: for example, firing an event every 10 seconds. You can register\na Javascript method to be called whenever certain events are fired, possibly with\ndata specific to that event.\n\nEvery visualization defines its own events, and the documentation for that visualization\nshould describe when each event is fired, what it means, and what information it\nsends to your event handler (for example, see the [orgchart\nvisualization](/chart/interactive/docs/gallery/orgchart)). This page describes how a visualization creator can fire events.\nTo learn how clients can register to receive events, see the [Handling\nEvents](/chart/interactive/docs/events) page.\n\nThere is one event that any selectable visualization should fire: the select event.\nHowever, the behavior and meaning of this event is defined by each visualization.\n\nIf a visualization is not ready for interaction immediately after the `draw` method returns control to the user, the visualization should fire: the ready event.\nThe exact behavior and meaning of this event is defined in [The Ready Event](#The_Ready_Event) section.\n\nIt is important to note that the Visualization API events are separate and distinct\nfrom the standard DOM events.\n\nContents\n--------\n\n1. [Firing an Event](#Triggering_an_Event)\n2. [The Select Event](#The_Select_Event)\n3. [The Ready Event](#The_Ready_Event)\n4. [More Information](#moreinfo)\n\nFiring an Event\n---------------\n\nTo fire an event from your visualization, call the [google.visualization.events.trigger()](/chart/interactive/docs/reference#trigger) function.\nThe function expects the following parameters:\n\n1. Source visualization (typically this is the `this` value).\n2. Event name (string).\n3. Event details (Object). An optional map (name/value) of specific event details.\n\n\nThe following example shows how a visualization throws the select event: \n\n```carbon\nMyVisualization.prototype.onclick = function(rowIndex) {\n this.highlightRow(this.selectedRow, false); // Clear previous selection\n this.highlightRow(rowIndex, true); // Highlight new selection\n\n // Save the selected row index in case getSelection is called.\n this.selectedRow = rowIndex;\n\n // Fire a select event.\n google.visualization.events.trigger(this, 'select', {});\n};\n```\n\nHosting pages can register to receive your events by calling [google.visualization.events.addListener()](/chart/interactive/docs/reference#addlistener) or [google.visualization.events.addOneTimeListener()](/chart/interactive/docs/reference#addonetimelistener).\nBe sure to document thoroughly any events that you fire.\n\nThe Select Event\n----------------\n\nThe \"select\" event is a standard event thrown by many visualizations\nin response to a user mouse click. If you choose to fire an event in response to\nmouse clicks, you should implement the \"select\" event in the standard way described\nhere:\n\n1. Fire an event with the name 'select' when the user selects some data within the visualization. The event does not send any arguments to the listening functions.\n2. Expose the [getSelection()](/chart/interactive/docs/reference#visgetselection) method as described in the linked document section. This method should return the indexes of **data** elements that the user selected. \n3. Expose a [setSelection()](/chart/interactive/docs/reference#vissetselection) method as described in the [reference](/chart/interactive/docs/reference#vissetselection) section. Also see the [handling events](/chart/interactive/docs/events) page to learn how to handle events.\n\n\u003cbr /\u003e\n\nThe Ready Event\n---------------\n\nAny visualization should fire a \"ready\" event that works in a standard way to let the developer know when the visualization\nis ready to process called methods. (However, there is no absolute *requirement* that\na visualization behave this way; check the documentation for your visualization).\n\nIn general, visualizations that expose the \"ready\" event are designed with the\nfollowing specifications:\n\n- The ready event does not pass any properties to the handler (your function handler should not expect any parameters to be passed to it).\n- The visualization *should* fire the ready event after the visualization is ready for interaction. If the drawing of the visualization is asynchronous, it is important that the event is fired when interaction methods can actually be called, and not just when the `draw` method ends.\n- Adding a listener to this event should be done before calling the `draw` method, because otherwise the event might be fired before the listener is set up and you will not catch it.\n- By calling interaction methods before the ready event is fired, you take a risk that these methods will not work properly.\n\n\nThe convention is that visualizations which do not fire a \"ready\" event are ready for interaction immediately after the `draw` method ends and returns control to the user.\n\nMore Information\n----------------\n\n- [Controls and Dashboards](/chart/interactive/docs/gallery/controls)\n- [getSelection()](/chart/interactive/docs/reference#visgetselection)\n- [`google.visualization.events.addListener()`](/chart/interactive/docs/reference)"]]
