הפניית Google Vision API

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

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

1. טבלת טבלת נתונים
2. שיעור צפייה בנתונים
3. Class wrapper class
4. ClassEditor
5. שיטות לשינוי נתונים
   1. group()
   2. join()
6. פורמטים
   1. חץ עיצוב
   2. BarFormat
   3. צבעפורמט
   4. פורמט תאריך
   5. NumberNumber
   6. קו ביטול נעילה
7. ClassHelper
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. drawסרגל הכלים()

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

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

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

המחלקה של טבלת הנתונים

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

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

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

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

בונה

תחביר

DataTable(opt_data, opt_version)

opt_data

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

opt_version

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

פרטים

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

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

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

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

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

דוגמאות

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

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 באמצעות קריאה לבנאי ללא פרמטרים והוספת ערכים על ידי קריאה לשיטות 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'}). אפשר לשלב ערכים ואובייקטים פשוטים באותה קריאה בשיטה). שימוש ב-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)	מספר	הוספה של שורות חדשות לטבלת הנתונים, והחזרת השורה של השורה האחרונה שהוספת. אפשר לקרוא לשיטה הזו כדי ליצור שורות חדשות ריקות או באמצעות נתונים לאכלוס השורות, כפי שמתואר בהמשך. 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()	טבלת נתונים	מחזירה שיבוט של טבלת הנתונים. התוצאה היא עותק עמוק של טבלת הנתונים, מלבד מאפייני התא, מאפייני השורה, מאפייני הטבלה ונכסי העמודה, שהעותקים שלהם שטחיים. כלומר, נכסים לא פשוטים מועתקים לפי הפניה, אבל נכסים בסיסיים מועתקים לפי ערך.
getColumnId(columnIndex)	String	מחזירה את המזהה של עמודה נתונה שצוינה באינדקס העמודה בטבלה הבסיסית. בטבלאות נתונים שמאוחזרות על ידי שאילתות, מזהה העמודה מוגדר על ידי מקור הנתונים, ואפשר להשתמש בו כדי להפנות לעמודות כשמשתמשים בשפת השאילתות. לעיון גם: Query.setQuery
getColumnIndex(columnIdentifier)	מחרוזת, מספר	מחזירה את האינדקס של עמודה נתונה שצוינה על ידי אינדקס העמודה, המזהה או התווית, אם היא קיימת בטבלה זו, אחרת -1. כשהמחרוזת columnIdentifier היא מחרוזת, היא משמשת לאיתור העמודה לפי המזהה שלה, לפני התווית שלה. לעיון גם: getColumnId, getColumnLabel
getColumnLabel(columnIndex)	String	מחזירה את התווית של עמודה נתונה שצוינה על ידי אינדקס העמודה בטבלה הבסיסית. תווית העמודה מוצגת בדרך כלל כחלק מההצגה החזותית. לדוגמה, תווית העמודה יכולה להופיע ככותרת עמודה בטבלה, או כתווית מקרא בתרשים עוגה. בטבלאות נתונים שמאוחזרות על ידי שאילתות, תווית העמודה מוגדרת לפי מקור הנתונים או לפי הסעיף label בשפת השאילתות. לעיון גם: setColumnLabel
getColumnPattern(columnIndex)	String	מחזירה את דפוס העיצוב המשמש לעיצוב הערכים של העמודה שצוינה. columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). לטבלאות נתונים שאוחזרו על ידי שאילתות, תבנית העמודה מוגדרת על ידי מקור הנתונים, או לפי הקטע format בשפת השאילתה. דוגמה לתבנית: '#,##0.00'. מידע נוסף על תבניות זמין בחומר העזר בנושא שפת השאילתות.
getColumnProperties(columnIndex)	התנגדות	מחזירה מפה של כל המאפיינים בעמודה שצוינה. הערה: אובייקט המאפיינים מוחזר על ידי הפניה, כך ששינוי הערכים באובייקט המאוחזר משנה אותם ב-DataTable. columnIndex הוא האינדקס המספרי של העמודה שאליה יש לאחזר מאפיינים.
getColumnProperty(columnIndex, name)	אוטומטית	מחזירה את הערך של מאפיין בעל שם, או null אם לא הוגדר נכס כזה עבור העמודה שצוינה. סוג ההחזרה משתנה בהתאם לנכס. columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). name הוא שם המאפיין כמחרוזת. מידע נוסף: setColumnProperty setColumnProperties
getColumnRange(columnIndex)	התנגדות	מחזירה את ערכי המינימום והמקסימום של ערכים בעמודה נתונה. לאובייקט שהוחזר יש מאפיינים min ו-max. אם הטווח אינו מכיל ערכים, min ו-max יכילו null. הערך של columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns().
getColumnRole(columnIndex)	String	מחזירה את התפקיד של העמודה שצוינה.
getColumnType(columnIndex)	String	מחזירה את סוג העמודה שצוינה על ידי אינדקס העמודה. columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). סוג העמודה שהוחזרה יכול להיות אחת מהאפשרויות הבאות: 'string', 'number', 'boolean', 'date', 'datetime', ו-'timeofday'
getDistinctValues(columnIndex)	מערך אובייקטים	מחזירה את הערכים הייחודיים בעמודה מסוימת, בסדר עולה. columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). סוג האובייקטים המוחזרים זהה לסוג האובייקטים המוחזרים בשיטת getValue.
getFilteredRows(filters)	מערך אובייקטים	מחזירה את האינדקסים של השורות לשורות שתואמות לכל המסננים הנתונים. האינדקסים חוזרים בסדר עולה. הפלט של השיטה הזו יכול לשמש כקלט ל-DataView.setRows() כדי לשנות את קבוצת השורות בתצוגה החזותית. filters - מערך אובייקטים שמתאר ערך קביל של תא. שיטה זו מחזירה אינדקס של שיטה אם הוא תואם לכל המסננים הנתונים. כל מסנן הוא אובייקט עם מאפיין מספרי column שמציין את אינדקס העמודה בשורה להערכה, וגם את אחד מהבאים: נכס ב-value עם ערך שחייב להתאים בדיוק לתא בעמודה שצוינה. הערך חייב להיות זהה לזה שמופיע בעמודה; או אחד או יותר מהמאפיינים הבאים, מאותו סוג של העמודה שסוננה: minValue – ערך מינימלי של התא. ערך התא בעמודה חייב להיות גדול מהערך הזה או שווה לו. maxValue – הערך המקסימלי של התא. ערך התא בעמודה חייב להיות קטן מהערך הזה או שווה לו. המשמעות של ערך אפס או שלא הוגדר עבור 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)	String	מחזירה את הערך המפורמט של התא באינדקסים של השורה והעמודה. הערך של rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהמערכת מחזירה בשיטת getNumberOfRows(). ColumnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). למידע נוסף על עיצוב ערכים של עמודות, אפשר לעיין בחומר העזר בנושא שפת השאילתות. למידע נוסף: setFormattedValue
getNumberOfColumns()	מספר	מחזירה את מספר העמודות בטבלה.
getNumberOfRows()	מספר	מחזירה את מספר השורות בטבלה.
getProperties(rowIndex, columnIndex)	התנגדות	מחזירה מפה של כל המאפיינים בתא שצוין. חשוב לשים לב שהאובייקט של המאפיין מוחזר על ידי הפניה, כך ששינוי הערכים באובייקט המאוחזר משנה אותם ב-DataTable. rowIndex הוא אינדקס השורות של התא. columnIndex הוא אינדקס העמודה של התא.
getProperty(rowIndex, columnIndex, name)	אוטומטית	מחזירה את הערך של מאפיין בעל שם, או null אם לא הוגדר מאפיין כזה עבור התא שצוין. סוג ההחזרה משתנה בהתאם לנכס. הערך של rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהמערכת מחזירה בשיטת getNumberOfRows(). columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). המחרוזת name היא מחרוזת עם שם הנכס. מידע נוסף: setCell setProperty setProperty
getRowProperties(rowIndex)	התנגדות	מחזירה מפה של כל המאפיינים בשורה שצוינה. הערה: אובייקט המאפיינים מוחזר על ידי הפניה, כך ששינוי הערכים באובייקט המאוחזר משנה אותם ב-DataTable. rowIndex הוא האינדקס של השורה לאחזור מאפיינים.
getRowProperty(rowIndex, name)	אוטומטית	מחזירה את הערך של מאפיין בעל שם, או null אם לא הוגדר מאפיין כזה עבור השורה שצוינה. סוג ההחזרה משתנה בהתאם לנכס. הערך של rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהמערכת מחזירה בשיטת getNumberOfRows(). המחרוזת name היא מחרוזת עם שם הנכס. למידע נוסף: setRowProperty setRowProperty
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 צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). סוג הערך המוחזר תלוי בסוג העמודה (ראו getColumnType): אם סוג העמודה הוא 'string', הערך הוא מחרוזת. אם סוג העמודה הוא 'number', הערך הוא מספר. אם סוג העמודה הוא 'בוליאני', הערך הוא בוליאני. אם סוג העמודה הוא 'תאריך' או 'תאריך', הערך הוא אובייקט תאריך. אם סוג העמודה הוא 'timeofday', הערך הוא מערך של ארבעה מספרים: [hour, minute, second, אלפיות השנייה]. אם ערך התא הוא ערך ריק, הפונקציה מחזירה את הערך 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 צריך להיות מספר עם אינדקס חוקי של עמודות. למידע נוסף: removeעמודות
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 צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). value [אופציונלי] הוא הערך שהוקצה לתא שצוין. כדי להחליף את הערך הזה, צריך להגדיר את הפרמטר הזה לערך undefined. כדי למחוק את הערך הזה, צריך להגדיר אותו לערך null. סוג הערך תלוי בסוג העמודה (מידע נוסף מופיע במאמר getColumnType() ): אם סוג העמודה הוא 'string', הערך צריך להיות מחרוזת. אם סוג העמודה הוא 'number', הערך צריך להיות מספר. אם סוג העמודה הוא 'בוליאני', הערך צריך להיות בוליאני. אם סוג העמודה הוא 'תאריך' או 'תאריך', הערך צריך להיות אובייקט תאריך. אם סוג העמודה הוא 'timeofday', הערך צריך להיות מערך של ארבעה מספרים: [hour, minute, second, אלפיות השנייה]. formattedValue [אופציונלי] היא מחרוזת שהערך שלה הוא מחרוזת. כדי למנוע החלפה של הערך הזה, צריך להגדיר את הפרמטר הזה לערך undefined. כדי לנקות את הערך ולבקש מה-API להחיל את עיצוב ברירת המחדל על value, לפי הצורך, צריך להגדיר אותו כ-null. כדי להגדיר ערך בפורמט ריק, צריך להגדיר אותו כמחרוזת ריקה. לרוב, הערך בפורמט מייצג רכיבים חזותיים כדי להציג תוויות של ערכים. לדוגמה, הערך בפורמט יכול להופיע כטקסט של תווית בתרשים עוגה. השדה properties [אופציונלי] הוא Object (מפה של שם/ערך) הכוללת מאפיינים נוספים עבור התא הזה. כדי למנוע החלפה של הערך הזה, צריך להגדיר את הפרמטר הזה לערך undefined. כדי למחוק את הערך הזה, צריך להגדיר אותו לערך null. חלק מהרכיבים החזותיים תומכים במאפייני שורות, עמודות או תאים כדי לשנות את התצוגה או את ההתנהגות שלהם. תוכלו לעיין בתיעוד של הרכיבים החזותיים כדי לראות אילו מאפיינים נתמכים בהם. מידע נוסף זמין במאמר הבא: setValue(), setFormattedValue() , setProperty() , setProperty() .
setColumnLabel(columnIndex, label)	ללא	הגדרת תווית של עמודה. columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). המחרוזת label היא מחרוזת עם התווית שברצונך להקצות לעמודה. תווית העמודה מוצגת בדרך כלל כחלק מההצגה החזותית. לדוגמה, התווית של העמודה יכולה להופיע ככותרת של עמודה בטבלה או כתווית של מקרא בתרשים עוגה. למידע נוסף: getColumnLabel
setColumnProperty(columnIndex, name, value)	ללא	מגדיר מאפיין בעמודה אחת. חלק מהרכיבים החזותיים תומכים במאפייני שורות, עמודות או תאים כדי לשנות את התצוגה או את ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד. columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). המחרוזת name היא מחרוזת עם שם הנכס. הערך value הוא ערך מכל סוג שיש להקצות לנכס שצוין בעמודה שצוינה. מידע נוסף:setColumnProperties getColumnProperty
setColumnProperties(columnIndex, properties)	ללא	הגדרה של מאפייני עמודות מרובים. חלק מהרכיבים החזותיים תומכים במאפייני שורות, עמודות או תאים כדי לשנות את התצוגה או את ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד. columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). העמודה properties היא Object (מפת שם/ערך) עם מאפיינים נוספים לעמודה זו. אם מצוין null, כל המאפיינים הנוספים של העמודה יוסרו. מידע נוסף: setColumnProperty getColumnProperty
setFormattedValue(rowIndex, columnIndex, formattedValue)	ללא	מגדיר את הערך המפורמט של תא. הערך של rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהמערכת מחזירה בשיטת getNumberOfRows(). columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). formattedValue היא מחרוזת עם הערך המעוצב עבור התצוגה. כדי לנקות את הערך הזה כך שה-API יחיל את עיצוב ברירת המחדל על ערך התא לפי הצורך, מגדירים אותו formatValue null. כדי להגדיר ערך בפורמט ריק באופן מפורש, מגדירים אותו למחרוזת ריקה. ראו גם: getFormattedValue
setProperty(rowIndex, columnIndex, name, value)	ללא	מגדיר מאפיין של תא. חלק מהרכיבים החזותיים תומכים במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד. הערך של rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהמערכת מחזירה בשיטת getNumberOfRows(). columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). המחרוזת name היא מחרוזת עם שם הנכס. value הוא ערך מכל סוג שיש להקצות למאפיין שמצוין בשם של התא שצוין. מידע נוסף: setCell setProperty getProperty
setProperties(rowIndex, columnIndex, properties)	ללא	הגדרה של מספר מאפייני תאים. חלק מהרכיבים החזותיים תומכים במאפייני שורות, עמודות או תאים כדי לשנות את התצוגה או את ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד. הערך של rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהמערכת מחזירה בשיטת getNumberOfRows(). columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). השדה properties הוא Object (מפת שם/ערך) עם מאפיינים נוספים לתא זה. אם מציינים את null, כל המאפיינים הנוספים של התא יוסרו. מידע נוסף: setCell setProperty getProperty
setRowProperty(rowIndex, name, value)	ללא	מגדיר מאפיין שורה. חלק מהרכיבים החזותיים תומכים במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד. הערך של rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהמערכת מחזירה בשיטת getNumberOfRows(). המחרוזת name היא מחרוזת עם שם הנכס. value הוא ערך מכל סוג שיש להקצות למאפיין שמצוין בשורה של השורה שצוינה. למידע נוסף: setRowProperty 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)	ללא	מגדירה את הערך של תא. מעבר להחלפת ערך קיים של תא, השיטה הזו תמחק גם את כל הערכים והמאפיינים של התא. הערך של rowIndex צריך להיות מספר גדול מ-0 או שווה לו, וקטן ממספר השורות שהמערכת מחזירה בשיטת getNumberOfRows(). columnIndex צריך להיות מספר גדול מאפס או שווה לו, וקטן ממספר העמודות שמוחזרות על ידי השיטה getNumberOfColumns(). השיטה הזו לא מאפשרת להגדיר ערך מעוצב לתא הזה. לשם כך, צריך לקרוא לפונקציה setFormattedValue(). value הוא הערך שהוקצה לתא שצוין. סוג הערך המוחזר תלוי בסוג העמודה (מידע נוסף זמין במאמר getColumnType): אם סוג העמודה הוא 'string', הערך צריך להיות מחרוזת. אם סוג העמודה הוא 'number', הערך צריך להיות מספר. אם סוג העמודה הוא 'בוליאני', הערך צריך להיות בוליאני. אם סוג העמודה הוא 'תאריך' או 'תאריך', הערך צריך להיות אובייקט תאריך. אם סוג העמודה הוא 'timeofday', הערך צריך להיות מערך של ארבעה מספרים: [hour, minute, second, אלפיות השנייה]. בכל סוג של עמודה, אפשר להגדיר את הערך כ-null. למידע נוסף: setCell, setFormattedValue, setProperty, setProperty
sort(sortColumns)	ללא	ממיינת את השורות, בהתאם לעמודות המיון שצוינו. שיטה זו משנה את DataTable. אפשר להיכנס ל-getSortedRows() לקבלת תיאור של פרטי המיון. שיטה זו לא מחזירה את הנתונים הממוינים. לעיון גם: getsortedRows לדוגמה: כדי למיין לפי העמודה השלישית ולאחר מכן לפי העמודה השנייה, יש להשתמש ב: data.sort([{column: 2}, {column: 1}]);
toJSON()	String	מחזירה ייצוג JSON של DataTable שניתן להעביר אל הבנאי של 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 data של ה-build

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

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

