טיפול באירועים

בדף הזה מתואר איך להאזין לאירועים שמופעלים באמצעות תרשים ולטפל בהם.

תוכן עניינים

1. סקירה כללית
2. הרשמה וטיפול באירוע
3. אחזור פרטי אירוע
4. האירוע select
5. האירוע המוכן
6. אירוע השגיאה
7. דוגמה לטיפול באירועים

סקירה כללית

במצעדים של Google אפשר להפעיל אירועים שאפשר להאזין להם. אפשר להפעיל אירועים על ידי פעולות של משתמשים, כמו כאשר משתמש לוחץ על תרשים. אפשר לרשום ששיטת JavaScript תתבצע קריאה בכל פעם שאירועים מסוימים מופעלים, עם נתונים ספציפיים לאותו אירוע.

כל תרשים מגדיר אירועים משלו, והתיעוד של אותו תרשים צריך לתאר מתי כל אירוע מופעל, מה המשמעות שלו ואיך להחזיר את המידע המשויך לאירוע. בדף הזה מתואר כיצד להירשם כדי לקבל אירועים מתרשים ואיך לטפל בהם.

יש אירוע אחד שכל תרשים שניתן לבחור צריך לפעול: האירוע שנבחר. עם זאת, ההתנהגות והמשמעות של אירוע זה מוגדרות על ידי כל תרשים.

חשוב לציין שאירועי התרשים הם נפרדים ונפרדים מאירועי ה-DOM הרגילים.

הרשמה וטיפול באירוע

כדי לרשום את ה-handlers של האירועים, אפשר לקרוא ל-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());
});

אחזור מידע על אירועים

אירועים בדרך כלל חושפים מידע בשתי דרכים: על ידי העברת מידע לפונקציית ה-handler כפרמטר, או על ידי הוספת מידע לאובייקט גלובלי. אם והאופן שבו האירוע חושף את המידע, יש לתאר את המידע בתיעוד של אותו תרשים. כדי לאחזר את שני סוגי המידע:

פרטי אירועים שהועברו ל-handler

אם התרשים מעביר נתונים כפרמטר לפונקציית הטיפול, תוכלו לאחזר אותו כפי שמוצג כאן:

// 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']);
}

לפרמטר שיועבר ל-handler שלך יהיה מאפיין שצריך לתעד בתרשים. דוגמה לתרשים שחושפת מידע על אירוע בדרך זו, אפשר לראות את אירוע הדף של הטבלה.

פרטי אירועים שהועברו לאובייקט גלובלי

אירועים מסוימים משנים את המאפיין של אובייקט גלובלי, ולאחר מכן אפשר לבקש אותו. דוגמה נפוצה לכך היא האירוע '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" נבחרים עם המפרטים הבאים:

• האירוע שנבחר לא מעביר מאפיינים או אובייקטים ל-handler (ה-handler של הפונקציה לא אמור לצפות להעברה של פרמטרים כלשהם אליו).
• התרשים צריך לחשוף את השיטה 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() ב-handler שלך. הדרך הפשוטה ביותר להפעיל אותם היא להפוך את האובייקט DataTable לגלובלי.

הדוגמה הבאה מציגה תיבת סימון עם רכיבי הטבלה שנבחרו, כאשר נבחר רכיב של תרשים טבלה:

חשוב לשים לב בתרשים הטבלה מפעיל רק אירועים של בחירת שורה. עם זאת, הקוד הוא גנרי, וניתן להשתמש בו עבור אירועים של בחירת שורות, עמודות ותאים.

לדוגמה, הוא הקוד של ה-handler:

// 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().

באופן כללי, תרשימים שחושפים את האירוע 'מוכנים' מעוצב לפי המפרטים הבאים:

• האירוע המוכן לא מעביר נכסים אל ה-handler (ה-handler של הפונקציה לא אמור לצפות לפרמטרים שמועברים אליו).
• התרשים אמור להפעיל את האירוע המוכן לאחר שהתרשים מוכן לאינטראקציה. אם התרשים של התרשים הוא אסינכרוני, חשוב שהאירוע יופעל כשהקריאה לאירועי האינטראקציה תהיה בפועל, ולא רק כאשר השיטה draw מסתיימת.
• עליכם להוסיף האזנה לאירוע הזה לפני הקריאה לשיטה draw(), כי יכול להיות שהאירוע יופעל לפני שהמאזין יוגדר ולא תבחינו בו.
• קריאה לשיטות אינטראקציה לפני שהאירוע המוכן יופעל, עלולה לגרום לכך שהשיטות האלה לא יפעלו כראוי.

באופן הזה, תרשימים שלא מפעילים אירוע 'מוכן' מוכנים לאינטראקציה מיד בסיום השיטה draw ומחזירים את השליטה על המשתמש. אם בתרשים כן מופעל אירוע מוכן, עליכם להמתין עד שהוא יזרק את הדף לפני ביצוע הקריאות לשיטות השונות, כפי שמוצג כאן:

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

התחביר של 'מטפל באירועים מוכנים'

function myReadyHandler(){...}

הגורם המטפל באירועים המוכנים לא מועבר לפרמטרים.

אירוע השגיאה

תרשימים צריכים להציג אירוע שגיאה כשהם נתקלים בשגיאה כלשהי, כדי לאפשר לכם לטפל בה באופן חינני. המטפל באירוע מעביר תיאור של השגיאה, וגם מאפייני אירועים מותאמים אישית הספציפיים לכל תרשים. עליך להירשם לאירוע הזה מיד לאחר יצירת התרשים כדי לאתר שגיאות שעשויות להתרחש בשלבים הבאים.

פונקציות העוזרות של goog.visualization.errors יכולות לעזור לכם להציג את שגיאות המשתמש בצורה חלקה.

תחביר של מטפל באירוע שגיאות

function myErrorHandler(err){...}

הגורם המטפל בשגיאות שגיאה צריך להעביר אובייקט עם החברים הבאים:

• id [חובה] – המזהה של רכיב ה-DOM שמכיל את התרשים, או הודעת שגיאה שמוצגת במקום התרשים אם לא ניתן לעבד אותו.
• message [חובה] – מחרוזת הודעה קצרה המתארת את השגיאה.
• detailedMessage [אופציונלי] – הסבר מפורט לשגיאה.
• אפשרויות [אופציונלי]- אובייקט שמכיל פרמטרים מותאמים אישית שמתאימים לשגיאה הזו ולסוג התרשים.

דוגמה לטיפול באירועים

הדוגמה הבאה מדגימה את 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());
});

אפשר ללחוץ על התרשימים שבהמשך בשורות טבלה או באלמנטים של התרשים כדי לראות את הבחירה בפעולה: