מאמרי עזרה של GoogleVisual API

בדף הזה מפורטים האובייקטים שנחשפים על ידי Google Vision API והשיטות הסטנדרטיות שחשופות כל הרכיבים החזותיים.

הערה: מרחב השמות של GoogleVisual API הוא google.visualization.*

סיווג DataTable

מייצג טבלת ערכים דו-ממדית שניתנת לשינוי. כדי ליצור עותק לקריאה בלבד של DataTable (אפשר לסנן באופן אופציונלי כך שיוצגו ערכים, שורות או עמודות ספציפיים), יוצרים DataView.

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

בנוסף, אפשר להקצות מאפיינים מותאמים אישית (צמדי שם/ערך) לכל תא, שורה, עמודה או כל הטבלה. חלק מהרכיבים החזותיים תומכים במאפיינים מותאמים אישית ספציפיים. לדוגמה, התצוגה החזותית של הטבלה תומכת במאפיין תא שנקרא 'style', שמאפשר להקצות לתא המעובד בטבלה מחרוזות של סגנון CSS. הרכיבים החזותיים צריכים לתאר במסמכי התיעוד של כל מאפיין מותאם אישית שנתמך בו.

למידע נוסף: QueryResponse.getDataTable

בונה

תחביר

DataTable(opt_data, opt_version)

opt_data

[אופציונלי] נתונים ששימשו לאתחול הטבלה. הוא יכול להיות ה-JSON שמוחזר על ידי קריאה ל-DataTable.toJSON() בטבלה מאוכלסת, או אובייקט JavaScript שמכיל נתונים שמשמשים לאתחול הטבלה. המבנה של האובייקט הליטרל של JavaScript מתואר כאן. אם לא מזינים את הפרמטר הזה, תוחזר טבלת נתונים חדשה וריקה.

opt_version

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

פרטים

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

כל תא בטבלה מכיל ערך מסוים. בתאים יכולים להיות ערך null או ערך מהסוג שצוין בעמודה שלהם. אפשר להגדיר לתאים גרסה 'מפורמטת' של הנתונים. זו גרסת מחרוזת של הנתונים, שמעוצבת לצורך הצגה באמצעות תצוגה חזותית. התצוגה החזותית יכולה (אבל לא נדרשת) להשתמש בגרסה המעוצבת, אבל היא תשתמש תמיד בנתונים עצמם לצורך מיון או חישובים שלה (למשל, כדי לקבוע איפה למקם נקודה בתרשים). למשל, יכול להיות שהערכים 'low' 'medium' ו-'high' מקצים כערכים בפורמט ערכים מספריים של 1, 2 ו-3 בתאים.

כדי להוסיף שורות נתונים אחרי קריאה ל-constructor, אפשר לקרוא ל-addRow() בשורה אחת או ל-addRows() בשביל כמה שורות. אפשר גם להוסיף עמודות באמצעות קריאה ל-methods addColumn(). יש גם שיטות להסרה של שורות ועמודות, אבל במקום להסיר שורות או עמודות כדאי ליצור DataView שהוא תצוגה סלקטיבית של DataTable.

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

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

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

var dt = new google.visualization.DataTable({
    cols: [{id: 'task', label: 'Task', type: 'string'},
           {id: 'hours', label: 'Hours per Day', type: 'number'}],
    rows: [{c:[{v: 'Work'}, {v: 11}]},
           {c:[{v: 'Eat'}, {v: 2}]},
           {c:[{v: 'Commute'}, {v: 2}]},
           {c:[{v: 'Watch TV'}, {v:2}]},
           {c:[{v: 'Sleep'}, {v:7, f:'7.000'}]}]
    }, 0.6);

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

var data = new google.visualization.DataTable();
data.addColumn('string', 'Task');
data.addColumn('number', 'Hours per Day');
data.addRows([
  ['Work', 11],
  ['Eat', 2],
  ['Commute', 2],
  ['Watch TV', 2],
  ['Sleep', {v:7, f:'7.000'}]
]);

שיטות

data.addRow();  // Add an empty row
data.addRow(['Hermione', new Date(1999,0,1)]); // Add a row with a string and a date value.

// Add a row with two cells, the second with a formatted value.
data.addRow(['Hermione', {v: new Date(1999,0,1),
                          f: 'January First, Nineteen ninety-nine'}
]);

data.addRow(['Col1Val', null, 'Col3Val']); // Second column is undefined.
data.addRow(['Col1Val', , 'Col3Val']);     // Same as previous.

data.addRows([
  ['Ivan', new Date(1977,2,28)],
  ['Igor', new Date(1962,7,5)],
  ['Felix', new Date(1983,11,17)],
  ['Bob', null] // No date set for Bob.
]);

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}

{"cols":[{"id":"Col1","label":"","type":"date"}],
 "rows":[
   {"c":[{"v":"a"},{"v":"Date(2010,10,6)"}]},
   {"c":[{"v":"b"},{"v":"Date(2010,10,7)"}]}
 ]
}

הפורמט של פרמטר ה-JavaScript ליטראלי הנתונים של הבונה

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

קודם כול, נראה דוגמה לאובייקט JavaScript פשוט שמתאר טבלה עם שלוש שורות ושלוש עמודות (הסוגים String, Number ו-Date):

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ],
  p: {foo: 'hello', bar: 'world!'}
}

עכשיו נתאר את התחביר:

אובייקט ה-data מורכב משני מאפיינים נדרשים ברמה העליונה, cols ו-rows, ומאפיין p אופציונלי שהוא מפה של ערכים שרירותיים.

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

נכס אחד (cols)

cols הוא מערך של אובייקטים שמתארים את המזהה והסוג של כל עמודה. כל מאפיין הוא אובייקט עם המאפיינים הבאים (תלוי אותיות רישיות):

• type [חובה] סוג הנתונים של הנתונים בעמודה. תומכת בערכי המחרוזת הבאים (דוגמאות כוללות את המאפיין v: , מתואר מאוחר יותר):
  • 'בוליאני' - ערך בוליאני של JavaScript ('true' או 'false'). ערך לדוגמה: v:'true'
  • 'מספר' - ערך מספר ב-JavaScript. ערכים לדוגמה: v:7 , v:3.14, v:-55
  • 'string' – ערך מחרוזת JavaScript. ערך לדוגמה: v:'hello'
  • 'date' - אובייקט JavaScript Date (חודש המבוסס על אפס), כאשר השעה נחתכה. ערך לדוגמה: v:new Date(2008, 0, 15)
  • 'תאריך' - אובייקט JavaScript 'תאריך', כולל השעה. ערך לדוגמה: v:new Date(2008, 0, 15, 14, 30, 45)
  • 'timeofday' - מערך של שלושה מספרים ורביעית אופציונלית, שמייצגת את השעה (0 מציין חצות), דקה, שנייה ואלפית שנייה אופציונלית. ערכים לדוגמה: v:[8, 15, 0], v: [6, 12, 1, 144]
• id [אופציונלי] מזהה מחרוזת של העמודה. חייב להיות ייחודי בטבלה. צריך להשתמש בתווים אלפאנומריים בסיסיים, כך שהדף המארח לא צריך תווי בריחה מיוחדים כדי לגשת לעמודה ב-JavaScript. הקפידו לא לבחור מילת מפתח של JavaScript. לדוגמה: id:'col_1'
• label [אופציונלי] ערך המחרוזת שחלק מהרכיבים החזותיים מציגים בעמודה הזו. לדוגמה: label:'Height'
• pattern [אופציונלי] דפוס מחרוזת ששימש את מקור הנתונים כדי לעצב ערכים בעמודות של ספרות, תאריך או שעה. המסמך הזה מיועד לעיון בלבד. סביר להניח שלא יהיה צורך לקרוא את הדפוס והוא לא חייב להיות קיים. הלקוח Google Vision לא משתמש בערך הזה (הוא קורא את הערך בפורמט של התא). אם ה-DataTable הגיע ממקור נתונים בתגובה לשאילתה עם תנאי format, סביר להניח שהדפוס שציינתם בתנאי הזה יוחזר בערך הזה. הסטנדרטים המומלצים לדפוס הם DecimalFormat של ה-ICU ו- SimpleDateFormat .
• p [אופציונלי] אובייקט שהוא מפה של ערכים מותאמים אישית שהוחלו על התא. הערכים האלה יכולים להיות מכל סוג של JavaScript. אם התצוגה החזותית תומכת במאפיינים ברמת התא, היא תתאר אותם. אחרת, המערכת תתעלם מהנכס הזה. לדוגמה: p:{style: 'border: 1px solid green;'}.

דוגמה ל-cols

cols: [{id: 'A', label: 'NEW A', type: 'string'},
       {id: 'B', label: 'B-label', type: 'number'},
       {id: 'C', label: 'C-label', type: 'date'}]

נכס rows

המאפיין rows מכיל מערך של אובייקטים מסוג שורה.

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

אובייקטים של תא

כל תא בטבלה מתואר על ידי אובייקט עם המאפיינים הבאים:

• v [אופציונלי] ערך התא. סוג הנתונים צריך להתאים לסוג הנתונים בעמודה. אם התא הוא null, המאפיין v צריך להיות null, אבל עדיין יכול להיות לו המאפיינים f ו-p.
• f [אופציונלי] גרסת מחרוזת של הערך v, בפורמט לתצוגה. בדרך כלל הערכים יהיו זהים, אבל אין צורך לעשות זאת. לכן, אם מציינים את Date(2008, 0, 1) עבור v, צריך לציין את הערך "1 בינואר 2008" או מחרוזת אחרת לנכס הזה. הערך הזה לא נבדק מול הערך v. התצוגה החזותית לא תשתמש בערך הזה לחישוב, אלא רק כתווית להצגה. אם לא מזינים את הפרמטר, גרסת המחרוזת של v תיווצר באופן אוטומטי באמצעות הפורמט שמוגדר כברירת מחדל. אפשר לשנות את הערכים של f באמצעות כלי פורמט משלכם, להגדיר אותם עם setFormattedValue() או עם setCell() או לאחזר אותם באמצעות getFormattedValue().
• p [אופציונלי] אובייקט שהוא מפה של ערכים מותאמים אישית שהוחלו על התא. הערכים האלה יכולים להיות מכל סוג של JavaScript. אם התצוגה החזותית תומכת במאפיינים ברמת התא, היא תתאר אותם. אפשר לאחזר את המאפיינים האלה באמצעות ה-methods getProperty() ו-getProperties(). לדוגמה: p:{style: 'border: 1px solid green;'}.

התאים במערך השורות צריכים להיות באותו סדר כמו תיאורי העמודות שלהם ב-cols. כדי לציין תא ריק, אפשר לציין את null, להשאיר את השדה ריק בתא במערך או להשמיט חברים במערך. לכן, כדי לציין שורה עם ערך null בשני התאים הראשונים, אפשר לציין את [ , , {cell_val}] או את [null, null, {cell_val}].