{
  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: 'number', אבל הערך עצמו, כמספרים, יתבטא כך: v: 42

נכס אחד (cols)

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

• type [חובה] סוג הנתונים של הנתונים בעמודה. תומך בערכי המחרוזת הבאים (לדוגמה, תכונת v:, שתוארה בהמשך):
  • 'boolean' – ערך בוליאני של JavaScript ('true' או 'false'). ערך לדוגמה: v:'true'
  • 'number' - ערך מספר JavaScript. ערכים לדוגמה: v:7 , v:3.14, v:-55
  • 'string' - ערך מחרוזת JavaScript. ערך לדוגמה: v:'hello'
  • 'date' - אובייקט התאריך של JavaScript (חודש מבוסס-אפס), ללא מגבלת זמן. ערך לדוגמה: 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, סביר להניח שהדפוס שציינת בסעיף זה יוחזר בערך הזה. הסטנדרטים המומלצים לגבי תבניות הם ה-ICU, DecimalFormat ו- 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 חייב להיות ריק, אם כי עדיין יכולים להיות לו המאפיינים f ו-p.
• f [אופציונלי] גרסת מחרוזת של הערך v, בפורמט שמיועד לתצוגה. בדרך כלל הערכים יהיו זהים, אם כי הם לא חייבים להתאים. לכן, אם מציינים Date(2008, 0, 1) עבור v, צריך לציין את המחרוזת "1 בינואר 2008" או מחרוזת כזאת של הנכס הזה. הערך הזה לא נבדק ביחס לערך v. התצוגה החזותית לא תשתמש בערך הזה לצורך חישוב, אלא רק כתווית להצגה. אם פרט זה יושמט, גרסת המחרוזת של v תיווצר באופן אוטומטי באמצעות עיצוב ברירת המחדל. אפשר לשנות את הערכים של f באמצעות המעצב האישי שלך, או להגדיר אותם עם setFormattedValue() או עם setCell() או לאחזר אותם עם getFormattedValue().
• p [אופציונלי] אובייקט הוא מפה של ערכים מותאמים אישית שהוחלו על התא. הערכים האלה יכולים להיות מכל סוג JavaScript. אם התצוגה החזותית שלך תומכת בכל המאפיינים ברמת התא, הם יתארו אותם. ניתן לאחזר את המאפיינים האלה בשיטות של getProperty() ו-getProperties(). לדוגמה: p:{style: 'border: 1px solid green;'}

התאים במערך השורות צריכים להיות באותו סדר כמו התיאורים של העמודות שלהם ב-cols. כדי לציין תא ריק, אפשר לציין 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 ברמת הטבלה הוא מפה של ערכים מותאמים אישית שהוחלה על כל DataTable. הערכים האלה יכולים להיות מכל סוג JavaScript. אם התצוגה החזותית שלך תומכת בכל המאפיינים ברמת טבלת הנתונים, היא תתאר אותם. אחרת, הנכס הזה יהיה זמין לשימוש באפליקציות. לדוגמה: p:{className: 'myDataTable'}

שיעור צפייה בנתונים

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

למידע נוסף:

setעמודות() , hideעמודות() , setRows() , hideRows() .

 

בונה 2

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

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

נתונים

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

viewAsJson

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

שיטות

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

סיווג גלישת תרשימים

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

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

עם זאת, בשלב זה ChartWrapper מפיץ רק קבוצת משנה של אירועים שנוצרו על ידי תרשימים: Select, ready ו-error. אירועים אחרים לא מועברים באמצעות המכונה של 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() . אם לא צוין אחרת, עליך להגדיר את כל המאפיינים המתאימים באמצעות שיטות set... שהאובייקט הזה חושף.

שיטות

ChartWrapper חושף את השיטות הנוספות הבאות:

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

אירועים

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

שם	תיאור	נכסים
error	מופעל כשמתרחשת שגיאה במהלך הניסיון לעבד את התרשים.	מזהה, הודעה
ready	התרשים מוכן לקריאות חיצוניות לשיטה אם רוצים ליצור אינטראקציה עם התרשים ולבקש שיטות שיחה אחרי שכותבים אותו, צריך להגדיר למאזינים אירוע לפני שמתקשרים לשיטת draw ולהתקשר אליהם רק אחרי שהאירוע הופעל.	ללא
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 ונרשמים כדי להאזין לאירוע "אישור". האירוע הזה נזרק כשהמשתמש לוחץ על הלחצן 'אישור' בתיבת הדו-שיח. לאחר השליחה, יש להתקשר אל ChartEditor.getChartWrapper() כדי לאחזר את התרשים ששונה על ידי המשתמש.
4. התקשרות אל ChartEditor.openDialog() ועוברת בChartWrapper. הפעולה הזו פותחת את תיבת הדו-שיח. לחצני הדו-שיח מאפשרים למשתמש לסגור את העורך. המופע של ChartEditor זמין כל עוד הוא קיים בהיקף. הוא לא מושמד באופן אוטומטי אחרי שהמשתמש סוגר את תיבת הדו-שיח.
5. כדי לעדכן את התרשים בקוד, יש להתקשר למספר setChartWrapper().

שיטות

שיטה	ערך החזרה	תיאור
openDialog(chartWrapper, opt_options)	null	פתיחת עורך התרשימים כתיבת דו-שיח מוטמעת בדף. הפונקציה חוזרת באופן מיידי. היא לא ממתינה לתיבת הדו-שיח לסגירה. אם לא מאבדים את היקף המכונה, אפשר להפעיל מחדש את openDialog() כדי לפתוח מחדש את תיבת הדו-שיח, אבל צריך להעביר שוב אובייקט ChartWrap. 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 שנוצר בקוד או הועתק מהדף. הרכיב הזה יוצג בתיבת הדו-שיח. יש להשתמש באפשרות הזו כדי לאפשר למשתמש לבחור את מקור הנתונים של התרשים. לדוגמה, אפשר ליצור תיבת רשימה שכוללת מספר כתובות 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), אבל אפשר להגדיר אותם בעצמך (לדוגמה, standardDviation או secondHighest). אחרי שתגדירו את תיאור השיטה תוכלו למצוא הוראות להגדרת אתר אגרגטור משלכם.

תחביר

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

data_table

הקלט DataTable. המערכת לא תשנה את השם הזה על ידי התקשרות ל-group().

מפתחות

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

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

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

עמודות

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

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

ערך החזרה

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

דוגמה

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

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

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

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

תפקיד	סוג מערך הקלט	סוג הערך המוחזר	תיאור
google.visualization.data.avg	number	number	הערך הממוצע של המערך שהועבר.
google.visualization.data.count	כל סוג	number	מספר השורות בקבוצה. המערכת סופרת ערכים מיותרים וכפולים.
google.visualization.data.max	מספר, מחרוזת, תאריך	מספר, מחרוזת, תאריך, ריק	הערך המקסימלי במערך. כשמדובר במחרוזות, זה הפריט הראשון ברשימה שממוינת לפי נתוני מילונציה. ב'תאריך' מציינים את התאריך האחרון. המערכת מתעלמת מהפקקים. מחזירה את הערך null אם אין ערך מקסימלי.
google.visualization.data.min	מספר, מחרוזת, תאריך	מספר, מחרוזת, תאריך, ריק	הערך המינימלי במערך. כשמדובר במחרוזות, זהו הפריט האחרון ברשימה שממוינת באופן סקסוגרפי. בערכי תאריך, זהו התאריך המוקדם ביותר. המערכת מתעלמת מהפקקים. מחזירה 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 לבין העמודה השנייה מ-dt2.

dt1עמודות

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

dt2עמודות

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

ערך החזרה

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

דוגמאות

*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

פורמטים

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

• הפורמטים משנים רק את הערכים המפורמטים, ולא את הערכים הבסיסיים. לדוגמה, הערך שיוצג יהיה 4,000.00 ש"ח אבל הערך הבסיסי עדיין יהיה 1,000.
• הפורמטים משפיעים על עמודה אחת בלבד בכל פעם. כדי לעצב מחדש מספר עמודות, יש להחיל פורמט על כל עמודה שרוצים לשנות.
• אם אתם משתמשים גם ברכיבי פורמט בהגדרת המשתמש, פריטי עיצוב מסוימים של Google Vision יעקפו את כל סוגי העיצוב בהגדרת המשתמש.

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

 

ה-Google Visualization API מספק את הפורמטים הבאים:

שם העיצוב	תיאור
חץ עיצוב	מוסיף חץ למעלה או למטה, שמציין אם ערך התא הוא מעל או מתחת לערך שצוין.
BarFormat	הפונקציה מוסיפה עמודה צבעונית, שהכיוון והצבע שלה קובעים אם ערך התא הוא מעל או מתחת לערך שצוין.
צבעפורמט	צובע תא לפי אם הערכים נמצאים בטווח מסוים.
פורמט תאריך	מעצב ערך של תאריך או תאריך במספר דרכים שונות, כולל, "1 בינואר 2009", "1 בינואר 2009" ו"1 בינואר 2009".
NumberNumber	עיצוב היבטים שונים של ערכים מספריים.
קו ביטול נעילה	משרשרת ערכי תאים באותה שורה לתא שצוין, יחד עם טקסט שרירותי.

פורמט חץ

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

אפשרויות

ArrowFormat תומך באפשרויות הבאות, שהועברו לבנאי:

אפשרות	תיאור
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 תומך באפשרויות הבאות, שהועברו לבנאי:

אפשרות	דוגמה תיאור
base	מספר שהוא ערך הבסיס שאליו יש להשוות את ערך התא. אם הערך של התא גבוה, הוא יואר מימין לבסיס, ואם הוא נמוך יותר, הוא יוצמד לשמאל. ערך ברירת המחדל הוא 0.
colorNegative	מחרוזת שמציינת את החלק של הערך השלילי בעמודות. הערכים האפשריים הם 'אדום', 'ירוק' ו'כחול'. ערך ברירת המחדל הוא 'אדום'.
colorPositive	מחרוזת המציינת את הצבע של קטע הערך החיובי של עמודות. הערכים האפשריים הם 'אדום', 'ירוק' ו'כחול'. ברירת המחדל היא 'כחול'.
drawZeroLine	ערך בוליאני שמציין אם לצייר קו בסיס כהה של פיקסל אחד כאשר קיימים ערכים שליליים. הקו הכהה מופיע שם כדי לשפר את הסריקה החזותית של העמודות. ערך ברירת המחדל הוא 'FALSE'.
max	ערך המספר המקסימלי של טווח העמודות. ערך ברירת המחדל הוא הערך הגבוה ביותר בטבלה.
min	ערך המספר המינימלי עבור טווח העמודות. ערך ברירת המחדל הוא הערך הנמוך ביותר בטבלה.
showValue	אם True, מציג ערכים ועמודות. אם False, מוצגים רק עמודות. ערך ברירת המחדל הוא 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%'});

צבע

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

שיטות

ColorFormat תומך בשיטות הבאות:

שיטה	תיאור
google.visualization.ColorFormat()	בונה. לא מקבלת ארגומנטים.
addRange(from, to, color, bgcolor)	מציינת את צבע החזית ו/או צבע הרקע של תא, בהתאם לערך של התא. לכל תא עם ערך בטווח שצוין מ-from עד to יוקצו color ו-bgcolor. חשוב להבין שהטווח אינו כולל, מפני שיצירת טווח של 1-1,000 ושנייה מ-1,000— 2,000 לא תאפשר התבטאות בערך של 1,000. from - [מחרוזת, מספר, תאריך, תאריך ושעה או שעה] הגבול התחתון (כולל) של הטווח, או ריק. אם הערך הוא null, הוא יהיה תואם ל- - . . מחרוזות מחרוזת מושוויות לפי סדר אלפביתי של ערכי המחרוזת. to - [מחרוזת, מספר, תאריך, תאריך ושעה או שעה] הגבול העליון (לא כולל) את הטווח, או ריק. אם הערך הוא null, הוא יהיה תואם ל-+. הגבולות של מחרוזת מושווים לפי סדר אלפביתי ביחס לערכי המחרוזת. color - הצבע שיש להחיל על הטקסט בתאים התואמים. הערכים יכולים להיות ערכי ' #RRGGBB' או קבועים קבועים של צבע, (לדוגמה: ' #FF0000' או 'red'). bgcolor – הצבע שרוצים להחיל על הרקע של תאים תואמים. הערכים יכולים להיות ' #RRGGBB' או ערכים קבועים של צבע, (לדוגמה: ' #FF0000' או 'red').
addGradientRange(from, to, color, fromBgColor, toBgColor)	הקצאה של צבע רקע מטווח בהתאם לערך התא. קנה המידה של הצבע מותאם לערך של התא בטווח מצבע גבול תחתון לצבע של גבול עליון. חשוב לשים לב שהשיטה הזו לא תוכל להשוות ערכי מחרוזת, כמו ש-addRange() יכול לעשות. טיפ: לרוב, הצופים יתקשו להעריך במדויק את טווחי הצבעים. הטווח הפשוט והקל ביותר לקריאה הוא מצבע רווי לחלוטין ללבן (למשל, #FF0000–FFFFFF). from – [Number, Date, DateTime, TimeTimeDay] הגבול התחתון (כולל) של הטווח, או null. אם הערך הוא null, הוא יתאים ל- -✘. to - [Number, Date, DateTime, TimeTimeDay] הגבול העליון (לא כולל) של הטווח, או null. אם הערך הוא null, הוא יתאים ל-+AUD. color - הצבע שיש להחיל על הטקסט בתאים התואמים. הצבע הזה זהה בכל התאים, בלי קשר לערך שלהם. 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%'});

פורמט התאריך

הפורמט של ערך Date ב-JavaScript מגוונות, כולל "1 בינואר 2016", "1 בינואר 2016" ו-"1 בינואר 2016".

אפשרויות

DateFormat תומך באפשרויות הבאות, שהועברו לבנאי:

אפשרות	תיאור
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	אזור הזמן שבו יש להזין את ערך התאריך. זהו ערך מספרי שמציין את GMT + את מספר אזורי הזמן הזה (יכול להיות שלילי). אובייקט תאריך נוצר כברירת מחדל עם אזור הזמן המשוער של המחשב שבו הן נוצרו. אפשרות זו משמשת להצגת הערך הזה באזור זמן אחר. לדוגמה, אם יצרתם אובייקט בתאריך 17:00 במחשב ששוכן בגריניץ', אנגליה, ובזמן שצוין באזור זמן של -5 (options['timeZone'] = -5, או באזור זמן מזרח האוקיינוס השקט בארה"ב), הערך שיוצג היה 12 בצהריים.

שיטות

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

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

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

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

דוגמת קוד	תיאור	פלט לדוגמה
GG	מעצב תקופות.	"מודעה"
yy או yyyy	לשנה.	1996
משחקים	החודש בשנה. בינואר: M מייצר 1 MM מפיק 01 MMM מפיקה את ינואר MMMM הפקת ינואר	"יולי" "07"
י'	היום בחודש. ערכי 'd' מיותרים יגרמו להוספה של אפסים בתחילת המספר.	10
h	קנה מידה ב-12 שעות. ערכי 'h' מיותרים יגרמו להוספה של אפסים בתחילת המספר.	12
ג'	שעה בסולם של 24 שעות. ערכי Hk נוספים יגרמו להוספת אפסים בתחילת המספר.	0
m	דקות בשעה. ערכי 'M' נוספים יגרמו להוספה של אפסים בתחילת המספר.	30
s	השניה בעוד דקה. הוספת ערכי '' תוסיף אפסים בתחילת המספר.	55
א	שנייה קטנה. ערכי 'S' נוספים ייתווספו מימין עם אפסים.	978
ה'	היום בשבוע. התוצאות הבאות עבור "יום שלישי": 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 תומך באפשרויות הבאות, שהועברו לבנאי:

אפשרות	תיאור
decimalSymbol	תו שישמש כסמן עשרוני. ברירת המחדל היא נקודה (.).
fractionDigits	מספר המציין כמה ספרות יש להציג אחרי הנקודה העשרונית. ברירת המחדל היא 2. אם מזינים יותר ספרות מהמספר שמופיע, יוצגו אפסים לערכים הקטנים יותר. הערכים שנחתכו יעוגלו (5 כלפי מעלה).
groupingSymbol	תו שישמש לקיבוץ ספרות משמאל לסימן העשרוני במספרים של שלוש. ברירת המחדל היא פסיק (,).
negativeColor	צבע הטקסט של ערכים שליליים. לא הוגדר ערך ברירת מחדל הערכים יכולים להיות כל ערך צבע HTML קביל, כגון "אדום" או " #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)	מחזירה את הערך המפורמט של ערך נתון. השיטה הזו לא מחייבת 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%'});

קו ביטול נעילה

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

שיטות

PatternFormat תומך בשיטות הבאות:

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

עזרה גאדג'ט

מחלקה שעוזרת לפשט את הכתיבה של גאדג'טים שמשתמשים ב-Google Visualization 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 Sheets.

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

שאילתה

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

יצרן

google.visualization.Query(dataSourceUrl, opt_options)

פרמטרים

dataSourceUrl

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

opt_options

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

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

שיטות

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

תגובה לשאילתה

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

שיטות

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

הצגת שגיאה

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

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

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

ניתן לראות דוגמה לשגיאה מותאמת אישית בדוגמה לדף מעטפת של שאילתה.

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

אירועים

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

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

• 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 ל-listener החדש. אם נדרש, אפשר להשתמש ב-handler כדי להסיר אותו מאוחר יותר על ידי קריאה ל-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()

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

google.visualization.events.removeListener(listener_handler)

listener_handler

ה-handler של ההאזנה להסרה, בהתאם לחזרה על ידי google.visualization.events.addListener().

removeAllListeners()

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

google.visualization.events.removeAllListeners(source_visualization)

source_visualization

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

trigger()

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

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

source_visualization

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

event_name

שם מחרוזת לחיוג לאירוע. אפשר לבחור כל מחרוזת שרוצים.

event_args

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

דוגמה

זוהי דוגמה להמחשה של שיטה שנקראת "select" (בחירה) כאשר מתבצעת קריאה לשיטה onclick. הוא לא מחזיר ערכים.

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.

בונה

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

visualization_class_name(dom_element)

dom_element

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

דוגמה

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

טיוטה()

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

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

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

צריך להגדיר את כל הפעולות בהסבר הקצר לפני הקריאה לשיטה 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');
  }
});

