با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
تجسم شما می تواند رویدادهایی را ایجاد کند که یک صفحه میزبان می تواند برای دریافت آنها ثبت نام کند. رویدادها می‌توانند با اقدامات کاربر فعال شوند: برای مثال کاربر روی نمودار کلیک می‌کند، یا می‌تواند داخلی باشد: به عنوان مثال، هر 10 ثانیه یک رویداد را اجرا می‌کند. می‌توانید یک متد جاوا اسکریپت را ثبت کنید تا هر زمان که رویدادهای خاصی فعال می‌شوند، احتمالاً با داده‌های خاص آن رویداد، فراخوانی شود.
هر تصویرسازی رویدادهای خود را تعریف می‌کند، و مستندات مربوط به آن تجسم باید توضیح دهد که هر رویداد چه زمانی اجرا می‌شود، چه معنایی دارد و چه اطلاعاتی را برای مدیریت رویداد شما ارسال می‌کند (برای مثال، به تجسم orgchart مراجعه کنید). این صفحه توضیح می‌دهد که چگونه یک ایجادکننده تجسم می‌تواند رویدادها را فعال کند. برای اطلاع از نحوه ثبت نام مشتریان برای دریافت رویدادها، به صفحه Handling Events مراجعه کنید.
یک رویداد وجود دارد که هر تصویرسازی قابل انتخابی باید فعال شود: رویداد انتخاب. با این حال، رفتار و معنای این رویداد توسط هر تجسم تعریف می شود.
اگر یک تجسم بلافاصله پس از اینکه روش draw کنترل را به کاربر بازگرداند برای تعامل آماده نباشد، تجسم باید فعال شود: رویداد آماده. رفتار و معنای دقیق این رویداد در قسمت The Ready Event تعریف شده است.
توجه به این نکته مهم است که رویدادهای Visualization API جدا و متمایز از رویدادهای استاندارد DOM هستند.
جزئیات رویداد (Object). یک نقشه اختیاری (نام/مقدار) از جزئیات رویداد خاص.
مثال زیر نشان می دهد که چگونه یک تجسم رویداد انتخابی را پرتاب می کند:
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', {});
};
رویداد "انتخاب" یک رویداد استاندارد است که توسط بسیاری از تجسم ها در پاسخ به کلیک ماوس کاربر پرتاب می شود. اگر می‌خواهید یک رویداد را در پاسخ به کلیک‌های ماوس فعال کنید، باید رویداد «انتخاب» را به روش استانداردی که در اینجا توضیح داده شده است پیاده‌سازی کنید:
هنگامی که کاربر برخی از داده‌ها را در تصویرسازی انتخاب می‌کند، رویدادی را با نام "انتخاب" فعال کنید. رویداد هیچ آرگومانی را به توابع شنیداری ارسال نمی کند.
همانطور که در بخش سند پیوندی توضیح داده شده است، متد getSelection() را در معرض دید قرار دهید. این روش باید شاخص های عناصر داده ای را که کاربر انتخاب کرده است برگرداند.
همانطور که در بخش مرجع توضیح داده شده است، یک متد setSelection() را نمایش دهید. همچنین برای یادگیری نحوه رسیدگی به رویدادها، به صفحه مدیریت رویدادها مراجعه کنید.
رویداد آماده
هر تجسمی باید یک رویداد "آماده" را اجرا کند که به روشی استاندارد کار می کند تا به توسعه دهنده اطلاع دهد که چه زمانی تجسم برای پردازش متدهای نامیده می شود. (با این حال، هیچ الزام مطلقی وجود ندارد که یک تجسم به این شکل رفتار کند؛ مستندات را برای تجسم خود بررسی کنید).
به طور کلی، تجسم هایی که رویداد "آماده" را نشان می دهند با مشخصات زیر طراحی می شوند:
رویداد آماده هیچ خاصیتی را به کنترل کننده منتقل نمی کند (کنترل کننده تابع شما نباید انتظار داشته باشد که هیچ پارامتری به آن ارسال شود).
تجسم باید رویداد آماده را پس از آماده شدن تجسم برای تعامل فعال کند. اگر ترسیم تجسم ناهمزمان باشد، مهم است که رویداد زمانی اجرا شود که روش‌های تعامل واقعاً می‌توانند فراخوانی شوند، و نه فقط زمانی که متد 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)"]]