הנה דוגמה לאובייקט טבלה עם שלוש עמודות, שמולאו בשלוש שורות של נתונים:

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ]
}

נכס p

המאפיין p ברמת הטבלה הוא מפה של ערכים מותאמים אישית שהוחלה על כל DataTable. הערכים האלה יכולים להיות מכל סוג של JavaScript. אם התצוגה החזותית תומכת במאפיינים ברמת טבלת הנתונים, היא תתאר אותם. אחרת, הנכס הזה יהיה זמין לשימוש באפליקציה. לדוגמה: p:{className: 'myDataTable'}.

מחלקה ב-DataView

תצוגה לקריאה בלבד של DataTable בסיסי. השדה DataView מאפשר לבחור רק קבוצת משנה של העמודות או השורות. הוא גם מאפשר לשנות את הסדר של עמודות או שורות ולשכפל עמודות או שורות.

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

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

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

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

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

אפשר לשלב את DataView.getFilteredRows() עם DataView.setRows() כדי ליצור DataView עם קבוצת משנה מעניינת של נתונים, כפי שמוצג כאן:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(6);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));
data.setCell(3, 0, 'Frank');
data.setCell(3, 1, new Date(2007, 11, 28));
data.setCell(4, 0, 'Floyd');
data.setCell(4, 1, new Date(2005, 3, 13));
data.setCell(5, 0, 'Fritz');
data.setCell(5, 1, new Date(2007, 9, 2));

// Create a view that shows everyone hired since 2007.
var view = new google.visualization.DataView(data);
view.setRows(view.getFilteredRows([{column: 1, minValue: new Date(2007, 0, 1)}]));
var table = new google.visualization.Table(document.getElementById('test_dataview'));
table.draw(view, {sortColumn: 1});

יצרנים

יש שתי דרכים ליצור מכונה חדשה של DataView:

מבנה 1

var myView = new google.visualization.DataView(data)

data

DataTable או DataView ששימשו לאתחול התצוגה. כברירת מחדל, התצוגה מכילה את כל העמודות והשורות בטבלת הנתונים או בתצוגת הנתונים הבסיסית, בסדר המקורי. כדי להסתיר או להציג שורות או עמודות בתצוגה הזו, צריך לקרוא ל-methods set...() או hide...() המתאימות.

למידע נוסף:

setColumns(), hideColumns(), setRows(), ו-hideRows().

מבנה 2

ה-constructor הזה יוצר DataView חדש על ידי הקצאת DataView עם סריאליזציה ל-DataTable. התהליך הזה עוזר ליצור מחדש את ה-DataView שעברתם סריאליזציה באמצעות DataView.toJSON().

var myView = google.visualization.DataView.fromJSON(data, viewAsJson)

נתונים

האובייקט DataTable שבו השתמשתם כדי ליצור את DataView, שבו קראתם DataView.toJSON(). אם הטבלה הזו שונה מהטבלה המקורית, יתקבלו תוצאות בלתי צפויות.

viewAsJson

מחרוזת ה-JSON שהוחזרה על ידי DataView.toJSON(). זהו תיאור של השורות שצריך להציג או להסתיר ב-DataTable שב-data.

שיטות

// Show some columns directly from the underlying data.
// Shows column 3 twice.
view.setColumns([3, 4, 3, 2]);

// Underlying table has a column specifying a value in centimeters.
// The view imports this directly, and creates a calculated column
// that converts the value into inches.
view.setColumns([1,{calc:cmToInches, type:'number', label:'Height in Inches'}]);
function cmToInches(dataTable, rowNum){
  return Math.floor(dataTable.getValue(rowNum, 1) / 2.54);
}

סיווגChartWrapper

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

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

עם זאת, בשלב הזה, ChartWrapper מפיץ רק קבוצת משנה של אירועים שהופעלו באמצעות תרשימים: בחירה, מוכן ושגיאה. אירועים אחרים לא מועברים באמצעות המכונה של ChartWrapper. כדי לקבל אירועים אחרים צריך לקרוא ל-getChart() ולהירשם לאירועים ישירות בנקודת האחיזה של התרשים, כמו בדוגמה הבאה:

var wrapper;
function drawVisualization() {

  // Draw a column chart
  wrapper = new google.visualization.ChartWrapper({
    chartType: 'ColumnChart',
    dataTable: [['Germany', 'USA', 'Brazil', 'Canada', 'France', 'RU'],
                [700, 300, 400, 500, 600, 800]],
    options: {'title': 'Countries'},
    containerId: 'visualization'
  });

  // Never called.
  google.visualization.events.addListener(wrapper, 'onmouseover', uselessHandler);

  // Must wait for the ready event in order to
  // request the chart and subscribe to 'onmouseover'.
  google.visualization.events.addListener(wrapper, 'ready', onReady);

  wrapper.draw();

  // Never called
  function uselessHandler() {
    alert("I am never called!");
  }

  function onReady() {
    google.visualization.events.addListener(wrapper.getChart(), 'onmouseover', usefulHandler);
  }

  // Called
  function usefulHandler() {
    alert("Mouseover event!");
  }
}

יצרן

ChartWrapper(opt_spec)

opt_spec

[אופציונלי] - אובייקט JSON שמגדיר את התרשים, או גרסת מחרוזת טורית של האובייקט הזה. הפורמט של האובייקט הזה מוצג במסמכי התיעוד שלdrawChart(). אם לא מציינים זאת, צריך להגדיר את כל המאפיינים המתאימים באמצעות methods של set... שחשופות על ידי האובייקט הזה.

שיטות

ChartWrapper מציג את השיטות הנוספות הבאות:

אירועים

אובייקט ChartWrapper זורק את האירועים הבאים. לתשומת ליבך, עליך להתקשר אל ChartWrapper.draw() לפני שאירועים מוצגים.

דוגמה

שני קטעי הקוד הבאים יוצרים תרשים קו מקביל. בדוגמה הראשונה נעשה שימוש בסימון מילולי של JSON כדי להגדיר את התרשים. בדוגמה השנייה נעשה שימוש בשיטות ChartWrapper כדי להגדיר את הערכים האלה.

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Visualization API Sample</title>
<!--
  One script tag loads all the required libraries!
-->
<script type="text/javascript"
      src='https://www.gstatic.com/charts/loader.js'></script>