אפשר להגדיר בשיטה 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()

אפשר לבחור רשומת נתונים בוויזואליזציה - לדוגמה, נקודה בתרשים שטח או עמודה בתרשים עמודות. כשקוראים לשיטה הזו, התצוגה החזותית צריכה לציין בצורה חזותית את הבחירה החדשה. ההטמעה של 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'}, כלומר {label: 'Start Date', type: 'date'}. אפשר גם להשתמש בתפקידים אופציונליים של נתונים, אבל יש להגדיר אותם במפורש באמצעות סימון אובייקט מילולי. אפשר להשתמש בסימון מילולי של אובייקט גם בכל תא, כדי להגדיר אובייקטים סלולריים).

תחביר

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

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

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);

drawingsChart()

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

תחביר

google.visualization.drawChart(chart_JSON_or_object)

chart_JSON_or_object

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

מאפיין (property)	סוג	נדרש	ברירת מחדל	תיאור
סוג תרשים	String	נדרש	ללא	שם הסיווג. לא ניתן להשמיט את שם החבילה google.visualization בתרשימים של Google. אם ספריית ההצגה החזותית המתאימה לא נטענה עדיין, השיטה הזו תטען את הספרייה עבורך אם זוהי הצגה חזותית של Google, וצריך לטעון רכיבים חזותיים של צד שלישי באופן מפורש. דוגמאות: Table, PieChart, example.com.CrazyChart.
מזהה מאגר	String	נדרש	ללא	המזהה של רכיב ה-DOM בדף שמארח את התצוגה החזותית.
אפשרויות	התנגדות	אופציונלי	ללא	אובייקט שמתאר את האפשרויות של הצגת הנתונים. אפשר להשתמש בסימון מילולי של JavaScript, או לתת לו כינוי. דוגמה: "options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
טבלת נתונים	התנגדות	אופציונלי	ללא	השדה DataTable שמשמש לאכלוס התצוגה. כאן יכול להיות ייצוג מילולי של מחרוזת JSON של DataTable, כמתואר מעל, או כינוי לאובייקט google.visualization.DataTable מאוכלס, או מערך דו-מימדי כמו המקובל על arrayToDataTable(opt_firstRowIsData=false) . עליך לציין את הנכס הזה או את המאפיין dataSourceUrl.
dataSourceUrl	String	אופציונלי	ללא	שאילתה של מקור נתונים כדי לאכלס את נתוני התרשים (לדוגמה, גיליון אלקטרוני של Google). עליך לציין את הנכס הזה או את הנכס dataTable.
שאילתה	String	אופציונלי	ללא	אם מציינים dataSourceUrl, אפשר לציין מחרוזת שאילתה דמוית SQL באמצעות שפת השאילתות החזותית כדי לסנן את הנתונים או לשנות אותם.
רענון-מרווח	מספר	אופציונלי	ללא	התדירות שבה מילות המפתח צריכות לרענן את מקור השאילתה. יש להשתמש במאפיין הזה רק כשמציינים את 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>

drawסרגל הכלים()

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