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

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

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

1. סיווג DataTable
2. סיווג DataView
3. סיווגChartWrapper
4. מחלקה של ChartEditor
5. שיטות לטיפול בנתונים
   1. group()
   2. join()
6. מעצבי עיצוב
   1. ArrowFormat
   2. BarFormat
   3. ColorFormat
   4. DateFormat
   5. NumberFormat
   6. PatternFormat
7. כיתת GuardHelper
8. מחלקות של שאילתות
   1. שאילתה
   2. QueryResponse
9. סיווג תצוגה של שגיאה
10. אירועים
    1. google.visualization.events.addListener()
    2. google.visualization.events.addOneTimeListener()
    3. google.visualization.events.removeListener()
    4. google.visualization.events.removeAllListeners()
    5. google.visualization.events.trigger()
11. שיטות ומאפיינים סטנדרטיים להמחשה חזותית
    1. בונה
    2. draw()
    3. getAction()
    4. getSelection()
    5. removeAction()
    6. setAction()
    7. setSelection()
12. מגוון שיטות סטטיות
    1. arrayToDataTable()
    2. drawChart()
    3. drawToolbar()

הערה לגבי מערכים

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

data = ['a','b','c', ,]; // BAD
data = ['a','b','c'];   // OK
data = ['a','b', ,'d']; // Also OK. The third value is undefined.

סיווג 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'}]
]);

האם צריך ליצור את ה-DataTable ב-JavaScript או בסימון מילולי של האובייקטים?

אפשר ליצור DataTable על ידי שליחת קריאה ל-constructor ללא פרמטרים ולאחר מכן באמצעות הוספת ערכים באמצעות קריאה ל-methods addColumn()/ addRows() שמפורטות בהמשך, או על ידי העברת אובייקט מילולי של JavaScript כדי לאתחל אותו. שתי השיטות מתוארות בהמשך. באיזה מהם כדאי להשתמש?

• יצירה ואכלוס של טבלה ב-JavaScript באמצעות קריאה ל-addColumn(), addRow() ו-addRows() הם קוד קריא מאוד. השיטה הזו שימושית כשמזינים קוד באופן ידני. הפעולה הזו איטית יותר משימוש בסימון מילולי של אובייקטים (כפי שמתואר בהמשך), אבל בטבלאות קטנות יותר (למשל, 1,000 תאים), סביר להניח שלא יהיה הבדל משמעותי.
• הצהרה ישירה של האובייקט DataTable באמצעות סימון מילולי של אובייקט מהירה משמעותית בטבלאות גדולות. עם זאת, התחביר עשוי להיות מסובך. כדאי להשתמש בו אם אפשר ליצור בקוד את התחביר המילולי של האובייקט, מה שמפחית את הסיכוי לשגיאות.

 

שיטות

שיטה	הערך המוחזר	תיאור
addColumn(type, opt_label, opt_id) או addColumn(description_object)	מספרים	הפונקציה מוסיפה עמודה חדשה לטבלת הנתונים ומחזירה את האינדקס של העמודה החדשה. לכל התאים בעמודה החדשה מוקצה ערך null. לשיטה הזו יש שתי חתימות: החתימה הראשונה כוללת את הפרמטרים הבאים: type - מחרוזת עם סוג הנתונים של ערכי העמודה. הסוג יכול להיות אחת מהאפשרויות הבאות: 'string', 'number', 'boolean', 'date', 'datetime', או 'timeofday'. opt_label - [אופציונלי] מחרוזת עם התווית של העמודה. תווית העמודה מוצגת בדרך כלל כחלק מההמחשה החזותית, למשל ככותרת עמודה בטבלה או כתווית מקרא בתרשים עוגה. אם לא תציינו ערך, תוקצה מחרוזת ריקה. opt_id – [אופציונלי] מחרוזת עם מזהה ייחודי לעמודה. אם לא תציינו ערך, תוקצה מחרוזת ריקה. החתימה השנייה כוללת פרמטר אובייקט יחיד עם המשתמשים הבאים: type – מחרוזת שמתארת את סוג הנתונים של העמודה. ערכים זהים לאלה של type שלמעלה. label - [אופציונלי, מחרוזת] תווית לעמודה. id – [אופציונלי, מחרוזת] מזהה של העמודה. role - [אופציונלי, מחרוזת] תפקיד לעמודה. pattern – [אופציונלי, מחרוזת] מחרוזת בפורמט מספר (או תאריך) שמציינת איך להציג את הערך בעמודה. למידע נוסף: getColumnId, getColumnLabel, getColumnType, insertColumn, getColumnRole
addRow(opt_cellArray)	מספרים	הפונקציה מוסיפה שורה חדשה לטבלת הנתונים ומחזירה את האינדקס של השורה החדשה. opt_cellArray [אופציונלי] אובייקט שורה, בסימון JavaScript, שמציין את הנתונים של השורה החדשה. אם הפרמטר לא כלול, השיטה הזו פשוט תוסיף שורה חדשה וריקה בסוף הטבלה. הפרמטר הזה הוא מערך של ערכי תאים: אם רוצים לציין רק ערך בתא, צריך רק לציין את הערך בתא (למשל 55 או hello'); אם רוצים לציין ערך בפורמט ו/או מאפיינים לתא, אפשר להשתמש באובייקט של תא (למשל, {v:55, f:'Fifty-five'}). אפשר לשלב ערכים פשוטים ואובייקטים של תאים באותה קריאה ל-method). צריך להשתמש ב-null או ברשומת מערך ריקה כדי תא ריק. לדוגמה: 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.
addRows(numOrArray)	מספרים	מוסיף שורות חדשות לטבלת הנתונים, ומחזיר את האינדקס של השורה האחרונה שנוספה. אפשר לקרוא ל-method הזה כדי ליצור שורות ריקות חדשות או עם נתונים שמשמשים לאכלוס השורות, כפי שמתואר בהמשך. numOrArray – מספר או מערך: מספר – מספר שמציין כמה שורות חדשות ולא מאוכלסות יש להוסיף. Array – מערך של אובייקטים מסוג row שמשמשים לאכלוס קבוצה של שורות חדשות. כל שורה היא אובייקט כפי שמתואר ב-addRow(). צריך להשתמש ב- null או ברשומת מערך ריקה כדי תא ריק. דוגמה: 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. ]); למידע נוסף: insertRows
clone()	DataTable	מחזירה שכפול של טבלת הנתונים. התוצאה היא עותק עומק של טבלת הנתונים, מלבד מאפייני תא, מאפייני שורה, מאפייני טבלה ומאפייני עמודה, שהם עותקים רדודים. כלומר, מאפיינים לא פרימיטיביים מועתקים לפי הפניה, אבל המאפיינים הראשוניים מועתקים לפי ערך.
getColumnId(columnIndex)	מחרוזת	מחזירה את המזהה של עמודה נתונה שצוינה על ידי אינדקס העמודה בטבלה הבסיסית. בטבלאות נתונים שמאוחזרות באמצעות שאילתות, מזהה העמודה מוגדר על ידי מקור הנתונים, ואפשר להשתמש בו כדי להפנות לעמודות כשמשתמשים בשפת השאילתה. למידע נוסף: Query.setQuery
getColumnIndex(columnIdentifier)	מחרוזת, מספר	מחזירה את האינדקס של עמודה נתונה שצוינה על ידי אינדקס העמודה, מזהה או תווית אם היא קיימת בטבלה הזו. אחרת, -1. כשהערך בשדה columnIdentifier הוא מחרוזת, הוא משמש למציאת העמודה לפי המזהה שלה ואחר כך לפי התווית שלה. למידע נוסף: getColumnId, getColumnLabel
getColumnLabel(columnIndex)	מחרוזת	מחזירה את התווית של עמודה נתונה שצוינה על ידי אינדקס העמודה בטבלה הבסיסית. בדרך כלל, תווית העמודה מוצגת כחלק מהתצוגה החזותית. לדוגמה, ניתן להציג את תווית העמודה ככותרת עמודה בטבלה או כתווית מקרא בתרשים עוגה. לטבלאות נתונים שמאוחזרות באמצעות שאילתות, תווית העמודה מוגדרת על ידי מקור הנתונים, או על ידי המשפט label של שפת השאילתה. למידע נוסף: setColumnLabel
getColumnPattern(columnIndex)	מחרוזת	מחזירה את דפוס העיצוב המשמש לעיצוב הערכים של העמודה שצוינה. columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). בטבלאות נתונים שמאוחזרות באמצעות שאילתות, דפוס העמודה נקבע על ידי מקור הנתונים, או על ידי המשפט format של שפת השאילתה. דוגמה לדפוס: '#,##0.00'. מידע נוסף על דפוסים זמין בחומר העזר בנושא שפת שאילתות.
getColumnProperties(columnIndex)	אובייקט	מחזירה מפה של כל המאפיינים עבור העמודה שצוינה. שימו לב שאובייקט המאפיינים מוחזר באמצעות הפניה, לכן שינוי הערכים באובייקט המאוחזר משנה אותם ב-DataTable. columnIndex הוא האינדקס המספרי של העמודה שעבורה רוצים לאחזר את המאפיינים.
getColumnProperty(columnIndex, name)	אוטומטית	מחזירה את הערך של מאפיין בעל שם, או null אם לא הוגדר מאפיין כזה בעמודה שצוינה. סוג ההחזרה משתנה בהתאם לנכס. columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). name הוא שם הנכס, כמחרוזת. מידע נוסף: setColumnProperty setColumnProperties
getColumnRange(columnIndex)	אובייקט	מחזירה את הערכים המינימליים והמקסימליים של ערכים בעמודה שצוינה. לאובייקט שמוחזר יש את המאפיינים min ו-max. אם אין בטווח ערכים, min ו-max יכילו null. columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שהוחזרו על ידי השיטה getNumberOfColumns().
getColumnRole(columnIndex)	מחרוזת	הפונקציה מחזירה את role מהעמודה שצוינה.
getColumnType(columnIndex)	מחרוזת	מחזירה את הסוג של עמודה נתונה שצוינה על ידי אינדקס העמודה. columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). סוג העמודה המוחזר יכול להיות אחת מהאפשרויות הבאות: 'string', 'number', 'boolean', 'date', 'datetime', ו-'timeofday'
getDistinctValues(columnIndex)	מערך של אובייקטים	מחזירה את הערכים הייחודיים בעמודה מסוימת, בסדר עולה. columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). סוג האובייקטים שמוחזרים זהה לסוג האובייקטים שמוחזרים באמצעות ה-method getValue.
getFilteredRows(filters)	מערך של אובייקטים	מחזירה את אינדקסי השורות עבור שורות שתואמות לכל המסננים הנתונים. האינדקסים מוחזרים בסדר עולה. הפלט של השיטה הזו יכול לשמש כקלט ל-DataView.setRows() כדי לשנות את קבוצת השורות שמופיעה בתצוגה החזותית. filters - מערך אובייקטים שמתארים ערך תא קביל. בשיטה הזו, אינדקס השורה מוחזר אם הוא תואם לכל המסננים הנתונים. כל מסנן הוא אובייקט עם מאפיין column מספרי שמציין את האינדקס של העמודה בשורה שצריך לבדוק, ועוד אחת מהאפשרויות הבאות: מאפיין value עם ערך שחייב להיות זהה בדיוק לתא בעמודה שצוינה. הערך צריך להיות מאותו הסוג כמו העמודה; או אחד מהמאפיינים הבאים או שניהם, מאותו הסוג של העמודה המסוננת: minValue – ערך מינימלי עבור התא. ערך התא בעמודה שצוין חייב להיות גדול מהערך הזה או שווה לו. maxValue – הערך המקסימלי של התא. ערך התא בעמודה שצוין חייב להיות קטן מהערך הזה או שווה לו. ערך null או ערך לא מוגדר של minValue (או maxValue) פירושו שהגבול התחתון (או העליון) של הטווח לא ייאכף. מאפיין אופציונלי נוסף, test, מציין פונקציה שצריך לשלב עם סינון ערכים או טווח. הפונקציה מופעלת עם ערך התא, האינדקס של השורה והעמודה וגם טבלת הנתונים. אם צריך להחריג את השורה מהתוצאה, הפונקציה צריכה להחזיר את הערך False. דוגמה: getFilteredRows([{column: 3, value: 42}, {column: 2, minValue: 'bar', maxValue: 'foo'}, {column: 1, test: (value, rowId, columnId, datatable) => { return value == "baz"; }}]) מחזירה מערך שמכיל, בסדר עולה, את האינדקסים של כל השורות שבהן העמודה הרביעית (אינדקס 3) היא בדיוק 42, והעמודה השלישית (אינדקס עמודה 2) היא בין 'bar' ל-'foo' (כולל).
getFormattedValue(rowIndex, columnIndex)	מחרוזת	מחזירה את הערך המפורמט של התא באינדקסים של השורה והעמודה הנתונים. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). ColumnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). מידע נוסף על עיצוב הערכים של העמודות מופיע במאמרי העזרה לשפת השאילתות. למידע נוסף: setFormattedValue
getNumberOfColumns()	מספרים	מחזירה את מספר העמודות בטבלה.
getNumberOfRows()	מספרים	מחזירה את מספר השורות בטבלה.
getProperties(rowIndex, columnIndex)	אובייקט	מחזירה מפה של כל המאפיינים בתא שצוין. שימו לב שאובייקט המאפיינים מוחזר באמצעות הפניה, לכן שינוי הערכים באובייקט המאוחזר משנה אותם ב-DataTable. rowIndex הוא אינדקס השורות של התא. columnIndex הוא אינדקס העמודות של התא.
getProperty(rowIndex, columnIndex, name)	אוטומטית	מחזירה את הערך של מאפיין בעל שם, או null אם לא הוגדר מאפיין כזה בתא שצוין. סוג ההחזרה משתנה בהתאם לנכס. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). name היא מחרוזת עם שם הנכס. למידע נוסף: setCell setProperties setProperty
getRowProperties(rowIndex)	אובייקט	מחזירה מפה של כל המאפיינים בשורה שצוינה. שימו לב שאובייקט המאפיינים מוחזר באמצעות הפניה, לכן שינוי הערכים באובייקט המאוחזר משנה אותם ב-DataTable. rowIndex הוא האינדקס של השורה שעבורה יש לאחזר את המאפיינים.
getRowProperty(rowIndex, name)	אוטומטית	הפונקציה מחזירה את הערך של מאפיין בעל שם, או null אם לא הוגדר מאפיין כזה בשורה שצוינה. סוג ההחזרה משתנה בהתאם לנכס. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). name היא מחרוזת עם שם הנכס. מידע נוסף: setRowProperty setRowProperties
getSortedRows(sortColumns)	מערך של מספרים	מחזירה גרסה ממוינת של הטבלה בלי לשנות את הסדר של הנתונים הבסיסיים. כדי למיין באופן סופי את הנתונים המקוריים, צריך לקרוא לפונקציה sort(). אפשר להגדיר את המיון בכמה דרכים, בהתאם לסוג שמעבירים לפרמטר sortColumns: מספר יחיד מציין את האינדקס של העמודה שלפיה רוצים למיין. המיון יופיע בסדר עולה. דוגמה: הפונקציה sortColumns(3) תמיין לפי העמודה הרביעית, בסדר עולה. אובייקט יחיד שמכיל את מספר האינדקס של העמודות שלפיו יתבצע מיון, ומאפיין בוליאני אופציונלי desc. אם הערך של desc מוגדר כ-True, העמודה הספציפית ממוינת בסדר יורד. אחרת, המיון יהיה בסדר עולה. דוגמאות: הפונקציה sortColumns({column: 3}) תמיין לפי העמודה הרביעית, בסדר עולה; העמודה sortColumns({column: 3, desc: true}) תמיין לפי העמודה הרביעית, בסדר יורד. מערך מספרים של האינדקסים של העמודות שלפיהם יתבצע מיון. המספר הראשון הוא העמודה הראשית שלפיה צריך למיין, המספר השני הוא העמודה המשנית וכן הלאה. כלומר, כששני ערכים בעמודה הראשונה זהים, מתבצעת השוואה בין הערכים בעמודה הבאה וכן הלאה. דוגמה: הערך sortColumns([3, 1, 6]) ימיין קודם לפי העמודה הרביעית (בסדר עולה), ואז לפי העמודה השנייה (בסדר עולה) ואז לפי העמודה השביעית (בסדר עולה). מערך של אובייקטים, כל אחד עם מספר האינדקס של העמודה שלפיה יתבצע מיון, ומאפיין בוליאני אופציונלי desc. אם מגדירים את הערך desc כ-True, העמודה הספציפית ממוינת בסדר יורד (ברירת המחדל היא בסדר עולה). האובייקט הראשון הוא העמודה הראשית שלפיה צריך למיין, האובייקט השני הוא המשני וכן הלאה. כלומר, כששני ערכים בעמודה הראשונה שווים, מתבצעת השוואה בין הערכים בעמודה הבאה וכן הלאה. דוגמה: הערך sortColumn([{column: 3}, {column: 1, desc: true}, {column: 6, desc: true}]) יבצע קודם מיון לפי העמודה הרביעית (בסדר עולה), ולאחר מכן לפי עמודה 2 בסדר יורד, ולאחר מכן לפי עמודה 7 בסדר יורד. הערך המוחזר הוא מערך של מספרים, כל מספר הוא אינדקס של שורה DataTable. איטרציה של השורות DataTable לפי הסדר של המערך המוחזר, תגרור שורות לפי sortColumns שצוין. הפלט יכול לשמש כקלט ל-DataView.setRows() כדי לשנות במהירות את קבוצת השורות שמוצגת בתצוגה חזותית. חשוב לשים לב שהמיון חייב להיות יציב: כלומר, אם ממיינים לפי ערכים שווים של שתי שורות, אותו מיון יחזיר את השורות באותו סדר בכל פעם. מידע נוסף: מיון דוגמה: כדי לחזור על שורות שמסודרים לפי העמודה השלישית, משתמשים: var rowInds = data.getSortedRows([{column: 2}]); for (var i = 0; i < rowInds.length; i++) { var v = data.getValue(rowInds[i], 2); }
getTableProperties	אובייקט	מחזירה מפה של כל המאפיינים עבור הטבלה.
getTableProperty(name)	אוטומטית	מחזירה את הערך של מאפיין בעל שם, או null אם לא הוגדר מאפיין כזה לטבלה. סוג ההחזרה משתנה בהתאם לנכס. name היא מחרוזת עם שם הנכס. מידע נוסף: setTableProperties setTableProperty
getValue(rowIndex, columnIndex)	אובייקט	מחזירה את הערך של התא באינדקסים של השורה והעמודה הנתונים. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). הסוג של הערך המוחזר תלוי בסוג העמודה (ראו getColumnType): אם סוג העמודה הוא 'string', הערך הוא מחרוזת. אם סוג העמודה הוא 'מספר', הערך הוא מספר. אם סוג העמודה הוא 'בוליאני', הערך הוא בוליאני. אם סוג העמודה הוא תאריך או תאריך ושעה, הערך הוא האובייקט Date. אם סוג העמודה הוא 'timeofday', הערך הוא מערך של ארבעה מספרים: [hour, דקות, שניות, אלפיות שנייה]. אם ערך התא הוא ערך null, הפונקציה מחזירה את הערך null.
insertColumn(columnIndex, type [,label [,id]])	אין	מוסיפה עמודה חדשה לטבלת הנתונים, באינדקס שצוין. כל העמודות הקיימות באינדקס שצוין או אחריו יועברו לאינדקס גבוה יותר. columnIndex הוא מספר עם האינדקס הנדרש של העמודה החדשה. הערך type צריך להיות מחרוזת עם סוג הנתונים של ערכי העמודה. הסוג יכול להיות אחת מהאפשרויות הבאות: 'string', 'number', 'boolean', 'date', 'datetime', ו-'timeofday'. הערך label צריך להיות מחרוזת עם התווית של העמודה. תווית העמודה מוצגת בדרך כלל כחלק מההמחשה החזותית, למשל ככותרת עמודה בטבלה או כתווית מקרא בתרשים עוגה. אם לא תציינו ערך, תוקצה מחרוזת ריקה. הערך id צריך להיות מחרוזת עם מזהה ייחודי לעמודה. אם לא תציינו ערך, תוקצה מחרוזת ריקה. למידע נוסף: addColumn
insertRows(rowIndex, numberOrArray)	אין	מוסיפים את מספר השורות שצוין באינדקס השורות שצוין. rowIndex הוא מספר האינדקס שבו מוסיפים את השורות החדשות. השורות יתווספו, החל ממספר האינדקס שצוין. numberOrArray הוא מספר שורות חדשות וריקות להוספה, או מערך של שורה מאוכלסת אחת או יותר להוספה לאינדקס. לתחביר להוספת מערך של אובייקטים מסוג שורה ראו addRows(). למידע נוסף: addRows
removeColumn(columnIndex)	אין	מסיר את העמודה באינדקס שצוין. columnIndex צריך להיות מספר עם אינדקס עמודה חוקי. למידע נוסף: removeColumns
removeColumns(columnIndex, numberOfColumns)	אין	מסירה את מספר העמודות שצוין, החל מהעמודה באינדקס שצוין. numberOfColumns הוא מספר העמודות להסרה. columnIndex צריך להיות מספר עם אינדקס עמודה חוקי. למידע נוסף: removeColumn
removeRow(rowIndex)	אין	מסיר את השורה באינדקס שצוין. rowIndex צריך להיות מספר עם אינדקס שורה חוקי. למידע נוסף: removeRows
removeRows(rowIndex, numberOfRows)	אין	הפונקציה מסירה את מספר השורות שצוין, החל מהשורה באינדקס שצוין. numberOfRows הוא מספר השורות שרוצים להסיר. rowIndex צריך להיות מספר עם אינדקס שורה חוקי. למידע נוסף: removeRow
setCell(rowIndex, columnIndex [, value [, formattedValue [, properties]]])	אין	מגדיר את הערך, הערך בפורמט ו/או המאפיינים של תא. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). value [אופציונלי] הוא הערך שהוקצה לתא שצוין. כדי למנוע החלפה של הערך הזה, צריך להגדיר את הפרמטר ל-undefined; כדי לנקות את הערך הזה, צריך להגדיר אותו ל-null. הסוג של הערך תלוי בסוג העמודה (ראו getColumnType()): אם סוג העמודה הוא 'string', הערך צריך להיות מחרוזת. אם סוג העמודה הוא 'מספר', הערך צריך להיות מספר. אם סוג העמודה הוא 'בוליאני', הערך צריך להיות בוליאני. אם סוג העמודה הוא תאריך או תאריך ושעה, הערך צריך להיות אובייקט Date. אם סוג העמודה הוא 'timeofday', הערך צריך להיות מערך של ארבעה מספרים: [hour, דקות, שניות, אלפיות שנייה]. formattedValue [אופציונלי] היא מחרוזת עם הערך בפורמט של מחרוזת. כדי למנוע החלפה של הערך הזה, צריך להגדיר את הפרמטר הזה ל-undefined; כדי לנקות את הערך הזה ושה-API יחיל את עיצוב ברירת המחדל על value לפי הצורך, צריך להגדיר אותו כ-null. כדי להגדיר באופן מפורש ערך ריק בפורמט, צריך להגדיר אותו כמחרוזת ריקה. בדרך כלל משתמשים בערך בפורמט של המחשות ויזואליות כדי להציג תוויות של ערכים. לדוגמה, הערך בפורמט יכול להופיע כטקסט של תווית בתוך תרשים עוגה. properties [אופציונלי] הוא Object (מפת שם/ערך) עם מאפיינים נוספים לתא הזה. כדי למנוע החלפה של הערך הזה, צריך להגדיר את הפרמטר ל-undefined. כדי לנקות את הערך הזה, צריך להגדיר אותו ל-null. חלק מהרכיבים החזותיים תומכים במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או את ההתנהגות שלהם. במסמכי התיעוד של התצוגה החזותית מפורט אילו מאפיינים נתמכים. מידע נוסף מופיע כאן: setValue(), setFormattedValue(), setProperty(), setProperties().
setColumnLabel(columnIndex, label)	אין	מגדיר את התווית של עמודה. columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). label הוא מחרוזת עם התווית להקצאה לעמודה. התווית של העמודה מוצגת בדרך כלל כחלק מהתצוגה החזותית. לדוגמה, תווית העמודה יכולה להופיע ככותרת עמודה בטבלה או כתווית מקרא בתרשים עוגה. למידע נוסף: getColumnLabel
setColumnProperty(columnIndex, name, value)	אין	מגדיר מאפיין של עמודה אחת. חלק מהרכיבים החזותיים תומכים במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או את ההתנהגות שלהם. במסמכי התיעוד של התצוגה החזותית מפורטות המאפיינים הנתמכים. columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). name היא מחרוזת עם שם הנכס. value הוא ערך מכל סוג שצריך להקצות למאפיין בעל השם שצוין בעמודה שצוינה. למידע נוסף:setColumnProperties getColumnProperty
setColumnProperties(columnIndex, properties)	אין	מגדירה כמה מאפיינים של עמודות. חלק מהרכיבים החזותיים תומכים במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או את ההתנהגות שלהם. במסמכי התיעוד של התצוגה החזותית מפורטות המאפיינים הנתמכים. columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). properties הוא Object (מפת שם/ערכים) עם מאפיינים נוספים לעמודה הזו. אם מציינים את null, כל המאפיינים הנוספים של העמודה יוסרו. מידע נוסף: setColumnProperty getColumnProperty
setFormattedValue(rowIndex, columnIndex, formattedValue)	אין	הגדרת הערך בפורמט של תא. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). formattedValue היא מחרוזת עם הערך בפורמט לתצוגה. כדי לנקות את הערך הזה ושה-API יחיל את עיצוב ברירת המחדל על ערך התא לפי הצורך, מגדירים אותו formattedValue null. כדי להגדיר במפורש ערך ריק בפורמט, מגדירים אותו למחרוזת ריקה. למידע נוסף: getFormattedValue
setProperty(rowIndex, columnIndex, name, value)	אין	מגדיר מאפיין תא. בחלק מהרכיבים החזותיים יש תמיכה במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או את ההתנהגות שלהם. במסמכי התיעוד של התצוגה החזותית מפורטות המאפיינים הנתמכים. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). name היא מחרוזת עם שם הנכס. value הוא ערך מכל סוג שצריך להקצות למאפיין בעל השם שצוין בתא שצוין. מידע נוסף: setCell setProperties getProperty
setProperties(rowIndex, columnIndex, properties)	אין	מגדירה מאפייני תאים מרובים. חלק מהרכיבים החזותיים תומכים במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או את ההתנהגות שלהם. במסמכי התיעוד של התצוגה החזותית מפורטות המאפיינים הנתמכים. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). properties הוא Object (מפת שם/ערך) עם מאפיינים נוספים לתא הזה. אם מציינים null, כל המאפיינים הנוספים של התא יוסרו. מידע נוסף: setCell setProperty getProperty
setRowProperty(rowIndex, name, value)	אין	מגדיר מאפיין שורה. בחלק מהרכיבים החזותיים יש תמיכה במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או את ההתנהגות שלהם. במסמכי התיעוד של התצוגה החזותית מפורטות המאפיינים הנתמכים. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). name היא מחרוזת עם שם הנכס. value הוא ערך מכל סוג שצריך להקצות למאפיין בעל השם שצוין בשורה שצוינה. מידע נוסף: setRowProperties getRowProperty
setRowProperties(rowIndex, properties)	אין	מגדיר מאפייני מספר שורות. בחלק מהרכיבים החזותיים יש תמיכה במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או את ההתנהגות שלהם. במסמכי התיעוד של התצוגה החזותית מפורטות המאפיינים הנתמכים. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). properties הוא Object (מפת שם/ערכים) עם מאפיינים נוספים לשורה הזו. אם מציינים את null, כל המאפיינים הנוספים של השורה יוסרו. מידע נוסף: setRowProperty getRowProperty
setTableProperty(name, value)	אין	מגדירה מאפיין טבלה יחיד. בחלק מהרכיבים החזותיים יש תמיכה במאפיינים של טבלה, שורה, עמודה או תא כדי לשנות את התצוגה או את ההתנהגות שלהם. במסמכי התיעוד של התצוגה החזותית מפורטות המאפיינים הנתמכים. name היא מחרוזת עם שם הנכס. value הוא ערך מכל סוג שצריך להקצות למאפיין בעל השם שצוין בטבלה. מידע נוסף: setTableProperties getTableProperty
setTableProperties(properties)	אין	מגדירה כמה מאפיינים של טבלה. בחלק מהרכיבים החזותיים יש תמיכה במאפיינים של טבלה, שורה, עמודה או תא כדי לשנות את התצוגה או את ההתנהגות שלהם. במסמכי התיעוד של התצוגה החזותית מפורטות המאפיינים הנתמכים. properties הוא Object (מפת שם/ערך) עם מאפיינים נוספים לטבלה. אם מציינים את null, כל המאפיינים הנוספים של הטבלה יוסרו. מידע נוסף: setTableProperty getTableProperty
setValue(rowIndex, columnIndex, value)	אין	מגדיר את הערך של תא. בנוסף להחלפת ערך התא הקיים, השיטה הזו גם תנקה את הערכים והמאפיינים (property) שצוינו בתא. rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). columnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). ה-method הזה לא מאפשר להגדיר ערך בפורמט לתא הזה. כדי לעשות זאת, קוראים לפונקציה setFormattedValue(). value הוא הערך שהוקצה לתא שצוין. הסוג של הערך המוחזר תלוי בסוג העמודה (ראו getColumnType): אם סוג העמודה הוא 'string', הערך צריך להיות מחרוזת. אם סוג העמודה הוא 'מספר', הערך צריך להיות מספר. אם סוג העמודה הוא 'בוליאני', הערך צריך להיות בוליאני. אם סוג העמודה הוא תאריך או תאריך ושעה, הערך צריך להיות אובייקט Date. אם סוג העמודה הוא 'timeofday', הערך צריך להיות מערך של ארבעה מספרים: [hour, דקות, שניות, אלפיות שנייה]. בכל סוג של עמודה, ניתן להגדיר את הערך כ-null. ראו גם: setCell, setFormattedValue, setProperty, setProperties
sort(sortColumns)	אין	מיון השורות לפי עמודות המיון שצוינו. השדה DataTable משתנה באמצעות ה-method הזה. למידע על פרטי המיון, ראו getSortedRows(). השיטה הזו לא מחזירה את הנתונים הממוינים. למידע נוסף: getSortedRows דוגמה: כדי למיין לפי העמודה השלישית ולאחר מכן לפי העמודה השנייה, משתמשים בפקודה: data.sort([{column: 2}, {column: 1}]);
toJSON()	מחרוזת	הפונקציה מחזירה ייצוג ב-JSON של DataTable שאפשר להעביר אל constructor של DataTable. לדוגמה: {"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.

שיטות

שיטה	הערך המוחזר	תיאור
getColumnId getColumnLabel getColumnPattern getColumnProperty getColumnRange getColumnType getDistinctValues getFilteredRows getFormattedValue getNumberOfColumns getNumberOfRows getProperty getProperties getRowProperty getSortedRows getTableProperty getValue	ניתן לראות תיאורים בDataTable.	זהה ל-methods המקבילות ל-DataTable, אבל האינדקסים של שורות/עמודות מפנים לאינדקס בתצוגה ולא בטבלה או בתצוגה המפורטת הבסיסית.
getTableColumnIndex(viewColumnIndex)	מספרים	מחזירה את האינדקס בטבלה הבסיסית (או בתצוגה) של עמודה נתונה שצוינה באינדקס שלה בתצוגה הזו. viewColumnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות שמוחזרים באמצעות ה-method getNumberOfColumns(). הפונקציה מחזירה את הערך 1- אם זו עמודה שנוצרה. לדוגמה: אם בוצעה קריאה בעבר אל setColumns([3, 1, 4]), getTableColumnIndex(2) תחזיר 4.
getTableRowIndex(viewRowIndex)	מספרים	מחזירה את האינדקס בטבלה הבסיסית (או בתצוגה) של שורה נתונה שצוינה באינדקס שלה בתצוגה הזו. viewRowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי השיטה getNumberOfRows(). לדוגמה: אם בוצעה קריאה בעבר אל setRows([3, 1, 4]), getTableRowIndex(2) תחזיר 4.
getViewColumnIndex(tableColumnIndex)	מספרים	הפונקציה מחזירה את האינדקס בתצוגה הזו שממופה לעמודה נתונה שצוינה באינדקס שלה בטבלה הבסיסית (או בתצוגה המפורטת). אם קיים יותר מאינדקס אחד כזה, מחזירה את המדד הראשון (הקטן ביותר). אם לא קיים אינדקס כזה (העמודה שצוינה לא נמצאת בתצוגה), מחזירה את הערך 1-. tableColumnIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר העמודות כפי שהוחזר על ידי השיטה getNumberOfColumns() של הטבלה/התצוגה המפורטת הבסיסית. לדוגמה: אם בוצעה קריאה בעבר אל setColumns([3, 1, 4]), getViewColumnIndex(4) תחזיר 2.
getViewColumns()	מערך של מספרים	מחזירה את העמודות בתצוגה הזו, לפי הסדר. כלומר, אם קוראים לפונקציה setColumns עם מערך כלשהו ואז קוראים ל-getViewColumns(), אמור להתקבל מערך זהה.
getViewRowIndex(tableRowIndex)	מספרים	הפונקציה מחזירה את האינדקס בתצוגה הזו שממופה לשורה נתונה שמצוינת על ידי האינדקס שלה בטבלה הבסיסית (או בתצוגה המפורטת). אם קיים יותר מאינדקס אחד כזה, מחזירה את המדד הראשון (הקטן ביותר). אם לא קיים אינדקס כזה (השורה שצוינה לא נמצאת בתצוגה), מחזירה את הערך 1-. tableRowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהוחזרו על ידי ה-method getNumberOfRows() של הטבלה/התצוגה המפורטת הבסיסית. לדוגמה: אם בוצעה קריאה בעבר אל setRows([3, 1, 4]), getViewRowIndex(4) תחזיר 2.
getViewRows()	מערך של מספרים	מחזירה את השורות בתצוגה הזו, לפי הסדר. כלומר, אם קוראים ל-setRows עם מערך כלשהו, ואז קוראים ל-getViewRows(), אמור להתקבל מערך זהה.
hideColumns(columnIndexes)	אין	הסתרת העמודות שצוינו מהתצוגה הנוכחית. columnIndexes הוא מערך של מספרים שמייצגים את האינדקסים של העמודות להסתרה. האינדקסים האלה הם מספרי האינדקסים בטבלה/תצוגה המפורטת הבסיסית. המספרים ב-columnIndexes לא חייבים להיות בסדר (כלומר [3,4,1] תקין). העמודות האחרות שומרות על סדר האינדקס שלהן כשמבצעים חזרה עליהן. הזנת מספר אינדקס לעמודה שכבר מוסתרת אינה שגיאה, אבל הזנת אינדקס שלא קיים בטבלה/בתצוגה המפורטת הבסיסית גורמת לשגיאה. כדי לבטל את הסתרת העמודות, צריך לקרוא לפונקציה setColumns(). דוגמה: אם יש לכם טבלה עם 10 עמודות, קראו לפונקציה setColumns([2,7,1,7,9]) ולאחר מכן hideColumns([7,9]), העמודות בתצוגה יהיו [2,1].
hideRows(min, max)	אין	הסתרת כל השורות עם אינדקסים שנמצאים בין מינימום למקסימום (כולל) מהתצוגה הנוכחית. זהו תחביר נוחות ל-hideRows(rowIndexes) שלמעלה. לדוגמה, הערך hideRows(5, 10) שוות ערך ל-hideRows([5, 6, 7, 8, 9, 10]).
hideRows(rowIndexes)	אין	הסתרת השורות שצוינו מהתצוגה הנוכחית. rowIndexes הוא מערך של מספרים שמייצגים את האינדקסים של השורות שרוצים להסתיר. האינדקסים האלה הם מספרי האינדקסים בטבלה/תצוגה המפורטת הבסיסית. המספרים ב-rowIndexes לא חייבים להיות בסדר (כלומר [3,4,1] תקין). השורות הנותרות שומרות על סדר האינדקס שלהן. הזנה של מספר אינדקס לשורה שכבר מוסתרת אינה שגיאה, אבל הזנת אינדקס שלא קיים בטבלה או בתצוגה המפורטת הבסיסית תגרום לשגיאה. כדי לבטל את הסתרת השורות, צריך לקרוא לפונקציה setRows(). דוגמה: אם יש לכם טבלה עם 10 שורות ואתם קוראים לפונקציה setRows([2,7,1,7,9]), ואז hideRows([7,9]), השורות בתצוגה יהיו [2,1].
setColumns(columnIndexes)	אין	מציינת אילו עמודות יוצגו בתצוגה הזו. כל העמודות שלא צוינו יוסתרו. זהו מערך של אינדקסים של עמודות בטבלה או בתצוגה המפורטת הבסיסית או בעמודות המחושבות. אם לא קוראים ל-method הזה, ברירת המחדל היא להציג את כל העמודות. המערך יכול גם להכיל כפילויות, כדי להציג את אותה העמודה כמה פעמים. העמודות יוצגו בסדר שצוין. columnIndexes – מערך של מספרים ו/או אובייקטים (אפשר לשלב ביניהם): מספרים מציינים את האינדקס של עמודת נתוני המקור שצריך לכלול בתצוגה. הנתונים מועברים בלי שינויים. אם אתם צריכים להגדיר באופן מפורש תפקיד או מאפיינים נוספים של עמודות, ציינו אובייקט עם המאפיין sourceColumn. אובייקטים מציינים עמודה מחושבת. עמודה מחושבת יוצרת ערך בזמן אמת בכל שורה ומוסיפה אותו לתצוגה. האובייקט צריך לכלול את המאפיינים (properties) הבאים: calc [function] – פונקציה שתתבצע בכל שורה בעמודה כדי לחשב ערך לאותו תא. חתימת הפונקציה היא func(dataTable, row), כאשר dataTable הוא המקור DataTable ו-row הוא האינדקס של שורת נתוני המקור. הפונקציה צריכה להחזיר ערך יחיד מהסוג שצוין על ידי type. type [string] – סוג ה-JavaScript של הערך שפונקציית calc מחזירה. label [אופציונלי, string] – תווית אופציונלית להקצאה לעמודה הזו שנוצרה. אם לא מציינים זאת, עמודת התצוגה לא תכלול תווית. id [אופציונלי, string] – מזהה אופציונלי להקצאה לעמודה הזו שנוצרה. sourceColumn - [אופציונלי, number] עמודת המקור שבה רוצים להשתמש כערך. אם צוין, לא מציינים את המאפיין calc או את המאפיין type. הפעולה הזו דומה להעברת מספר במקום אובייקט, אבל מאפשרת לציין תפקיד ומאפיינים לעמודה החדשה. properties [אופציונלי, object] – אובייקט שמכיל מאפיינים שרירותיים להקצאה לעמודה הזו. אם לא מציינים זאת, עמודת התצוגה לא תכלול מאפיינים. role [אופציונלי, string] - תפקיד להקצאה לעמודה הזו. אם לא מגדירים את התפקיד הקיים, התפקיד הקיים לא ייובא. דוגמאות: // 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); }
setRows(min, max)	אין	מגדיר את השורות בתצוגה הזו לכל האינדקסים (בטבלה/בתצוגה המפורטת הבסיסית) שנמצאים בין מינימום ומקסימום (כולל). זהו תחביר נוחות של setRows(rowIndexes) שמופיע למטה. לדוגמה, setRows(5, 10) שוות ערך לפונקציה setRows([5, 6, 7, 8, 9, 10]).
setRows(rowIndexes)	אין	מגדיר את השורות הגלויות בתצוגה הזו, על סמך מספרי האינדקס מהטבלה/התצוגה המפורטת הבסיסית. rowIndexes צריך להיות מערך של מספרי אינדקסים שמציין אילו שורות להציג בתצוגה. המערך מציין את הסדר שבו יוצגו השורות, ואפשר גם לשכפל את השורות. שימו לב שיוצגו רק השורות שצוינו ב-rowIndexes. השיטה הזו מוחקת את כל השורות האחרות מהתצוגה. המערך יכול גם להכיל כפילויות, וכך ליצור עותק של השורה שצוינה בתצוגה הזו (לדוגמה, setRows([3, 4, 3, 2]) יגרום לשורה 3 להופיע פעמיים בתצוגה הזו). המערך מספק מיפוי של השורות מהטבלה או מהתצוגה המפורטת הבסיסית לתצוגה הזו. אפשר להשתמש ב-getFilteredRows() או ב-getSortedRows() כדי ליצור קלט לשיטה הזו. דוגמה: כדי ליצור תצוגה מפורטת עם שורות שלוש ואפס של טבלה/תצוגה מפורטת בסיסית: view.setRows([3, 0])
toDataTable()	DataTable	הפונקציה מחזירה אובייקט DataTable שמאוכלס בשורות ובעמודות הגלויות של DataView.
toJSON()	string	מחזירה ייצוג במחרוזת של DataView. המחרוזת הזו לא מכילה את הנתונים בפועל. היא מכילה רק את ההגדרות הספציפיות ל-DataView, כמו שורות ועמודות גלויות. אפשר לאחסן את המחרוזת הזו ולהעביר אותה ל- constructor הסטטי של DataView.fromJSON() כדי ליצור מחדש את התצוגה הזו. היא לא תכלול עמודות שנוצרו.

סיווג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 מציג את השיטות הנוספות הבאות:

שיטה	סוג הערך המוחזר	תיאור
draw(opt_container_ref)	אין	מצייר את התרשים. כדי להציג את השינויים, צריך להפעיל את ה-method הזה אחרי כל שינוי שמבצעים בתרשים או בנתונים. opt_container_ref [אופציונלי] - הפניה לרכיב קונטיינר חוקי בדף. אם השדה הזה מוגדר, התרשים יופיע שם. אם לא, התרשים ייכתב ברכיב עם המזהה שצוין באמצעות containerId.
toJSON()	מחרוזת	מחזירה גרסת מחרוזת של ייצוג JSON של התרשים.
clone()	ChartWrapper	מחזירה עותק עמוק של wrapper של התרשים.
getDataSourceUrl()	מחרוזת	אם התרשים הזה מקבל את הנתונים שלו ממקור נתונים, הפונקציה מחזירה את כתובת ה-URL של מקור הנתונים. אחרת, הפונקציה מחזירה את הערך null.
getDataTable()	google.visualization.DataTable	אם התרשים הזה מקבל את הנתונים שלו מ-DataTable שהוגדר באופן מקומי, הפונקציה תחזיר הפניה ל-DataTable של התרשים. אם התרשים הזה מקבל את הנתונים שלו ממקור נתונים, הוא יחזיר את הערך null. כל השינויים שמבצעים באובייקט המוחזר יבואו לידי ביטוי בתרשים בפעם הבאה שתפעילו את האובייקט ChartWrapper.draw().
getChartType()	מחרוזת	שם הכיתה של התרשים המוקף. אם זהו תרשים של Google, השם לא יתאים עם google.visualization. לדוגמה, אם מדובר בתרשים Treemap, הוא יחזיר 'Treemap' ולא 'google.Visualization.treemap'.
getChartName()	מחרוזת	הפונקציה מחזירה את שם התרשים שהוקצה על ידי setChartName().
getChart()	הפניה לאובייקטים בתרשים	מחזירה הפניה לתרשים שנוצר על ידי ChartWrapper, לדוגמה google.visualization.BarChart או google.visualization.ColumnChart . הפונקציה תחזיר null עד לאחר קריאה ל-draw() באובייקט ChartWrapper, והיא תגרור אירוע מוכן. ה-methods שנקראו לאובייקט המוחזר יופיעו בדף.
getContainerId()	מחרוזת	המזהה של רכיב הקונטיינר DOM בתרשים.
getQuery()	מחרוזת	מחרוזת השאילתה לתרשים הזה, אם יש לו שאילתה כזו, והיא נשלחת אל מקור נתונים.
getRefreshInterval()	מספרים	כל מרווח רענון של התרשים הזה, אם הוא שולח שאילתה למקור נתונים. איפוס מציין שאין רענון.
getOption(key, opt_default_val)	כל סוג	פונקציה זו מחזירה את ערך האפשרות שצוין בתרשים key – השם של אפשרות האחזור. יכול להיות שם שעומד בדרישות, כמו 'vAxis.title'. opt_default_value [Optional] - אם הערך שצוין לא מוגדר או אפס, הערך יוחזר.
getOptions()	אובייקט	מחזירה את אובייקט האפשרויות של התרשים.
getView()	אובייקט או מערך	מחזירה את אובייקט המאתחל DataView, באותו פורמט כמו dataview.toJSON(), או מערך של אובייקטים כאלו.
setDataSourceUrl(url)	אין	מגדיר את כתובת ה-URL של מקור נתונים לשימוש בתרשים הזה. אם תגדירו גם טבלת נתונים לאובייקט הזה, המערכת תתעלם מכתובת ה-URL של מקור הנתונים.
setDataTable(table)	אין	מגדיר את ה-DataTable עבור התרשים. מעבירים את אחת מהאפשרויות הבאות: null, אובייקט DataTable, ייצוג JSON של DataTable או מערך שתואם לתחביר של arrayToDataTable().
setChartType(type)	אין	מגדיר את סוג התרשים. מעבירים את שם הכיתה של התרשים המוקף. אם זהו תרשים של Google, אין לך אפשרות להשתמש בתרשים הזה עם google.visualization. לדוגמה, בתרשים עוגה, מעבירים את הערך 'PieChart'.
setChartName(name)	אין	מגדיר שם שרירותי לתרשים. המידע הזה לא מוצג בשום מקום בתרשים, אלא אם התרשים המותאם אישית מיועד לשימוש בו באופן מפורש.
setContainerId(id)	אין	מגדיר את המזהה של רכיב ה-DOM שמכיל את התרשים.
setQuery(query_string)	אין	מגדיר מחרוזת שאילתה, אם התרשים הזה שולח שאילתה למקור נתונים. אם מציינים את הערך הזה, צריך גם להגדיר את כתובת ה-URL של מקור הנתונים.
setRefreshInterval(interval)	אין	מגדיר את מרווח הרענון של התרשים, אם הוא שולח שאילתה למקור נתונים. אם מציינים את הערך הזה, צריך גם להגדיר כתובת URL של מקור נתונים. אפס מציין שאין רענון.
setOption(key, value)	אין	הפונקציה מגדירה ערך של אפשרות בתרשים יחיד, כאשר key הוא שם האפשרות ו-value הוא הערך. כדי לבטל את ההגדרה של אפשרות, צריך להעביר את הערך כ-null. שימו לב ש-key יכול להיות שם תקין, כמו 'vAxis.title'.
setOptions(options_obj)	אין	מגדירה אובייקט אפשרויות מלא לתרשים.
setView(view_spec)	אין	מגדיר אובייקט מאתחל DataView, שמשמש כמסנן של נתוני הבסיס. ה-wrapper של התרשים חייב לכלול נתונים בסיסיים מ-DataTable או ממקור נתונים שעליו רוצים להחיל את התצוגה הזו. אפשר להעביר במחרוזת או באובייקט המאתחל DataView, כמו זה שמוחזר על ידי dataview.toJSON(). אפשר גם להעביר במערך של אובייקטים של אתחול DataView. במקרה כזה, ה-DataView הראשון במערך מוחל על נתוני הבסיס כדי ליצור טבלת נתונים חדשה, וה-DataView השני מוחל על טבלת הנתונים שמתקבלת מהיישום של ה-DataView הראשון, וכן הלאה.

אירועים

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

שם	תיאור	תכונות
error	מופעל כשמתרחשת שגיאה בניסיון לעבד את התרשים.	מזהה, הודעה
ready	התרשים מוכן לקריאות method חיצוניות. אם רוצים להשתמש בתרשים, ולהפעיל שיטות אחרי שרטוט, צריך להגדיר האזנה לאירוע הזה לפני שמפעילים את השיטה draw, ולהפעיל את ה-methods רק אחרי שהאירוע הופעל.	אין
select	מופעל כשהמשתמש לוחץ על עמודה או מקרא. כשבוחרים רכיב בתרשים, נבחר התא המתאים בטבלת הנתונים. כשבוחרים מקרא, נבחרת העמודה המתאימה בטבלת הנתונים. כדי לבדוק אילו קבוצות נבחרו, אפשר להתקשר למספר ChartWrapper.getChart(). getSelection(). חשוב לשים לב שהכלל הזה יועבר רק כשסוג התרשים הבסיסי מקפיץ אירוע בחירה.	אין

דוגמה

שני קטעי הקוד הבאים יוצרים תרשים קו מקביל. בדוגמה הראשונה נעשה שימוש בסימון מילולי של 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().

שיטות

שיטה	הערך המוחזר	תיאור
openDialog(chartWrapper, opt_options)	null	פותח את עורך התרשימים כתיבת דו-שיח מוטמעת בדף. הפונקציה מחזירה באופן מיידי. היא לא ממתינה שתיבת הדו-שיח תיסגר. אם ההיקף של המכונה לא יאבד, תוכלו לקרוא שוב אל openDialog() כדי לפתוח מחדש את תיבת הדו-שיח, אבל תצטרכו להעביר שוב באובייקט ChartWrapper. chartWrapper – אובייקט ChartWrapper שמגדיר את התרשים הראשוני שצריך לעבד בחלון. התרשים צריך להכיל DataTable, או להיות מחובר למקור נתונים תקין. ה-wrapper הזה מועתק באופן פנימי לעורך התרשימים כך ששינויים מאוחרים יותר שתבצעו בנקודת האחיזה של ChartWrapper לא יבואו לידי ביטוי בעותק של עורך התרשימים. opt_options – [אופציונלי] אובייקט שמכיל אפשרויות לעורך התרשימים. אפשרויות מפורטות מפורטות בטבלת האפשרויות שבהמשך.
getChartWrapper()	ChartWrapper	הפונקציה מחזירה את הערך ChartWrapper שמייצג את התרשים, עם שינויים שהמשתמשים מבצעים.
setChartWrapper(chartWrapper)	null	אפשר להשתמש בשיטה הזו כדי לעדכן בכלי העריכה את התרשים שעבר עיבוד. chartWrapper – אובייקט ChartWrapper שמייצג את התרשים החדש שצריך לעבד. הערך של התרשים צריך להיות DataTable מאוכלס, או שהוא צריך להיות מחובר למקור נתונים חוקי.
closeDialog()	null	סגירת תיבת הדו-שיח של עורך התרשימים.

אפשרויות

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

שם	סוג	ברירת המחדל	תיאור
dataSourceInput	נקודת אחיזה לרכיב או urlbox	null	המאפיין הזה מאפשר למשתמשים לציין מקור נתונים לתרשים. המאפיין הזה יכול להיות אחד משני ערכים: 'urlbox' - הצגת כתובת ה-URL של מקור הנתונים של התרשים בתיבת הדו-שיח בתיבת טקסט שניתנת לעריכה. המשתמש יכול לשנות את ההגדרה הזו והתרשים יוצג מחדש בהתאם למקור הנתונים החדש. אלמנט DOM – מאפשר לספק רכיב HTML מותאם אישית לשימוש כדי לבחור מקור נתונים. מעבירים את נקודת האחיזה לרכיב HTML של HTML, שנוצר בקוד או הועתק מהדף. הרכיב הזה יוצג בתיבת הדו-שיח. אפשר להשתמש באפשרות הזו כדי לאפשר למשתמש לבחור את מקור הנתונים של התרשים. לדוגמה, צור תיבת רשימה שמכילה כמה כתובות URL של מקורות נתונים, או שמות ידידותיים למשתמש שמתוכם המשתמשים יכולים לבחור. הרכיב חייב להטמיע handler של בחירה ולהשתמש בו כדי לשנות את מקור הנתונים של התרשים: לדוגמה, לשנות את DataTable הבסיסי או לשנות את השדה dataSourceUrl של התרשים.

אירועים

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

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

דוגמה

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

שיטה	תיאור
google.visualization.data.group	מבצעת פעולת SQL GROUP BY כדי להחזיר טבלה שמקובצת לפי ערכים בעמודות שצוינו.
google.visualization.data.join	מחבר שתי טבלאות נתונים בעמודת מפתח אחת או יותר.

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 כדי להתאים אישית את התנהגות הקיבוץ.

פעולה	סוג מערך הקלט	סוג הערך המוחזר	תיאור
google.visualization.data.month	תאריך	number	בהינתן תאריך, הפונקציה תחזיר את ערך החודש המבוסס על אפס (0, 1, 2 וכן הלאה).

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

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

פעולה	סוג מערך הקלט	סוג הערך המוחזר	תיאור
google.visualization.data.avg	number	number	הערך הממוצע של המערך שהועבר.
google.visualization.data.count	כל סוג	number	מספר השורות בקבוצה. המערכת סופרת ערכים ריקים וכפולים.
google.visualization.data.max	מספר, מחרוזת, תאריך	number, string, Date, null	הערך המקסימלי במערך. למחרוזות, זהו הפריט הראשון ברשימה ממוינת לקסיקוגרפיה. בערכי תאריך, זהו הפריט האחרון. המערכת מתעלמת ממשתנים. הפונקציה מחזירה ערך null אם אין ערך מקסימלי.
google.visualization.data.min	מספר, מחרוזת, תאריך	number, string, Date, null	הערך המינימלי במערך. למחרוזות, זהו הפריט האחרון ברשימה ממוינת לקסיקוגרפיה. עבור ערכי תאריך, זהו התאריך המוקדם ביותר. המערכת מתעלמת ממשתנים. הפונקציה מחזירה ערך null אם אין ערך מינימלי.
google.visualization.data.sum	number	number	הסכום של כל הערכים במערך.

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

אפשר ליצור פונקציית מגביל כדי לבצע ערכים פשוטים של טרנספורמציה מרכזיים לפני שהפונקציה 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', '[e-mail]'],
  ['Paul McCartney', '[e-mail]'],
  ['George Harrison', '[e-mail]'],
  ['Ringo Starr', '[e-mail]']
]);

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