<script>
  google.charts.load('current);
  google.charts.setOnLoadCallback(drawVisualization);

  function drawVisualization() {
    var wrap = new google.visualization.ChartWrapper({
       'chartType':'LineChart',
       'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
       'containerId':'visualization',
       'query':'SELECT A,D WHERE D > 100 ORDER BY D',
       'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
       });
     wrap.draw();
  }
</script>
</head>
<body>
  <div id="visualization" style="height: 400px; width: 400px;"></div>
</body>
</html>

אותו תרשים, עכשיו באמצעות שיטות הגדרה:

<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html; charset=utf-8'/>
<title>Google Visualization API Sample</title>
<!-- One script tag loads all the required libraries!
-->
<script type="text/javascript"
    src='https://www.gstatic.com/charts/loader.js'></script>
<script type="text/javascript">
  google.charts.load('current');
  google.charts.setOnLoadCallback(drawVisualization);
  function drawVisualization() {
    // Define the chart using setters:
    var wrap = new google.visualization.ChartWrapper();
    wrap.setChartType('LineChart');
    wrap.setDataSourceUrl('http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');
    wrap.setContainerId('visualization');
    wrap.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    wrap.setOptions({'title':'Population Density (people/km^2)', 'legend':'none'});
    wrap.draw();
  }
</script>
</head>
<body>
  <div id='visualization' style='height: 400px; width: 400px;'></div>
</body>
</html>

כיתה של 'עורך תרשימים'

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

כדי להשתמש ב-ChartEditor:

1. טוענים את החבילה charteditor. ב-google.charts.load(), טוענים את החבילה 'charteditor'. אין צורך לטעון את החבילות של סוג התרשים שאתם מעבדים בעורך. עורך התרשימים יטען בשבילכם כל חבילה לפי הצורך.
2. יוצרים אובייקט ChartWrapper שמגדיר את התרשים שהמשתמשים יכולים להתאים אישית. התרשים הזה יוצג בתיבת הדו-שיח, והמשתמש יוכל להשתמש בעורך כדי לעצב מחדש את התרשים, לשנות את סוגי התרשים ואפילו לשנות את נתוני המקור.
3. יוצרים מכונה חדשה של ChartEditor ונרשמים כדי להאזין לאירוע "ok". האירוע הזה מופעל כשהמשתמש לוחץ על הלחצן 'אישור' בתיבת הדו-שיח. לאחר קבלת התרשים, עליך להפעיל את ChartEditor.getChartWrapper() כדי לאחזר את התרשים ששונו על ידי המשתמש.
4. מתקשרים אל ChartEditor.openDialog() ומעבירים את ChartWrapper. תיפתח תיבת הדו-שיח. לחצני תיבת הדו-שיח מאפשרים למשתמש לסגור את העורך. המכונה ChartEditor זמינה כל עוד היא בתוקף. היא לא נמחקת באופן אוטומטי אחרי שהמשתמש סוגר את תיבת הדו-שיח.
5. כדי לעדכן את התרשים בקוד, צריך להתקשר למספר setChartWrapper().

שיטות

אפשרויות

עורך התרשימים תומך באפשרויות הבאות:

אירועים

עורך התרשימים מציג את האירועים הבאים:

דוגמה

הקוד לדוגמה הבא פותח תיבת דו-שיח של עורך תרשימים עם תרשים קו מאוכלס. אם המשתמש ילחץ על 'אישור', התרשים הערוך יישמר בערך <div> שצוין בדף.

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  <title>
    Google Visualization API Sample
  </title>
  <script type="text/javascript"
    src="https://www.gstatic.com/charts/loader.js"></script>
  <script type="text/javascript">
    google.charts.load('current', {packages: ['charteditor']});
  </script>
  <script type="text/javascript">
    google.charts.setOnLoadCallback(loadEditor);
    var chartEditor = null;

    function loadEditor() {
      // Create the chart to edit.
      var wrapper = new google.visualization.ChartWrapper({
         'chartType':'LineChart',
         'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
         'query':'SELECT A,D WHERE D > 100 ORDER BY D',
         'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
      });

      chartEditor = new google.visualization.ChartEditor();
      google.visualization.events.addListener(chartEditor, 'ok', redrawChart);
      chartEditor.openDialog(wrapper, {});
    }

    // On "OK" save the chart to a <div> on the page.
    function redrawChart(){
      chartEditor.getChartWrapper().draw(document.getElementById('vis_div'));
    }

  </script>
</head>
<body>
  <div id="vis_div" style="height: 400px; width: 600px;"></div>
</body>
</html>

שיטות למניפולציה של נתונים

מרחב השמות google.visualization.data מכיל שיטות סטטיות לביצוע פעולות דומות ל-SQL על אובייקטים של DataTable, למשל הצטרפות אליהם או קיבוץ לפי ערך עמודה.

מרחב השמות google.visualization.data חושף את השיטות הבאות:

group()

הפונקציה מקבלת אובייקט DataTable מאוכלס ומבצעת פעולת GROUP BY דמוית SQL, כדי להחזיר טבלה עם שורות שמקובצות לפי ערכי העמודה שצוינו. שימו לב שהפעולה הזו לא משנה את הקלט DataTable.

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

מרחב השמות google.visualization.data כולל כמה ערכי צבירה שימושיים (לדוגמה, sum ו-count), אבל אפשר להגדיר משלכם (למשל, StandardDeviation או secondHighest). הוראות להגדרת אתר אגרגטור משלך מפורטות אחרי תיאור השיטה.

תחביר

google.visualization.data.group(data_table, keys, columns)

data_table

הקלט DataTable. הפעולה הזו לא תשתנה בהתקשרות אל group().

מפתחות

מערך של מספרים ו/או אובייקטים שמציינים את העמודות שרוצים לקבץ. טבלת התוצאות כוללת את כל העמודות במערך הזה, וגם את כל העמודות ב-columns. אם מספר הוא מספר, זהו אינדקס העמודה של הקלט DataTable לקיבוץ. אם אובייקט, הוא יכלול פונקציה שיכולה לשנות את העמודה שצוינה (לדוגמה, אפשר להוסיף את הערך 1 לערך בעמודה הזו). האובייקט צריך לכלול את המאפיינים (properties) הבאים:

• column – מספר שהוא אינדקס של עמודות מ-dt שעליו רוצים להחיל את הטרנספורמציה.
• modifier – פונקציה שמקבלת ערך אחד (ערך התא בכל שורה) ומחזירה את הערך שהשתנה. הפונקציה הזו משמשת לשינוי הערך של העמודה כדי לסייע בקיבוץ. לדוגמה, כדי להפעיל את הפונקציה whatQuarter שמחשבת רבעון מעמודת תאריך, כדי שה-API יוכל לקבץ שורות לפי רבעון. הערך המחושב מוצג בעמודות המפתח בטבלה שמוחזרת. אפשר להצהיר על הפונקציה הזו בתוך האובייקט, או שהיא יכולה להיות פונקציה שמגדירים במקום אחר בקוד (היא חייבת להיות בטווח הקריאה). ב-API יש פונקציית שינוי פשוטה אחת. כאן מפורטות הוראות ליצירת פונקציות שימושיות יותר משלכם. צריך לדעת מה סוג הנתונים שהפונקציה הזו יכולה לקבל, ולקרוא לו רק בעמודות מהסוג הזה. צריך לדעת גם את סוג ההחזרה של הפונקציה הזו, ולהצהיר עליו במאפיין type שמתואר בהמשך.
• type – הסוג שהוחזר על-ידי הפונקציה modifier. השם צריך להיות שם של סוג מחרוזת JavaScript, לדוגמה: 'number' או 'boolean'.
• label – [אופציונלי] תווית מחרוזת להקצאת העמודה הזו ב-DataTable המוחזר.
• id – [אופציונלי] מזהה מחרוזת להקצאת העמודה הזו ב-DataTable שמוחזר.

דוגמאות: [0], [0,2], [0,{column:1, modifier:myPlusOneFunc, type:'number'},2]

columns (עמודות)

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

• column - מספר שמציין את האינדקס של העמודה להצגה.
• aggregation – פונקציה שמקבלת מערך של כל הערכים של העמודה הזו בקבוצת השורות הזו, ומחזירה ערך יחיד שיוצג בשורת התוצאה. הערך המוחזר צריך להיות מהסוג שצוין במאפיין type של האובייקט. בהמשך מופיעים פרטים על יצירת פונקציית צבירה משלכם. צריך לדעת אילו סוגי נתונים ה-method הזה מקבלת, ולהפעיל אותם רק בעמודות מהסוג המתאים. ב-API יש כמה פונקציות צבירה שימושיות. בקטע פונקציות צבירה זמינות שבהמשך אפשר לראות רשימה, או יצירת פונקציית צבירה כדי ללמוד איך לכתוב פונקציית צבירה משלכם.
• type - הסוג המוחזר של פונקציית הצבירה. השם צריך להיות שם של סוג מחרוזת JavaScript, לדוגמה: 'number' או 'boolean'.
• label – [אופציונלי] תווית מחרוזת שצריך להחיל על העמודה הזו בטבלה שמוחזרת.
• id – [אופציונלי] מזהה מחרוזת שצריך להחיל על העמודה הזו בטבלה שמוחזרת.

ערך החזרה

DataTable עם עמודה אחת לכל עמודה במפתחות ועמודה אחת לכל עמודה ב-columns. הטבלה ממוינת לפי שורות מפתח, משמאל לימין.

דוגמה

// This call will group the table by column 0 values.
// It will also show column 3, which will be a sum of
// values in that column for that row group.
var result = google.visualization.data.group(
  dt,
  [0],
  [{'column': 3, 'aggregation': google.visualization.data.sum, 'type': 'number'}]
);

*Input table*
1  'john'  'doe'            10
1  'jane'  'doe'           100
3  'jill'  'jones'          50
3  'jack'  'jones'          75
5  'al'    'weisenheimer'  500

*Output table*
1  110
3  125
5  500

פונקציות מגבילות זמינות

ה-API מספק את פונקציות הצירוף הבאות, שאפשר להעביר למפתחות. modifier כדי להתאים אישית את התנהגות הקיבוץ.

פונקציות צבירה זמינות

ה-API מספק את פונקציות הצבירה הבאות שאפשר להעביר לעמודות. aggregation.

יצירת פונקציית מגביל

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

// Input type: Date
// Return type: number (1-4)
function getQuarter(someDate) {
  return Math.floor(someDate.getMonth()/3) + 1;
}

יצירת פונקציית צבירה

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

// Input type: Array of any type
// Return type: number
function count(values) {
  return values.length;
}

join()

השיטה הזו מאחדת שתי טבלאות נתונים (DataTable או DataView אובייקטים) לטבלת תוצאות יחידה, בדומה להצהרת SQL JOIN. מציינים צמד אחד או יותר של עמודות (עמודות מפתח) בין שתי הטבלאות, וטבלת הפלט כוללת את השורות בהתאם לשיטת האיחוד שציינתם: רק שורות שבהן שני המפתחות תואמים, כל השורות מטבלה אחת או כל השורות משתי הטבלאות, גם אם המפתחות תואמים. טבלת התוצאות כוללת רק את עמודות המפתח, ועמודות נוספות שציינתם. שימו לב של-dt2 לא יכולים להיות מפתחות כפולים, אבל ל-dt1 יכול להיות. המונח 'מפתח' הוא שילוב של כל הערכים בעמודת המפתח, ולא של ערך ספציפי בעמודת המפתח. לכן, אם בשורה יש ערכים בתאים: A | B | C, ו-0 ו-1 הן עמודות מפתח, המפתח בשורה הזו הוא AB.

תחביר

google.visualization.data.join(dt1, dt2, joinMethod,
                                 keys, dt1Columns, dt2Columns);

dt1

אכלוס DataTable כדי לצרף עם dt2.

dt2

DataTable מאוכלסים שאפשר לצרף באמצעות dt1. הטבלה הזו לא יכולה לכלול כמה מפתחות זהים (כאשר מפתח הוא שילוב של ערכים מעמודות המפתח).

joinMethod

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

• 'full' – טבלת הפלט כוללת את כל השורות משתי הטבלאות, ללא קשר להתאמה של המפתחות. בשורות שלא תואמות יופיעו רשומות תאים ריקות; שורות שתואמות לחיפוש משולבות.
• 'inner' – הצירוף המלא מסונן כך שיכלול רק שורות שבהן המפתחות תואמים.
• 'left' – טבלת הפלט כוללת את כל השורות מ-dt1, גם אם יש שורות תואמות מ-dt2 וגם אם לא.
• 'right' – טבלת הפלט כוללת את כל השורות מ-dt2, גם אם יש שורות תואמות מ-dt1 וגם אם לא.

מפתחות

מערך של עמודות מפתח להשוואה משתי הטבלאות. כל זוג הוא מערך של שני רכיבים, הראשון הוא מפתח ב-dt1 והשני הוא מפתח ב-dt2. המערך הזה יכול לציין עמודות לפי האינדקס, המזהה או התווית שלהן. ראו getColumnIndex.
הסוג של העמודות צריך להיות זהה בשתי הטבלאות. כל המפתחות שצוינו חייבים להתאים בהתאם לכלל שנקבע על ידי joinMethod כדי לכלול שורה מהטבלה. עמודות המפתח תמיד נכללות בטבלת הפלט. רק dt1, הטבלה השמאלית, יכול לכלול מפתחות כפולים. מפתחות ב-dt2 חייבים להיות ייחודיים. המונח 'מפתח' כאן הוא קבוצה ייחודית של עמודות מפתח, ולא ערכים בודדים בעמודות. לדוגמה, אם עמודות המפתח היו A ו-B, הטבלה הבאה תכלול רק ערכי מפתח ייחודיים (ולכן ניתן להשתמש בה כ-dt2):

A	B
יאן	אדום
יאן	כחול
Fred	אדום

דוגמה: [[0,0], [2,1]] משווה בין הערכים מהעמודה הראשונה בשתי הטבלאות וגם מהעמודה השלישית מ-dt1 לבין העמודה השנייה מ-dt1.

dt1Columns

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

dt2Columns

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

ערך החזרה

DataTable עם עמודות המפתח, dt1Columns ו-dt2Columns. הטבלה ממוינת לפי עמודות המפתח, משמאל לימין. כשהערך של joinMethod הוא 'inner', צריך לאכלס את כל תאי המפתח. בשיטות איחוד אחרות, אם לא נמצא מפתח תואם, הערך של הטבלה יהיה null לכל תא מפתח שלא נמצאה לו התאמה.

דוגמאות

*Tables*
dt1                        dt2
bob  | 111 | red           bob   | 111 | point
bob  | 111 | green         ellyn | 222 | square
bob  | 333 | orange        jane  | 555 | circle
fred | 555 | blue          jane  | 777 | triangle
jane | 777 | yellow        fred  | 666 | dodecahedron
* Note that right table has duplicate Jane entries, but the key we will use is
* columns 0 and 1. The left table has duplicate key values, but that is
* allowed.

*Inner join* google.visualization.data.join(dt1, dt2, 'inner', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red    | point
bob  | 111 | green  | point
jane | 777 | yellow | triangle
* Note that both rows from dt1 are included and matched to
* the equivalent dt2 row.


*Full join* google.visualization.data.join(dt1, dt2, 'full', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red    | point
bob   | 111 | green  | point
bob   | 333 | orange | null
ellyn | 222 | null | square
fred  | 555 | blue   | null
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle


*Left join*  google.visualization.data.join(dt1, dt2, 'left', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red | point
bob  | 111 | green | point
bob  | 333 | orange | null
fred | 555 | blue | null
jane | 777 | yellow | triangle


*Right join*  google.visualization.data.join(dt1, dt2, 'right', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red | point
bob   | 111 | green | point
ellyn | 222 | null | square
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle

מעצבי עיצוב

ב-Google Vision API יש כלים לעיצוב מחדש שאפשר להשתמש בהם כדי לשנות את הפורמט של הנתונים בתצוגה החזותית. כלי העיצוב האלה משנים את הערך בפורמט של העמודה שצוינה בכל השורות. הערה:

• כלי העיצוב משנים רק את הערכים בפורמט, ולא את הערכים הבסיסיים. לדוגמה, הערך שיוצג יהיה '$1,000.00', אבל הערך הבסיסי עדיין יהיה '1000'.
• כלי העיצוב משפיעים רק על עמודה אחת בכל פעם. כדי לשנות את הפורמט של כמה עמודות, צריך להחיל את הפורמט על כל עמודה שרוצים לשנות.
• אם אתם משתמשים גם בעיצובים שהוגדרו על ידי המשתמש, כלים מסוימים לעיצוב תצוגה חזותית של Google יבטלו את כל כלי העיצוב שהוגדרו על ידי המשתמש.

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

חשוב: אפשר להשתמש בעיצובים רק עם DataTable; אי אפשר להשתמש בהם עם DataView (האובייקטים של DataView הם לקריאה בלבד).

אלה השלבים הכלליים לשימוש בכלי לעיצוב:

1. מקבלים את האובייקט DataTable המאוכלס.
2. לכל עמודה שרוצים לשנות את הפורמט שלה:
   1. יוצרים אובייקט שמפרט את כל האפשרויות של העיצוב. זהו אובייקט JavaScript בסיסי עם קבוצה של מאפיינים וערכים. אפשר לעיין במסמכי העזרה של כלי העיצוב כדי לראות אילו מאפיינים נתמכים. (אופציונלי, אפשר להעביר באובייקט סימון מילולי של אובייקט שמציין את האפשרויות).
   2. יוצרים את העיצוב ומעבירים את אובייקט האפשרויות.
   3. קוראים לפונקציה formatter.format(table, colIndex) ומעבירים את המספר DataTable ואת מספר הנתונים בעמודה (המבוסס על אפס) של הנתונים לפרמט מחדש. חשוב לשים לב שאפשר להחיל רק פורמט אחד על כל עמודה. שימוש בכלי לעיצוב שני פשוט יחליף את האפקטים של העמודה הראשונה.
      חשוב: פורמטים רבים מחייבים שימוש בתגי HTML כדי להציג עיצוב מיוחד. אם התצוגה החזותית תומכת באפשרות allowHtml, צריך להגדיר אותה כ-True.

לפניכם דוגמה לשינוי של ערכי התאריך בפורמט של עמודת תאריך, כך שהפורמט שלהם יהיה בפורמט ארוך ('1 בינואר 2009'):

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(3);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));

// Create a formatter.
// This example uses object literal notation to define the options.
var formatter = new google.visualization.DateFormat({formatType: 'long'});

// Reformat our data.
formatter.format(data, 1);

// Draw our data
var table = new google.visualization.Table(document.getElementById('dateformat_div'));
table.draw(data, {showRowNumber: true});

רוב המעצבים מציגים את שתי השיטות הבאות:

שיטה	תיאור
google.visualization.formatter_name(options)	בונה, כאשר formatter_name הוא שם של specfic formatterclass. options – אובייקט JavaScript גנרי שמציין את האפשרויות לאותו פורמט. האובייקט הזה הוא אובייקט גנרי עם צמדי נכס/ערך עם מאפיינים שספציפיים לאותו פורמט. במסמכי התיעוד של הפורמט הספציפי הרלוונטי מוסבר אילו אפשרויות נתמכות. הנה שתי דרכים לדוגמה לקרוא ל-constructor של האובייקט DateFormat (תאריך פורמט) ולהעביר אותו בשני מאפיינים: // Object literal technique var formatter = new google.visualization.DateFormat({formatType: 'long', timeZone: -5}); // Equivalent property setting technique var options = new Object(); options['formatType'] = 'long'; options['timeZone'] = -5; var formatter = new google.visualization.DateFormat(options);
format(data, colIndex)	עיצוב מחדש של הנתונים בעמודה שצוינה. data – ערך DataTable שמכיל את הנתונים שצריך לשנות את הפורמט שלהם. אי אפשר להשתמש כאן ב-DataView. colIndex - האינדקס אפס של העמודה שבה יש לעצב. כדי לעצב כמה עמודות צריך לקרוא ל-method הזה כמה פעמים, עם ערכי ColIndex שונים.

 

Google Vision API מספק את עיצובי העיצוב הבאים:

שם המעצב	תיאור
ArrowFormat	הפונקציה מוסיפה חץ למעלה או למטה, שמציין אם ערך התא הוא מעל או מתחת לערך שצוין.
BarFormat	הפונקציה מוסיפה עמודה צבעונית, שהכיוון והצבע שלה מציינים אם ערך התא הוא מעל או מתחת לערך שצוין.
ColorFormat	צבע תא לפי האם הערכים נמצאים בטווח שצוין.
DateFormat	מגדיר את הערך 'תאריך' או 'תאריך' בכמה דרכים, כולל '1 בינואר 2009', '1/1/09' ו-'1 בינואר 2009'.
NumberFormat	עיצוב היבטים שונים של ערכים מספריים.
PatternFormat	הפונקציה משרשרת ערכי תאים באותה שורה לתא שצוין, יחד עם טקסט שרירותי.

ArrowFormat

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

אפשרויות

ArrowFormat תומך באפשרויות הבאות שמועברות ל-constructor:

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

קוד לדוגמה

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues Change');
data.addRows([
  ['Shoes', {v:12, f:'12.0%'}],
  ['Sports', {v:-7.3, f:'-7.3%'}],
  ['Toys', {v:0, f:'0%'}],
  ['Electronics', {v:-2.1, f:'-2.1%'}],
  ['Food', {v:22, f:'22.0%'}]
]);

var table = new google.visualization.Table(document.getElementById('arrowformat_div'));

var formatter = new google.visualization.ArrowFormat();
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true});

BarFormat

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

אפשרויות

BarFormat תומך באפשרויות הבאות שמועברות ל-constructor:

מקש Option	דוגמה תיאור
base	מספר שהוא ערך הבסיס שאליו צריך להשוות את ערך התא. אם ערך התא גבוה יותר, הוא ייצייר מימין לבסיס. אם ערך התא נמוך יותר, הוא ייצייר לשמאל. ערך ברירת המחדל הוא 0.
colorNegative	מחרוזת שמציינת את הקטע של הערך השלילי בעמודות. הערכים האפשריים הם 'red', 'green' (ירוק) ו-'blue' (כחול). ערך ברירת המחדל הוא 'red' (אדום).
colorPositive	מחרוזת שמציינת את הצבע של קטע הערך החיובי של עמודות. הערכים האפשריים הם 'אדום', 'ירוק' ו 'כחול'. ברירת המחדל היא 'כחול'.
drawZeroLine	ערך בוליאני שמציין אם יש לשרטט קו בסיס כהה של פיקסל אחד כאשר קיימים ערכים שליליים. הקו הכהה מופיע בתמונה כדי לשפר את הסריקה החזותית של העמודות. ערך ברירת המחדל הוא False.
max	הערך המקסימלי של טווח העמודות. ערך ברירת המחדל הוא הערך הכי גבוה בטבלה.
min	ערך המספר המינימלי בטווח העמודות. ערך ברירת המחדל הוא הערך הנמוך ביותר בטבלה.
showValue	אם True, יוצגו ערכים ועמודות. אם True, יוצגו רק עמודות. ערך ברירת המחדל הוא True.
width	העובי של כל עמודה, בפיקסלים. ערך ברירת המחדל הוא 100.

קוד לדוגמה

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('barformat_div'));

var formatter = new google.visualization.BarFormat({width: 120});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

ColorFormat

הקצאת צבעים לחזית או לרקע של תא מספרי, בהתאם לערך התא. הפורמט הזה הוא יוצא דופן, כי הוא לא משתמש באפשרויות שלו ב-constructor. במקום זאת, צריך לקרוא ל-addRange() או ל-addGradientRange() כמה פעמים שרוצים, כדי להוסיף טווחי צבעים, לפני הקריאה אל format(). אפשר לציין צבעים בכל פורמט מקובל של HTML, לדוגמה "שחור", "#000000" או "#000".

שיטות

ב-ColorFormat יש תמיכה בשיטות הבאות:

שיטה	תיאור
google.visualization.ColorFormat()	בונה. לא מקבלת ארגומנטים.
addRange(from, to, color, bgcolor)	מציינת צבע חזית ו/או צבע רקע של תא, בהתאם לערך התא. לכל תא עם ערך בטווח שצוין מ-to יוקצו color ו-bgcolor. חשוב להבין שהטווח לא כולל, כי יצירת טווח מ-1 עד 1,000 ושנייה מ-1,000 — 2,000 לא יכסה את הערך 1,000! from – [String, Number, Date, DateTime או TimeOfDay] הגבול התחתון של הטווח (כולל) של הטווח, או ערך null. אם הערך הוא null, הפונקציה תתאים לערך -TCF. השוו את גבולות המחרוזת לפי סדר אלפביתי לערכי המחרוזת. to – [String, מספר, תאריך, DateTime, או TimeOfDay] הגבול הגבוה (לא כולל) של הטווח, או null. אם הערך הוא null, הפונקציה תתאים ל-+ ההתאמה. גבולות המחרוזת ישוו לפי סדר האלפבית לערכי המחרוזת. צבע – הצבע שיש להחיל על טקסט בתאים תואמים. הערכים יכולים להיות ערכי '#RRGGBB' או קבועים מוגדרים של צבע (לדוגמה: '#FF0000' או 'אדום'). bgcolor – הצבע שיש להחיל על הרקע של תאים תואמים. הערכים יכולים להיות ערכי '#RRGGBB' או קבועים מוגדרים של צבע (לדוגמה: '#FF0000' או 'אדום').
addGradientRange(from, to, color, fromBgColor, toBgColor)	הקצאת צבע רקע מתוך טווח, בהתאם לערך התא. הצבע מותאם לערך התא בטווח שבין צבע גבול תחתון לצבע של גבול עליון. שימו לב שהשיטה הזו לא יכולה להשוות בין ערכי מחרוזות, מכיוון ש-addRange() יכול. טיפ: בדרך כלל קשה לצופים לזהות את טווחי הצבעים בצורה מדויקת. הטווח הפשוט והקל ביותר לקריאה הוא מצבע רוויי לחלוטין ללבן (למשל, #FF0000—FFFFFF). from – [Number, Date, DateTime או TimeOfDay] הגבול התחתון של הטווח (כולל) של הטווח, או null. אם הערך הוא null, הוא יתאים לערך -TCF. to – [Number, Date, DateTime או TimeOfDay] הגבול העליון (לא כולל) של הטווח, או null. אם הערך הוא null, הוא יתאים ל-+SCC. צבע – הצבע שיש להחיל על טקסט בתאים תואמים. הצבע זהה לכל התאים, ללא קשר לערך שלהם. fromBgColor – צבע הרקע של תאים שמחזיקים ערכים בקצה הנמוך של ההדרגתיות. הערכים יכולים להיות ערכי '#RRGGBB' או קבועים מוגדרים של צבע (לדוגמה: '#FF0000' או 'אדום'). toBgColor - צבע הרקע של תאים שמחזיקים ערכים בקצה העליון של ההדרגתיות. הערכים יכולים להיות ערכי '#RRGGBB' או קבועים מוגדרים של צבע (לדוגמה: '#FF0000' או 'אדום').
format(dataTable, columnIndex)	השיטה הרגילה format() להחלת העיצוב על העמודה שצוינה.

קוד לדוגמה

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('colorformat_div'));

var formatter = new google.visualization.ColorFormat();
formatter.addRange(-20000, 0, 'white', 'orange');
formatter.addRange(20000, null, 'red', '#33ff33');
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

DateFormat

מעצב ערך Date של JavaScript במגוון דרכים, כולל '1 בינואר 2016', '1/1/16' ו-'1 בינואר 2016'.

אפשרויות

DateFormat תומך באפשרויות הבאות שמועברות ל-constructor:

מקש Option	תיאור
formatType	אפשרות מהירה לעיצוב של התאריך. ערכי המחרוזת הבאים נתמכים, והתאריך 28 בפברואר 2016 השתנה בפורמט הבא: 'short' – פורמט קצר: למשל, "28/2/16" 'medium' – פורמט בינוני: לדוגמה, '28 בפברואר 2016' 'long' – פורמט ארוך: למשל, '28 בפברואר 2016' אי אפשר לציין גם formatType וגם pattern.
pattern	תבנית של פורמט מותאם אישית שצריך להחיל על הערך, בדומה לפורמט התאריך והשעה של ה-ICU. לדוגמה: var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"}); אי אפשר לציין גם formatType וגם pattern. בקטע הבא אפשר לקרוא פרטים נוספים על דפוסים.
timeZone	אזור הזמן שבו יש להציג את ערך התאריך. זהו ערך מספרי שמציין את שעון גריניץ' ואת המספר הזה של אזורי זמן (יכול להיות שלילי). האובייקטים של התאריך נוצרים כברירת מחדל לפי אזור הזמן המשוער במחשב שבו הם נוצרו. האפשרות הזו משמשת להצגת הערך באזור זמן אחר. לדוגמה, אם יצרתם את האובייקט 'תאריך' של 17:00 במחשב שנמצא בגריניץ' שבאנגליה, והגדרתם אזור זמן -5 (options['timeZone'] = -5, או שעון החוף המזרחי של ארה"ב בארה"ב), הערך שיוצג יהיה 12:00 בצהריים.

שיטות

ב-DateFormat יש תמיכה בשיטות הבאות:

שיטה	תיאור
google.visualization.DateFormat(options)	בונה. מידע נוסף זמין בקטע האפשרויות שלמעלה.
format(dataTable, columnIndex)	השיטה הרגילה של format() להחלת העיצוב על העמודה שצוינה.
formatValue(value)	מחזירה את הערך בפורמט המתאים של ערך נתון. לשיטה הזו לא נדרש DataTable.

קוד לדוגמה

function drawDateFormatTable() {
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Employee Name');
  data.addColumn('date', 'Start Date (Long)');
  data.addColumn('date', 'Start Date (Medium)');
  data.addColumn('date', 'Start Date (Short)');
  data.addRows([
    ['Mike', new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26)],
    ['Bob', new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0)],
    ['Alice', new Date(2006, 7, 16),
              new Date(2006, 7, 16),
              new Date(2006, 7, 16)]
  ]);

  // Create three formatters in three styles.
  var formatter_long = new google.visualization.DateFormat({formatType: 'long'});
  var formatter_medium = new google.visualization.DateFormat({formatType: 'medium'});
  var formatter_short = new google.visualization.DateFormat({formatType: 'short'});

  // Reformat our data.
  formatter_long.format(data, 1);
  formatter_medium.format(data,2);
  formatter_short.format(data, 3);

  // Draw our data
  var table = new google.visualization.Table(document.getElementById('dateformat_div'));
  table.draw(data, {showRowNumber: true, width: '100%', height: '100%'});
}

מידע נוסף על תבניות תאריכים

פרטים נוספים על הדפוסים הנתמכים:

הדפוסים דומים לפורמט התאריך והשעה של טיפול נמרץ, אבל התבניות הבאות עדיין לא נתמכות: A e D F g Y u w W. כדי למנוע התנגשות עם דפוסים, כל טקסט מילולי שרוצים שיופיע בפלט צריך להיות מוקף במירכאות בודדות, מלבד הגרשית, שאותה צריך להכפיל: למשל, "K 'o''clock.'".

דפוס	תיאור	פלט לדוגמה
שערים נגד	מגדיר תקופה.	"AD"
yy או yyyy	לשנה.	1996
M	חודש בשנה. לחודש ינואר: M מייצר 1 MM מניבה 01 MMM מפיקים את ינואר MMMM מפיקים את חודש ינואר	"יולי" '07'
יום	יום בחודש. ערכי 'd' נוספים יוסיפו אפסים בתחילת המספר.	‏10
שע'	שעה בקנה מידה של 12 שעות. ערכי 'h' נוספים יוסיפו אפסים בתחילת המספר.	12
H	שעה בקנה מידה של 24 שעות. ערכי Hk נוספים יוסיפו אפסים בתחילת הערך.	0
מ'	דקה בשעה. ערכי 'M' מיותרים יוסיפו אפסים בתחילת המספר.	30
שנ'	שנייה בדקה. ערכי 's נוספים' יוסיפו אפסים בתחילת המספר.	55
S	שניות חלקיות. הערכים המיותרים של 'S' ירווחים בצד ימין עם אפסים.	978
E	היום בשבוע. מעקב אחר פלטים עבור "יום שלישי": E יוצרת T EE או EEE הפקה - חמישי או שלישי EEEE מפיק ביום שלישי	"שלישי" "יום שלישי"
aa	AM/PM	"PM"
k	שעה ביום (1~24). ערכי 'k' נוספים יוסיפו אפסים בתחילת המספר.	24
K	שעה: AM/PM (0~11). ערכי 'k' נוספים יוסיפו אפסים בתחילת המספר.	0
z	אזור זמן. באזור זמן 5, הפונקציה יוצרת 'UTC+5'	'UTC+5'
Z	אזור זמן בפורמט RFC 822. לאזור זמן 5: Z, ZZ, ZZZ תוצרת -0500 ZZZZ ועוד מפיקים את הקוד "GMT -05:00"	-0800 "GMT -05:00"
v	אזור זמן (כללי).	"Etc/GMT-5"
'	מקש Escape לטקסט	'Date='
''	גרש בודד	''yy'

NumberFormat

מתאר את אופן העיצוב של עמודות מספריות. אפשרויות העיצוב כוללות ציון של סמל קידומת (למשל סימן דולר) או סימני פיסוק שישמשו כסמן אלפים.

אפשרויות

NumberFormat תומך באפשרויות הבאות שמועברות ל-constructor:

מקש Option	תיאור
decimalSymbol	תו שישמש כסמן העשרוני. ברירת המחדל היא נקודה (.).
fractionDigits	מספר שמציין כמה ספרות להציג אחרי הנקודה העשרונית. ערך ברירת המחדל הוא 2. אם מציינים יותר ספרות ממה שהמספר מכיל, יופיעו אפסים בערכים הקטנים יותר. ערכים קטועים יעוגלו (5 מעוגלים כלפי מעלה).
groupingSymbol	תו שישמש לקיבוץ ספרות משמאל לעשרונים בקבוצות של שלוש. ברירת המחדל היא פסיק (,).
negativeColor	צבע הטקסט של ערכים שליליים. אין ערך ברירת מחדל. הערכים יכולים להיות כל ערך קביל של צבע HTML, כמו 'red' או '#FF0000'.
negativeParens	ערך בוליאני שבו true מציין שערכים שליליים צריכים להיות מוקפים בסוגריים. ברירת המחדל היא True.
pattern	מחרוזת עיצוב. אם מציינים את הפרמטר הזה, המערכת מתעלמת מכל שאר האפשרויות, מלבד negativeColor. מחרוזת הפורמט היא קבוצת משנה של קבוצת תבניות ה-ICU . לדוגמה, הפונקציה {pattern:'#,###%'} תחזיר את ערכי הפלט '1,000%', '750%' ו-'50%' לערכים 10, 7.5 ו-0.5.
prefix	קידומת מחרוזת עבור הערך, לדוגמה "$".
suffix	סיומת של מחרוזת עבור הערך, לדוגמה '%'.

שיטות

ב-NumberFormat יש תמיכה בשיטות הבאות:

שיטה	תיאור
google.visualization.NumberFormat(options)	בונה. מידע נוסף זמין בקטע האפשרויות שלמעלה.
format(dataTable, columnIndex)	השיטה הרגילה format() להחלת העיצוב על העמודה שצוינה.
formatValue(value)	מחזירה את הערך בפורמט המתאים של ערך נתון. ל-method הזה לא נדרש DataTable.

קוד לדוגמה

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('numberformat_div'));

var formatter = new google.visualization.NumberFormat(
    {prefix: '$', negativeColor: 'red', negativeParens: true});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

PatternFormat

מאפשרת למזג את הערכים של העמודות הייעודיות לעמודה אחת, עם טקסט שרירותי. לדוגמה, אם הייתה לכם עמודה של שם פרטי ועמודה של שם משפחה, אפשר לאכלס עמודה שלישית עם {last name}, {first name}. פורמט העיצוב הזה לא תואם למוסכמות של ה-constructor וה-method format(). הוראות מופיעות בהמשך בקטע 'שיטות'.

שיטות

ב-PatternFormat יש תמיכה בשיטות הבאות:

שיטה	תיאור
google.visualization.PatternFormat(pattern)	בונה. לא לוקח אובייקט אפשרויות. במקום זאת, היא מקבלת פרמטר pattern של מחרוזת. זוהי מחרוזת שמתארת אילו ערכי עמודה צריך להזין בעמודת היעד, יחד עם כל טקסט שרירותי. צריך להטמיע placeholders במחרוזת כדי לציין ערך מעמודה אחרת להטמעה. ערכי ה-placeholder הם {#}, כאשר # הוא האינדקס של עמודת המקור שצריך להשתמש בה. האינדקס הוא אינדקס במערך srcColumnIndices מה-method format() שלמטה. כדי לכלול את התו { או } מילולי, צריך לסמן את בתו בריחה (escape) באופן הבא: \{ או \}. כדי לכלול את הסימן \ מילולי, יש לסמן את התו '\' בתו בריחה (escape). קוד לדוגמה הדוגמה הבאה ממחישה מבנה של תבנית שיוצרת רכיב עוגן, כאשר הרכיב הראשון והשני נלקח מהשיטה format(): var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>');
format(dataTable, srcColumnIndices, opt_dstColumnIndex)	הפעלת הפורמט הרגיל, עם כמה פרמטרים נוספים: dataTable – ה-DataTable שבו יש לפעול. srcColumnIndices - מערך של אינדקס אחד או יותר של עמודה (מבוססת-אפס) שיש לשלוף כמקורות מ-DataTable הבסיסי. הקוד ישמש כמקור נתונים לפרמטר pattern ב-constructor. לא חייבים למיין את מספרי העמודות. opt_dstColumnIndex – [אופציונלי] עמודת היעד שבה צריך להציב את הפלט של המניפולציה לפי pattern. אם לא מציינים זאת, הרכיב הראשון ב-srcColumIndices ישמש כיעד. ניתן לעיין בדוגמאות לעיצוב אחרי הטבלה.

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

Row before formatting (4 columns, last is blank):
John  |  Paul  |  Jones  |  [empty]

var formatter = new google.visualization.PatternFormat("{0} {1} {2}");
formatter.format(data, [0,1,2], 3);
Output:
  John  |  Paul  |  Jones  |  John Paul Jones

var formatter = new google.visualization.PatternFormat("{1}, {0}");
formatter.format(data, [0,2], 3);
Output:
  John  |  Paul  |  Jones  |  Jones, John

קוד לדוגמה

הדוגמה הבאה ממחישה איך לשלב נתונים משתי עמודות כדי ליצור כתובת אימייל. היא משתמשת באובייקט DataView כדי להסתיר את עמודות המקור המקוריות:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Name');
data.addColumn('string', 'Email');
data.addRows([
  ['John Lennon', 'john@beatles.co.uk'],
  ['Paul McCartney', 'paul@beatles.co.uk'],
  ['George Harrison', 'george@beatles.co.uk'],
  ['Ringo Starr', 'ringo@beatles.co.uk']
]);

var table = new google.visualization.Table(document.getElementById('patternformat_div'));

var formatter = new google.visualization.PatternFormat(
    '<a href="mailto:{1}">{0}</a>');
// Apply formatter and set the formatted value of the first column.
formatter.format(data, [0, 1]);

var view = new google.visualization.DataView(data);
view.setColumns([0]); // Create a view with the first column only.

table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

GadgetHelper

שיעור עוזר לפשט את הכתיבה של גאדג'טים שמשתמשים ב-Google Vision API.

יצרן

google.visualization.GadgetHelper()

שיטות

שיטה	הערך המוחזר	תיאור
createQueryFromPrefs(prefs)	google.visualization.Query	סטטי. יוצרים מכונה חדשה של google.visualization.Query ומגדירים את המאפיינים שלה בהתאם לערכים מהעדפות הגאדג'ט. סוג הפרמטר prefs הוא _IG_Prefs ההעדפה _table_query_url משמשת להגדרת כתובת ה-URL של מקור נתוני השאילתה. העדפה _table_query_refresh_interval משמשת להגדרת מרווח הרענון של השאילתה (בשניות).
validateResponse(response)	ערך בוליאני	סטטי. הפרמטר response הוא מסוג google.visualization.QueryResponse. הפונקציה מחזירה את הערך true אם התגובה מכילה נתונים. הפונקציה מחזירה את הערך false אם הפעלת השאילתה נכשלה והתשובה לא מכילה נתונים. אם אירעה שגיאה, השיטה הזו תציג הודעת שגיאה.

מחלקות של שאילתות

האובייקטים הבאים זמינים לשליחת שאילתות לגבי נתונים למקור נתונים חיצוני, כמו גיליונות אלקטרוניים של Google.

• שאילתה – גלישה של בקשת הנתונים היוצאת.
• QueryResponse – טיפול בתגובה ממקור הנתונים.

שאילתה

מייצג שאילתה שנשלחת למקור נתונים.

יצרן

google.visualization.Query(dataSourceUrl, opt_options)

פרמטרים

dataSourceUrl

[חובה, כתובת ה-URL של String] שאליה יש לשלוח את השאילתה. אפשר לעיין במסמכי התיעוד בנושא תרשימים וגיליונות אלקטרוניים ב-Google Sheets.

opt_options

[אופציונלי, אובייקט] מפת אפשרויות לבקשה. הערה: אם ניגשים למקור נתונים מוגבל , לא כדאי להשתמש בפרמטר הזה. אלה המאפיינים הנתמכים:

• sendMethod – [אופציונלי, String] מציין את השיטה שתשמש לשליחת השאילתה. בוחרים אחד מערכי המחרוזת הבאים:
  • 'xhr' – שליחת השאילתה באמצעות XmlHttpRequest.
  • 'scriptInjection' - שליחת השאילתה באמצעות החדרת סקריפט.
  • 'makeRequest' – [זמין רק לגאדג'טים, שהוצאו משימוש] שולחים את השאילתה באמצעות שיטת 'API של גאדג'טים' makeRequest(). אם צוין, צריך לציין גם את makeRequestParams.
  • 'auto' – שימוש בשיטה שצוינה על ידי הפרמטר tqrt של כתובת האתר מכתובת ה-URL של מקור הנתונים. tqrt יכול לקבל את הערכים הבאים: 'xhr', 'scriptInjection' או 'makeRequest'. אם tqrt חסר או מכיל ערך לא חוקי, ברירת המחדל היא 'xhr' לבקשות באותו דומיין ו-'scriptInjection' לבקשות בכמה דומיינים.
• makeRequestParams – [Object] מפת פרמטרים של שאילתת makeRequest(). משתמשים בו ונדרשים רק אם הערך של sendMethod הוא 'makeRequest'.

שיטות

שיטה	הערך המוחזר	תיאור
abort()	אין	הפסקת השליחה האוטומטית של שאילתה שהתחילה ב-setRefreshInterval().
setRefreshInterval(seconds)	אין	הגדרת השאילתה כך שתפעיל אוטומטית את ה-method send בכל משך זמן ספציפי (מספר שניות), החל מהקריאה הבוטה הראשונה ל-send. seconds הוא מספר גדול מאפס או שווה לו. אם משתמשים בשיטה הזו, צריך לקרוא לה לפני הקריאה ל-method send. כדי לבטל את השיטה הזו, אפשר להפעיל אותה שוב עם הערך אפס (ברירת המחדל) או לשלוח קריאה אל abort().
setTimeout(seconds)	אין	מגדירה את מספר השניות להמתנה לתגובה של מקור הנתונים לפני העלאת שגיאה של זמן קצוב לתפוגה. seconds הוא מספר גדול מאפס. הזמן הקצוב לתפוגה שמוגדר כברירת מחדל הוא 30 שניות. אם משתמשים בשיטה הזו, צריך להפעיל אותה לפני קריאה ל-method send.
setQuery(string)	אין	מגדיר את מחרוזת השאילתה. הערך של הפרמטר string צריך להיות שאילתה חוקית. אם משתמשים בשיטה הזו, צריך לקרוא אותה לפני הקריאה ל-method send. מידע נוסף על שפת השאילתות
send(callback)	אין	שליחת השאילתה למקור הנתונים. callback צריך להיות פונקציה שתיקרא כשמקור הנתונים מגיב. פונקציית הקריאה החוזרת תקבל פרמטר יחיד מסוג google.visualization.QueryResponse.

QueryResponse

מייצג את התשובה של הפעלת שאילתה שהתקבלה ממקור הנתונים. מופע של המחלקה הזו מועבר כארגומנט לפונקציית הקריאה החוזרת שהוגדרה כשנשלחה קריאה ל-Query.send.

שיטות

שיטה	הערך המוחזר	תיאור
getDataTable()	DataTable	מחזירה את טבלת הנתונים כפי שהוחזרה על-ידי מקור הנתונים. הפונקציה מחזירה את הערך null אם הפעלת השאילתה נכשלה ולא הוחזרו נתונים.
getDetailedMessage()	מחרוזת	מחזירה הודעת שגיאה מפורטת על שאילתות שנכשלו. אם ההרצה של השאילתה בוצעה בהצלחה, ה-method הזה יחזיר מחרוזת ריקה. ההודעה שמוחזרת היא הודעה שמיועדת למפתחים ויכול להיות שהיא תכלול מידע טכני, למשל, 'Column {salary} לא קיימת'.
getMessage()	מחרוזת	מחזירה הודעת שגיאה קצרה לשאילתות שנכשלו. אם ההרצה של השאילתה בוצעה בהצלחה, ה-method הזה יחזיר מחרוזת ריקה. ההודעה שמוחזרת היא הודעה קצרה שמיועדת למשתמשי הקצה, לדוגמה, 'שאילתה לא חוקית' או 'הגישה נדחתה'.
getReasons()	מערך של מחרוזות	מחזירה מערך של אפס רשומות נוספות. כל רשומה היא מחרוזת קצרה עם קוד שגיאה או אזהרה שהועלה במהלך הרצת השאילתה. קודים אפשריים: access_denied למשתמש אין הרשאות לגשת למקור הנתונים. invalid_query בשאילתה שצוינה יש שגיאת תחביר. data_truncated אחת או יותר משורות הנתונים שתואמות לבחירת השאילתה לא הוחזרה בגלל מגבלות גודל הפלט. (אזהרה). timeout השאילתה לא הגיבה בטווח הזמן הצפוי.
hasWarning()	ערך בוליאני	הפונקציה מחזירה את הערך true אם בהפעלת השאילתה יש הודעות אזהרה.
isError()	ערך בוליאני	הפונקציה מחזירה את הערך true אם הפעלת השאילתה נכשלה והתשובה לא מכילה אף טבלת נתונים. מחזירה <false> אם הפעלת השאילתה הושלמה בהצלחה והתשובה מכילה טבלת נתונים.

הצגת השגיאות

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

כל הפונקציות הן פונקציות סטטיות במרחב השמות google.visualization.errors.

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

תוכלו לראות דוגמה לשגיאה מותאמת אישית ב-Query Wrapper Example.

פעולה	הערך המוחזר	תיאור
addError(container, message, opt_detailedMessage, opt_options)	ערך של מזהה מחרוזת שמזהה את אובייקט השגיאה שנוצר. זהו ערך ייחודי בדף, ואפשר להשתמש בו כדי להסיר את השגיאה או למצוא את הרכיב שמכיל אותה.	הוספה של בלוק תצוגה של שגיאות למרכיב הדף שצוין, עם הטקסט והעיצוב שצוינו. container – רכיב ה-DOM שאליו יש להזין את הודעת השגיאה. אם אי אפשר למצוא את הקונטיינר, הפונקציה תגרור שגיאת JavaScript. message - מחרוזת להצגה. opt_detailedMessage - מחרוזת מפורטת אופציונלית של הודעה. כברירת מחדל, זהו טקסט שמועבר באמצעות העכבר, אבל ניתן לשנות אותו במאפיין opt_options.showInToolTip שמתואר בהמשך. opt_options – אובייקט אופציונלי עם מאפיינים שמגדירים אפשרויות תצוגה שונות להודעה. יש תמיכה באפשרויות הבאות: showInTooltip – ערך בוליאני שבו True מציג את ההודעה המפורטת רק כטקסט של הסבר קצר, ו-false מציג את ההודעה המפורטת בגוף המאגר אחרי ההודעה הקצרה. ערך ברירת המחדל הוא True. type – מחרוזת שמתארת את סוג השגיאה, שקובעת אילו סגנונות CSS צריך להחיל על ההודעה הזו. הערכים הנתמכים הם 'error' ו- 'warning'. ערך ברירת המחדל הוא 'error'. style - מחרוזת סגנון עבור הודעת השגיאה. הסגנון הזה יבטל את כל הסגנונות שהוחלו על סוג האזהרה (opt_options.type). לדוגמה: 'background-color: #33ff99; padding: 2px;' ערך ברירת המחדל הוא מחרוזת ריקה. removable - ערך בוליאני, כאשר True פירושו שניתן לסגור את ההודעה על ידי לחיצה של המשתמש על העכבר. ערך ברירת המחדל הוא False.
addErrorFromQueryResponse(container, response)	ערך מזהה מחרוזת שמזהה את אובייקט השגיאה שנוצר, או null אם התגובה לא ציינה שגיאה. זהו ערך ייחודי בדף, ואפשר להשתמש בו כדי להסיר את השגיאה או למצוא את הרכיב שמכיל אותה.	מעבירים תגובת שאילתה ומאגר תגים של הודעת שגיאה ל-method: אם תגובת השאילתה מציינת שגיאה בשאילתה, תוצג הודעת שגיאה ברכיב הדף שצוין. אם תגובת השאילתה היא null, השיטה תגרור שגיאת JavaScript. מעבירים את QueryResponse שהתקבל ב-handler של השאילתות להודעה הזו כדי להציג שגיאה. יוגדר גם סגנון המסך שמתאים לסוג (שגיאה או אזהרה, בדומה ל-addError(opt_options.type)) container – רכיב ה-DOM שאליו יש להזין את הודעת השגיאה. אם אי אפשר למצוא את הקונטיינר, הפונקציה תגרור שגיאת JavaScript. response – אובייקט QueryResponse שהתקבל ב-handler של השאילתה בתגובה לשאילתה. אם הערך הוא null, השיטה תגרור שגיאת JavaScript.
removeError(id)	בוליאני: True אם השגיאה הוסרה. אחרת, false.	מסירה מהדף את השגיאה שצוינה לפי המזהה. id – מזהה המחרוזת של שגיאה שנוצרה באמצעות addError() או addErrorFromQueryResponse().
removeAll(container)	אין	מסירה את כל בלוקי השגיאות ממאגר שצוין. אם הקונטיינר שצוין לא קיים, תופיע הודעת שגיאה. container – רכיב ה-DOM שמחזיק את מחרוזות השגיאה להסרה. אם הקונטיינר לא נמצא, הפונקציה תגרור שגיאת JavaScript.
getContainer(errorId)	יש להעביר לרכיב DOM שמכיל את השגיאה שצוינה. אם הוא לא נמצא, הוא מכיל את השגיאה null.	מאחזר כינוי לרכיב הקונטיינר שמכיל את השגיאה שצוינה באמצעות errorID. errorId – מזהה מחרוזת של שגיאה שנוצרה באמצעות addError() או addErrorFromQueryResponse().

אירועים

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

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

• google.visualization.events.addListener() ו-google.visualization.events.addOneTimeListener() מאזינים לאירועים.
• google.visualization.events.removeListener() מסיר גורם מאזין קיים
• הפונקציה google.visualization.events.removeAllListeners() מסירה את כל המאזינים של תרשים ספציפי
• google.visualization.events.trigger() מפעיל אירוע.

addListener()

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

google.visualization.events.addListener(source_visualization,
  event_name, handling_function)

source_visualization

כינוי למופע של התרשים להמחשת המקור.

event_name

שם המחרוזת של האירוע שרוצים להאזין לו. הוויזואליזציה צריכה לתעד אילו אירועים היא מפעילה.

handling_function

השם של פונקציית ה-JavaScript המקומית שצריך לקרוא כאשר source_visualization מפעיל את האירוע event_name. פונקציית הטיפול תועבר כפרמטרים של כל הארגומנטים של אירוע.

החזרות

handler של האזנה ל-listener החדש. ניתן להשתמש ב-handler כדי להסיר את ה-listener הזה מאוחר יותר במקרה הצורך, באמצעות קריאה ל-google.visualization.events.removeListener().

דוגמה

דוגמה להרשמה לקבלת אירוע הבחירה

var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler() {
  alert('A table row was selected');
}

addOneTimeListener()

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

דוגמה למקרים שבהם זה שימושי: כל ציור גורמת להשלכה של אירוע ready. אם רוצים שרק ready הראשון יפעיל את הקוד, כדאי להשתמש ב-addOneTimeListener ולא ב-addListener.

removeListener()

צריך להפעיל את השיטה הזו כדי לבטל רישום של event listener קיים.

google.visualization.events.removeListener(listener_handler)

listener_handler

ה-handler של ה-listener שצריך להסיר, כפי שהוא מוחזר על ידי google.visualization.events.addListener().

removeAllListeners()

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

google.visualization.events.removeAllListeners(source_visualization)

source_visualization

כינוי למופע של התרשים להמחשת המקור שממנו צריך להסיר את כל פונקציות ה-event listener.

trigger()

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

google.visualization.events.trigger(source_visualization, event_name,
  event_args)

source_visualization

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

event_name

שם מחרוזת לקריאה לאירוע. אתם יכולים לבחור כל ערך מחרוזת שרוצים.

event_args

[אופציונלי] מפה של צמדי שם/ערך להעברה לשיטה המקבל. לדוגמה: {message: "שלום לך!", Score: 10, name: "Fred"}. אפשר לקבוע ערך null אם אין צורך באירועים. המקלט צריך להיות מוכן לקבלת ערך null עבור הפרמטר הזה.

דוגמה

הנה דוגמה להמחשה חזותית שמקיפה שיטה בשם 'select' כשקוראים ל-method 'לחיצה' שלה. הוא לא מחזיר ערכים.

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;

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

שיטות ומאפיינים סטנדרטיים להמחשה חזותית

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

• בונה
• draw()
• getAction() [אופציונלי]
• getSelection() [אופציונלי]
• removeAction() [אופציונלי]
• setAction() [אופציונלי]
• setSelection() [אופציונלי]

הערה: השיטות האלה נמצאות במרחב השמות של התצוגה החזותית, לא במרחב השמות של google.Visualization.

בונה

ה-constructor צריך לקבל את השם של המחלקה החזותית, ולהחזיר מופע של המחלקה הזו.

visualization_class_name(dom_element)

dom_element

מצביע לרכיב DOM שבו צריך להטמיע את התצוגה החזותית.

דוגמה

var org = new google.visualization.OrgChart(document.getElementById('org_div')); 

draw()

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

draw(data[, options])

נתונים

DataTable או DataView מכילים את הנתונים שישמשו לשרטט התרשים. אין שיטה סטנדרטית לחילוץ DataTable מתרשים.

אפשרויות

[אופציונלי] מפה של צמדי שם/ערך של אפשרויות מותאמות אישית. לדוגמה: גובה ורוחב, צבעי רקע וכתוביות. מסמכי העזרה בנושא תצוגה חזותית צריכים לפרט אילו אפשרויות זמינות, וצריכים לתמוך באפשרויות ברירת מחדל אם לא מציינים את הפרמטר הזה. אפשר להשתמש בתחביר הליטרל של אובייקט JavaScript כדי להעביר במפת אפשרויות: למשל, {x:100, y:200, title:'An Example'}

דוגמה

chart.draw(myData, {width: 400, height: 240, is3D: true, title: 'My Daily Activities'});

getAction()

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

הפונקציה מחזירה את אובייקט הפעולה של ההסבר הקצר עם actionID המבוקש.

דוגמה:

// Returns the action object with the ID 'alertAction'.
chart.getAction('alertAction');

getSelection()

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

selection_array getSelection()

החזרות

selection_array מערך של אובייקטים נבחרים, שכל אחד מהם מתאר רכיב נתונים בטבלה הבסיסית המשמש ליצירת התצוגה החזותית (DataView או DataTable). לכל אובייקט יש את המאפיינים row ו/או column, עם האינדקס של השורה ו/או העמודה של הפריט שנבחר בבסיס DataTable. אם המאפיין row הוא אפס, הבחירה היא עמודה. אם המאפיין column ריק, הבחירה היא שורה. אם שניהם לא אפס, מדובר בפריט נתונים ספציפי. אפשר להפעיל את השיטה DataTable.getValue() כדי לקבל את הערך של הפריט שנבחר. אפשר להעביר את המערך שאוחזר אל setSelection().

דוגמה

function myClickHandler(){
  var selection = myVis.getSelection();
  var message = '';

  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      message += '{row:' + item.row + ',column:' + item.column + '}';
    } else if (item.row != null) {
      message += '{row:' + item.row + '}';
    } else if (item.column != null) {
      message += '{column:' + item.column + '}';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

removeAction()

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

הסרה של אובייקט הפעולה של ההסבר הקצר עם ה-actionID המבוקש מהתרשים.

דוגמה:

// Removes an action from chart with the ID of 'alertAction'.
chart.removeAction('alertAction');

setAction()

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

הגדרת פעולת הסבר קצר שתבוצע כשהמשתמש ילחץ על הטקסט של הפעולה.

setAction(action object)

ה-method setAction מתייחסת לאובייקט כפרמטר הפעולה שלו. האובייקט הזה צריך לציין 3 מאפיינים: id – מזהה הפעולה שהוגדרה, text – הטקסט שצריך להופיע בהסבר הקצר על הפעולה ו-action – הפונקציה שצריכה לפעול כשמשתמש לוחץ על הטקסט של הפעולה.

צריך להגדיר את כל הפעולות של ההסבר הקצר לפני קריאה ל-method של draw() בתרשים.

דוגמה:

// Sets a tooltip action which will pop an alert box on the screen when triggered.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  }
});

ה-method setAction יכולה גם להגדיר שני מאפיינים נוספים: visible ו-enabled. המאפיינים האלה צריכים להיות פונקציות שמחזירות ערכי boolean שמציינים אם הפעולה של ההסבר הקצר תהיה גלויה או מופעלת.

דוגמה:

// The visible/enabled functions can contain any logic to determine their state
// as long as they return boolean values.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  },
  visible: function() {
    return true;
  },
  enabled: function() {
    return true;
  }
});

setSelection()

אפשר לבחור רשומת נתונים בתצוגה החזותית, למשל נקודה בתרשים שטח או עמודה בתרשים עמודות. כשמתבצעת קריאה ל-method הזה, התצוגה החזותית אמורה לציין באופן חזותי מהי הבחירה החדשה. ההטמעה של setSelection() לא אמורה להפעיל אירוע מסוג "select" [בחירה]. ייתכן שהרכיבים החזותיים יתעלמו מחלק מהבחירה. לדוגמה, טבלה שיכולה להציג רק את השורות שנבחרו עשויה להתעלם מאלמנטים של תאים או עמודות בהטמעה של setSelection(), או לבחור את כל השורה.

בכל פעם שבה מתבצעת קריאה לשיטה הזו, הבחירה של כל הפריטים שנבחרו מתבטלת ורשימת הבחירה החדשה שהועברה אמורה לחול. אין דרך מפורשת לבטל את הבחירה בפריטים בודדים. כדי לבטל את הבחירה בפריטים בודדים, קוראים לפונקציה setSelection() כדי שהפריטים יישארו; כדי לבטל את הבחירה בכל הרכיבים, קוראים לפונקציה setSelection(), setSelection(null) או setSelection([]).

setSelection(selection_array)

selection_array

מערך של אובייקטים, שלכל אחד מהם יש מאפיין של שורה או עמודה מספריים. row ו-column הם מספר השורה או העמודה לפי אפס של פריט בטבלת הנתונים לבחירה. כדי לבחור עמודה שלמה, מגדירים את הערך row כ-null. כדי לבחור שורה שלמה, מגדירים את הערך column כ-null. דוגמה: הפונקציה setSelection([{row:0,column:1},{row:1, column:null}]) בוחרת את התא בכתובת (0,1) ואת כל שורה 1.

מגוון שיטות סטטיות

הקטע הזה מכיל שיטות שימושיות שונות שנחשפו במרחב השמות google.visualization.

arrayToDataTable()

השיטה הזו מקבלת מערך דו-ממדי וממירה אותו ל-DataTable.

סוגי הנתונים של העמודות נקבעים באופן אוטומטי לפי הנתונים שסופקו. אפשר לציין גם את סוגי הנתונים של העמודות באמצעות הסימון המילולי של האובייקט בשורה הראשונה (שורת כותרת העמודה) של המערך (כלומר {label: 'Start Date', type: 'date'}). אפשר להשתמש גם בתפקידי נתונים אופציונליים, אבל צריך להגדיר אותם באופן מפורש באמצעות סימון מילולי של האובייקט. לכל תא אפשר להשתמש גם בייצוג מילולי של אובייקטים, כדי להגדיר את האובייקטים של התא.

תחביר

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

מערך דו-ממדי, שבו כל שורה מייצגת שורה בטבלת הנתונים. אם הערך של opt_firstRowIsData כ-False (ברירת המחדל), השורה הראשונה תתפרש כתוויות של כותרת. סוגי הנתונים של כל עמודה מפורשים באופן אוטומטי מהנתונים הנתונים. אם אין ערך בתא, צריך לציין ערך של null או ערך ריק, לפי הצורך.

opt_firstRowIsData

האם בשורה הראשונה מוגדרת שורת כותרת או לא. אם True, המערכת מניחה שכל השורות הן נתונים. אם הערך הוא False, ההנחה היא שהשורה הראשונה היא שורת הכותרת, והערכים מוקצים כתוויות של עמודות. ברירת המחדל היא False.

החזרות

DataTable חדש.

דוגמאות

הקוד הבא מדגים שלוש דרכים ליצירת אותו אובייקט DataTable:

// Version 1: arrayToDataTable method
var data2 = google.visualization.arrayToDataTable([
  [{label: 'Country', type: 'string'},
   {label: 'Population', type: 'number'},
   {label: 'Area', type: 'number'},
   {type: 'string', role: 'annotation'}],
  ['CN', 1324, 9640821, 'Annotated'],
  ['IN', 1133, 3287263, 'Annotated'],
  ['US', 304, 9629091, 'Annotated'],
  ['ID', 232, 1904569, 'Annotated'],
  ['BR', 187, 8514877, 'Annotated']
]);

// Version 2: DataTable.addRows
var data3 = new google.visualization.DataTable();
data3.addColumn('string','Country');
data3.addColumn('number','Population');
data3.addColumn('number','Area');
data3.addRows([
  ['CN', 1324, 9640821],
  ['IN', 1133, 3287263],
  ['US', 304, 9629091],
  ['ID', 232, 1904569],
  ['BR', 187, 8514877]
]);

// Version 3: DataTable.setValue
var data = new google.visualization.DataTable();
data.addColumn('string','Country');
data.addColumn('number', 'Population');
data.addColumn('number', 'Area');
data.addRows(5);
data.setValue(0, 0, 'CN');
data.setValue(0, 1, 1324);
data.setValue(0, 2, 9640821);
data.setValue(1, 0, 'IN');
data.setValue(1, 1, 1133);
data.setValue(1, 2, 3287263);
data.setValue(2, 0, 'US');
data.setValue(2, 1, 304);
data.setValue(2, 2, 9629091);
data.setValue(3, 0, 'ID');
data.setValue(3, 1, 232);
data.setValue(3, 2, 1904569);
data.setValue(4, 0, 'BR');
data.setValue(4, 1, 187);
data.setValue(4, 2, 8514877);

drawChart()

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

תחביר

google.visualization.drawChart(chart_JSON_or_object)

chart_JSON_or_object

מחרוזת מילולית של JSON או אובייקט JavaScript עם המאפיינים הבאים (תלוי אותיות רישיות):

מאפיין (property)	סוג	חובה	ברירת המחדל	תיאור
chartType	מחרוזת	חובה	אין	שם הכיתה של התצוגה החזותית. אפשר להשמיט את שם החבילה google.visualization בתרשימים של Google. אם ספריית ההמחשה המתאימה עדיין לא נטענה, השיטה הזו תטען את הספרייה בשבילכם אם מדובר בתצוגה חזותית של Google. עליכם לטעון תצוגות חזותיות של צד שלישי באופן מפורש. דוגמאות: Table, PieChart, example.com.CrazyChart.
containerId	מחרוזת	חובה	אין	המזהה של רכיב ה-DOM בדף שלכם שיארח את התצוגה החזותית.
אפשרויות	אובייקט	אופציונלי	אין	אובייקט שמתאר את האפשרויות הוויזואליות. אפשר להשתמש בסימון מילולי של JavaScript או לספק כינוי לאובייקט. לדוגמה: "options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
dataTable	אובייקט	אופציונלי	אין	DataTable שמשמש לאכלוס התצוגה החזותית. זו יכולה להיות ייצוג מילולי של מחרוזת JSON של DataTable, כפי שמתואר למעלה, או כינוי לאובייקט google.visualization.DataTable מאוכלס, או מערך דו-ממדי כמו זה שמקובל ב- arrayToDataTable(opt_firstRowIsData=false) . עליך לציין את המאפיין הזה או את המאפיין dataSourceUrl.
dataSourceUrl	מחרוזת	אופציונלי	אין	שאילתה של מקור נתונים לאכלוס נתוני התרשים (לדוגמה, Google Sheets). צריך לציין את המאפיין הזה או את המאפיין dataTable.
שאילתה	מחרוזת	אופציונלי	אין	אם אתם מציינים dataSourceUrl, אפשר לציין מחרוזת שאילתה דמוית SQL באמצעות שפת השאילתה להמחשת הנתונים כדי לסנן או לשנות את הנתונים.
refreshInterval	מספרים	אופציונלי	אין	באיזו תדירות, בשניות, התצוגה החזותית צריכה לרענן את מקור השאילתה. צריך להשתמש באפשרות הזו רק כשמציינים את הערך dataSourceUrl.
צפייה	אובייקט או מערך	אופציונלי	אין	מגדיר אובייקט מאתחל DataView, שמשמש כמסנן של נתוני הבסיס, כפי שמוגדר באמצעות הפרמטר dataTable או הפרמטר dataSourceUrl. אפשר להעביר במחרוזת או באובייקט מאתחל DataView, כמו זה שמוחזר על ידי dataview.toJSON(). דוגמה: "view": {"columns": [1, 2]} אפשר גם להעביר במערך של אובייקטים של אתחול DataView. במקרה כזה, ה-DataView הראשון במערך מוחל על נתוני הבסיס כדי ליצור טבלת נתונים חדשה, וה-DataView השני מוחל על טבלת הנתונים שמתקבלת מהיישום של DataView הראשון, וכן הלאה.

דוגמאות

יצירת תרשים טבלה שמבוסס על מקור נתונים של גיליון אלקטרוני, שכוללת את השאילתה SELECT A,D WHERE D > 100 ORDER BY D

<script type="text/javascript">
  google.charts.load('current');  // Note: No need to specify chart packages.
  function drawVisualization() {
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",
      "query":"SELECT A,D WHERE D > 100 ORDER BY D",
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true
      }
   });
 }
google.charts.setOnLoadCallback(drawVisualization);
</script>

בדוגמה הבאה נוצרת את אותה הטבלה, אבל נוצר DataTable באופן מקומי:

<script type='text/javascript'>
  google.charts.load('current');
  function drawVisualization() {
    var dataTable = [
      ["Country", "Population Density"],
      ["Indonesia", 117],
      ["China", 137],
      ["Nigeria", 142],
      ["Pakistan", 198],
      ["India", 336],
      ["Japan", 339],
      ["Bangladesh", 1045]
    ];
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataTable": dataTable,
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true,
      }
    });
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

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

<script type="text/javascript">
  google.charts.load('current');
  var myStoredString = '{"containerId": "visualization_div",' +
    '"dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",' +
    '"query":"SELECT A,D WHERE D > 100 ORDER BY D",' +
    '"refreshInterval": 5,' +
    '"chartType": "Table",' +
    '"options": {' +
    '   "alternatingRowStyle": true,' +
    '   "showRowNumber" : true' +
    '}' +
  '}';
  function drawVisualization() {
    google.visualization.drawChart(myStoredString);
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

drawToolbar()

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