בדף הזה מפורטים האובייקטים שנחשפים על ידי Google Visualization API, והשיטות הסטנדרטיות שמוצגות על ידי כל הרכיבים החזותיים.
הערה: מרחב השמות של Google Visualization API הוא
google.visualization.*
הערה לגבי מערכים
דפדפנים מסוימים אינם מטפלים כראוי בפסיקים שנגרמים במערכי 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
באמצעות קריאה לבנאי ללא פרמטרים
והוספת ערכים על ידי קריאה לשיטות addColumn()
/
addRows()
המפורטות בהמשך, או על ידי העברת
אובייקט ליטרל של JavaScript מאוכלס כדי להפעיל אותו. שתי השיטות מתוארות בהמשך. באיזה מהם
כדאי להשתמש?
-
כדי ליצור טבלה ולאכלס טבלה ב-JavaScript, אפשר להפעיל את הקוד
addColumn()
,addRow()
וגםaddRows()
. השיטה הזו שימושית כשמזינים קוד באופן ידני. הוא איטי יותר משימוש בסימון אובייקט מילולי (כפי שמתואר בהמשך), אבל בטבלאות קטנות יותר (למשל, 1,000 תאים), סביר להניח שלא יהיה הבדל משמעותי. -
ההצהרה הישירה של האובייקט
DataTable
באמצעות סימון מילולי של אובייקטים מהירה הרבה יותר בטבלאות גדולות. עם זאת, שגיאות תחביר יכולות להיות מסובכות. כדאי להשתמש באפשרות הזו אם אפשר ליצור בקוד את התחביר המילולי של האובייקט. כך פוחת הסיכוי לשגיאות.
שיטות
שיטה | ערך החזרה | תיאור |
---|---|---|
או
|
מספר |
הוספת עמודה חדשה לטבלת הנתונים, והחזרת האינדקס של העמודה החדשה. לכל התאים
בעמודה החדשה מוקצה ערך החתימה הראשונה כוללת את הפרמטרים הבאים:
החתימה השנייה מכילה פרמטר אובייקט יחיד עם החברים הבאים:
למידע נוסף: getColumnId, getColumnLabel, getColumnType, insertColumn, getColumnRole |
addRow(opt_cellArray) |
מספר |
הוספת שורה חדשה לטבלת הנתונים והחזרת השורה של השורה החדשה.
לדוגמה: 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) |
מספר |
הוספה של שורות חדשות לטבלת הנתונים, והחזרת השורה של השורה האחרונה שהוספת. אפשר לקרוא לשיטה הזו כדי ליצור שורות חדשות ריקות או באמצעות נתונים לאכלוס השורות, כפי שמתואר בהמשך.
דוגמה: 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 |
מחזירה את דפוס העיצוב המשמש לעיצוב הערכים של העמודה שצוינה.
לטבלאות נתונים שאוחזרו על ידי שאילתות, תבנית העמודה מוגדרת על ידי מקור הנתונים, או לפי הקטע |
getColumnProperties(columnIndex)
|
התנגדות |
מחזירה מפה של כל המאפיינים בעמודה שצוינה. הערה: אובייקט המאפיינים מוחזר על ידי הפניה, כך ששינוי הערכים באובייקט המאוחזר משנה אותם ב-
|
getColumnProperty(columnIndex, name)
|
אוטומטית |
מחזירה את הערך של מאפיין בעל שם, או
מידע נוסף: setColumnProperty setColumnProperties |
getColumnRange(columnIndex) |
התנגדות |
מחזירה את ערכי המינימום והמקסימום של ערכים בעמודה נתונה. לאובייקט שהוחזר יש מאפיינים
הערך של |
getColumnRole(columnIndex) |
String | מחזירה את התפקיד של העמודה שצוינה. |
getColumnType(columnIndex) |
String |
מחזירה את סוג העמודה שצוינה על ידי אינדקס העמודה.
סוג העמודה שהוחזרה יכול להיות אחת מהאפשרויות הבאות: |
getDistinctValues(columnIndex) |
מערך אובייקטים |
מחזירה את הערכים הייחודיים בעמודה מסוימת, בסדר עולה.
סוג האובייקטים המוחזרים זהה לסוג האובייקטים המוחזרים
בשיטת |
getFilteredRows(filters) |
מערך אובייקטים |
מחזירה את האינדקסים של השורות לשורות שתואמות לכל המסננים הנתונים. האינדקסים חוזרים
בסדר עולה. הפלט של השיטה הזו יכול לשמש כקלט
ל-
מאפיין אופציונלי נוסף,
דוגמה: הפונקציה |
getFormattedValue(rowIndex, columnIndex)
|
String |
מחזירה את הערך המפורמט של התא באינדקסים של השורה והעמודה.
למידע נוסף על עיצוב ערכים של עמודות, אפשר לעיין בחומר העזר בנושא שפת השאילתות. למידע נוסף: setFormattedValue |
getNumberOfColumns() |
מספר | מחזירה את מספר העמודות בטבלה. |
getNumberOfRows() |
מספר | מחזירה את מספר השורות בטבלה. |
getProperties(rowIndex, columnIndex)
|
התנגדות |
מחזירה מפה של כל המאפיינים בתא שצוין. חשוב לשים לב שהאובייקט של המאפיין מוחזר על ידי הפניה, כך ששינוי הערכים באובייקט המאוחזר משנה אותם ב-
|
getProperty(rowIndex, columnIndex, name)
|
אוטומטית |
מחזירה את הערך של מאפיין בעל שם, או
מידע נוסף: setCell setProperty setProperty |
getRowProperties(rowIndex)
|
התנגדות |
מחזירה מפה של כל המאפיינים בשורה שצוינה. הערה: אובייקט המאפיינים מוחזר על ידי הפניה, כך ששינוי הערכים באובייקט המאוחזר משנה אותם ב-
|
getRowProperty(rowIndex, name)
|
אוטומטית |
מחזירה את הערך של מאפיין בעל שם, או
למידע נוסף: setRowProperty setRowProperty |
getSortedRows(sortColumns) |
מערך של מספרים |
מחזירה גרסה ממוינת של הטבלה מבלי לשנות את סדר הנתונים הבסיסיים.
כדי למיין באופן סופי את הנתונים הבסיסיים צריך להתקשר אל
הערך המוחזר הוא מערך של מספרים, וכל מספר הוא אינדקס של שורה
חשוב לזכור שהמיון מובטח להיות יציב: כלומר, אם ממוינים לפי ערכים שווים של שתי שורות, אותו מיון יחזיר את השורות באותו הסדר בכל פעם. דוגמה: כדי לחזור על שורות המסודרות לפי העמודה השלישית, יש להשתמש ב: var rowInds = data.getSortedRows([{column: 2}]); for (var i = 0; i < rowInds.length; i++) { var v = data.getValue(rowInds[i], 2); } |
getTableProperties
|
התנגדות | מחזירה מפה של כל המאפיינים בטבלה. |
getTableProperty(name) |
אוטומטית |
מחזירה את הערך של מאפיין בעל שם, או
למידע נוסף: setTableProperties setTableProperty |
getValue(rowIndex, columnIndex) |
התנגדות |
מחזירה את הערך של התא באינדקסים של השורה והעמודה.
סוג הערך המוחזר תלוי בסוג העמודה (ראו getColumnType):
|
insertColumn(columnIndex, type [,label [,id]])
|
ללא |
הוספת עמודה חדשה לטבלת הנתונים, באינדקס שצוין. כל העמודות הקיימות באינדקס שצוין או אחריו הועברו לאינדקס גבוה יותר.
ראו גם: addColumn |
insertRows(rowIndex, numberOrArray) |
ללא |
מוסיפים את מספר השורות שצוין באינדקס השורות שצוין
למידע נוסף: addRows |
removeColumn(columnIndex) |
ללא |
פונקציה זו מסירה את העמודה מהאינדקס שצוינה.
למידע נוסף: removeעמודות |
removeColumns(columnIndex, numberOfColumns)
|
ללא |
פונקציה זו מסירה את מספר העמודות שצוין החל מהעמודה באינדקס שצוין.
ראו גם: removeColumn |
removeRow(rowIndex) |
ללא |
פונקציה זו מסירה את השורה מהאינדקס שצוינה.
ראו גם: removeRows |
removeRows(rowIndex, numberOfRows) |
ללא |
פונקציה זו מסירה את מספר השורות שצוין החל מהשורה באינדקס שצוין.
ראו גם: removeRow |
setCell(rowIndex, columnIndex [, value [, formattedValue [, properties]]])
|
ללא |
מגדירה את הערך, הערך בפורמט או המאפיינים של תא.
מידע נוסף זמין במאמר הבא: setValue(), setFormattedValue() , setProperty() , setProperty() . |
setColumnLabel(columnIndex, label)
|
ללא |
הגדרת תווית של עמודה.
למידע נוסף: getColumnLabel |
setColumnProperty(columnIndex, name, value)
|
ללא |
מגדיר מאפיין בעמודה אחת. חלק מהרכיבים החזותיים תומכים במאפייני שורות, עמודות או תאים כדי לשנות את התצוגה או את ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד.
מידע נוסף:setColumnProperties getColumnProperty |
setColumnProperties(columnIndex, properties)
|
ללא |
הגדרה של מאפייני עמודות מרובים. חלק מהרכיבים החזותיים תומכים במאפייני שורות, עמודות או תאים כדי לשנות את התצוגה או את ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד.
מידע נוסף: setColumnProperty getColumnProperty |
setFormattedValue(rowIndex, columnIndex, formattedValue)
|
ללא |
מגדיר את הערך המפורמט של תא.
ראו גם: getFormattedValue |
setProperty(rowIndex, columnIndex, name, value)
|
ללא |
מגדיר מאפיין של תא. חלק מהרכיבים החזותיים תומכים במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד.
מידע נוסף: setCell setProperty getProperty |
setProperties(rowIndex, columnIndex, properties)
|
ללא |
הגדרה של מספר מאפייני תאים. חלק מהרכיבים החזותיים תומכים במאפייני שורות, עמודות או תאים כדי לשנות את התצוגה או את ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד.
מידע נוסף: setCell setProperty getProperty |
setRowProperty(rowIndex, name, value)
|
ללא |
מגדיר מאפיין שורה. חלק מהרכיבים החזותיים תומכים במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או ההתנהגות שלהם. לקבלת מידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד.
למידע נוסף: setRowProperty getRowProperty |
setRowProperties(rowIndex, properties)
|
ללא |
הגדרה של מספר מאפייני שורה. חלק מהרכיבים החזותיים תומכים במאפיינים של שורה, עמודה או תא כדי לשנות את התצוגה או ההתנהגות שלהם. למידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד.
למידע נוסף: setRowProperty getRowProperty |
setTableProperty(name, value)
|
ללא |
מגדיר נכס טבלה יחיד. חלק מהרכיבים החזותיים תומכים במאפיינים של טבלה, שורה, עמודה או תא כדי לשנות את התצוגה או ההתנהגות שלהם; למידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד.
למידע נוסף: setTableProperties getTableProperty |
setTableProperties(properties) |
ללא |
הגדרה של מספר מאפייני טבלה. חלק מהרכיבים החזותיים תומכים במאפיינים של טבלה, שורה, עמודה או תא כדי לשנות את התצוגה או ההתנהגות שלהם; למידע על המאפיינים הנתמכים, יש לעיין במסמכי התיעוד.
למידע נוסף: setTableProperty getTableProperty |
setValue(rowIndex, columnIndex, value) |
ללא |
מגדירה את הערך של תא. מעבר להחלפת ערך קיים של תא, השיטה הזו תמחק גם את כל הערכים והמאפיינים של התא.
למידע נוסף: 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]
-
'boolean' – ערך בוליאני של JavaScript ('true' או 'false'). ערך לדוגמה:
-
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
מכיל מערך של אובייקטים בשורה.
לכל אובייקט בשורה יש מאפיין חובה אחד בשם 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.
שיטות
שיטה | ערך החזרה | תיאור |
---|---|---|
הצגת התיאורים בשפה DataTable . |
כמו בשיטות המקבילות של DataTable , למעט אלה ששורות/עמודות מתווספות לאינדקס מתייחסות לאינדקס בתצוגה המפורטת ולא לטבלה/לתצוגה המפורטת הבסיסיות.
|
|
getTableColumnIndex(viewColumnIndex)
|
מספר |
מחזירה את האינדקס בטבלה או (בתצוגה) של עמודה נתונה שצוינה עבור האינדקס בתצוגה זו. הערך של
דוגמה: אם בוצעה קריאה לפונקציה |
getTableRowIndex(viewRowIndex) |
מספר |
מחזירה את האינדקס בטבלה או (בתצוגה) של שורה נתונה שצוינה באינדקס שלה בתצוגה זו. הערך של
דוגמה: אם בוצעה קריאה לפונקציה |
getViewColumnIndex(tableColumnIndex)
|
מספר |
הפונקציה מחזירה את האינדקס בתצוגה המפורטת הזו, הממפה לעמודה נתונה שצוינה באינדקס שלה בטבלה הבסיסית (או בתצוגה המפורטת). אם קיים יותר מאינדקס אחד, הפונקציה מחזירה את האינדקס הראשון (הקטן ביותר). אם לא קיים אינדקס כזה (העמודה שצוינה לא נמצאת בתצוגה המפורטת), מחזירה -1.
הערך של
דוגמה: אם בוצעה קריאה לפונקציה |
getViewColumns() |
מערך של מספרים |
מחזירה את העמודות בתצוגה הזו לפי הסדר. כלומר, אם מתקשרים ל- |
getViewRowIndex(tableRowIndex) |
מספר |
הפונקציה מחזירה את האינדקס בתצוגה המפורטת הזו, הממפה לשורה נתונה שצוינה על ידי האינדקס שלו בטבלה (או בתצוגה) הבסיסית. אם קיים יותר מאינדקס אחד, הפונקציה מחזירה את האינדקס הראשון (הקטן ביותר). אם לא קיים אינדקס כזה (השורה שצוינה אינה בתצוגה), מחזירה -1.
הערך של
דוגמה: אם בוצעה קריאה לפונקציה |
getViewRows() |
מערך של מספרים |
פונקציה זו מחזירה את השורות בתצוגה הזו לפי הסדר. כלומר, אם מתקשרים ל- |
hideColumns(columnIndexes) |
ללא |
הסתרת העמודות שצוינו מהתצוגה הנוכחית.
דוגמה: אם יש לכם טבלה עם 10 עמודות, ואתם מתקשרים ל- |
hideRows(min, max) |
ללא |
מסתיר את כל השורות עם אינדקסים הנמצאים בין מינימום למקסימום (כולל) מהתצוגה הנוכחית.
זהו תחביר נוחות של |
hideRows(rowIndexes) |
ללא |
הסתרת השורות שצוינו מהתצוגה הנוכחית.
דוגמה: אם יש לכם טבלה עם 10 שורות, ואתם קוראים ל- |
setColumns(columnIndexes) |
ללא |
מציינת אילו עמודות גלויות בתצוגה הזו. עמודות שלא צוינו יוסתרו. זהו מערך של אינדקסים של עמודות בטבלה/תצוגה הבסיסית, או עמודות מחושבות. אם לא קוראים לשיטה הזו, ברירת המחדל היא להציג את כל העמודות. המערך יכול להכיל גם כפילויות, כדי להציג את אותה עמודה כמה פעמים. העמודות יוצגו לפי הסדר שבו הן צוינו.
דוגמאות: // 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) |
ללא |
הגדרת השורות הגלויות בתצוגה הזו, על סמך מספרי האינדקס מהטבלה/התצוגה המפורטת הבסיסיות.
השדה
דוגמה: כדי ליצור תצוגה מפורטת עם השורות 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) |
ללא |
משרטט את התרשים. עליכם לקרוא לשיטה הזו לאחר ביצוע שינויים בתרשים או בנתונים כדי להציג את השינויים.
|
toJSON() |
String | מחזירה גרסת מחרוזת של ייצוג ה-JSON של התרשים. |
clone() |
wrapper של תרשים | מחזירה עותק עמוק של Wrapper של התרשים. |
getDataSourceUrl() |
String | אם התרשים מקבל את הנתונים שלו ממקור נתונים, מוחזרת כתובת ה-URL של מקור הנתונים הזה. אחרת, מחזירה null. |
getDataTable() |
google.visualization.DataTable |
אם התרשים הזה מקבל את הנתונים שלו מתוך
השינויים שיבוצעו באובייקט שהוחזר ישתקפו בתרשים בפעם הבאה שמתקשרים אל |
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) |
כל סוג |
החזרת הערך של אפשרות התרשים שצוינה
|
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:
-
טוענים את החבילה של
charteditor
. ב-google.charts.load()
, יש לטעון את החבילה 'chartEditor'. אין צורך לטעון את החבילות של סוג התרשים שמעבדים בעורך. הכלי לעריכת טבלאות יטען את כל חבילות הנתונים לפי הצורך. -
יצירת אובייקט מסוג
ChartWrapper
שמגדיר את התרשים של המשתמש לצורך התאמה אישית. התרשים הזה יוצג בתיבת הדו-שיח, והמשתמש ישתמש בעורך כדי לעצב מחדש את התרשים, לשנות את סוגי התרשימים ואפילו לשנות את נתוני המקור. -
יוצרים מופע חדש של ChartEditor ונרשמים כדי להאזין לאירוע "אישור". האירוע הזה נזרק כשהמשתמש לוחץ על הלחצן 'אישור' בתיבת הדו-שיח. לאחר השליחה, יש להתקשר אל
ChartEditor.getChartWrapper()
כדי לאחזר את התרשים ששונה על ידי המשתמש. -
התקשרות אל
ChartEditor.openDialog()
ועוברת בChartWrapper
. הפעולה הזו פותחת את תיבת הדו-שיח. לחצני הדו-שיח מאפשרים למשתמש לסגור את העורך. המופע שלChartEditor
זמין כל עוד הוא קיים בהיקף. הוא לא מושמד באופן אוטומטי אחרי שהמשתמש סוגר את תיבת הדו-שיח. - כדי לעדכן את התרשים בקוד, יש להתקשר למספר
setChartWrapper()
.
שיטות
שיטה | ערך החזרה | תיאור |
---|---|---|
openDialog(chartWrapper, opt_options) |
null |
פתיחת עורך התרשימים כתיבת דו-שיח מוטמעת בדף. הפונקציה חוזרת
באופן מיידי. היא לא ממתינה לתיבת הדו-שיח לסגירה. אם לא מאבדים את היקף המכונה, אפשר להפעיל מחדש את
|
getChartWrapper() |
ChartWrapper |
הפונקציה מחזירה ChartWrapper שמייצג את התרשים, בתוספת שינויים של משתמשים. |
setChartWrapper(chartWrapper) |
null |
אפשר להשתמש בשיטה הזו כדי לעדכן את התרשים המעובד בעורך.
chartWrapper – אובייקט |
closeDialog() |
null | סגירת תיבת הדו-שיח של עורך התרשימים. |
אפשרויות
עורך התרשימים תומך באפשרויות הבאות:
שם | סוג | ברירת מחדל | תיאור |
---|---|---|---|
dataSourceInput |
מזהה רכיב או 'urlbox' | null |
בעזרת הערך הזה המשתמשים יכולים לציין מקור נתונים לתרשים. המאפיין הזה יכול להיות אחד משני ערכים:
|
אירועים
עורך התרשימים מציג את האירועים הבאים:
שם | תיאור | נכסים |
---|---|---|
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 יעקפו את כל סוגי העיצוב בהגדרת המשתמש.
- קבלת האובייקט
DataTable
שלך. - בכל עמודה שרוצים לפרמט מחדש:
- יוצרים אובייקט שמציין את כל האפשרויות עבור הפירמוט שלכם. זהו אובייקט JavaScript בסיסי עם קבוצה של מאפיינים וערכים. במסמכי התיעוד של הפורמט שלך מפורטים אילו מאפיינים נתמכים. (לחלופין, אפשר להעביר אובייקט ליטרל אובייקט שמציין את האפשרויות שלך).
- יוצרים את הפורמט הרצוי ומעבירים אותו לאובייקט האפשרויות.
-
אפשר להתקשר למספר
formatter
.format(table, colIndex)
על ידי הזנת המספרDataTable
בעמודה (המבוססת על אפס) של הנתונים שרוצים לעצב מחדש. לתשומת ליבך: אפשר להחיל עיצוב אחד בלבד על כל עמודה. החלה של עיצוב שני פשוט תחליף את ההשפעות של העמודה הראשונה.
חשוב: הרבה מעצבי גופנים צריכים תגי HTML כדי להציג פורמט מיוחד. אם התצוגה החזותית תומכת באפשרות שלallowHtml
, צריך להגדיר אותה כ-true.
העיצוב בפועל המיושם על הנתונים נגזר מהאזור שבו ה-API נטען. לפרטים נוספים, אפשר לקרוא את המאמר טעינת תרשימים עם שפה או אזור ספציפיים .
חשוב: אפשר להשתמש בפורמטים רק ב-DataTable
, ולא ניתן להשתמש בהם עם DataView
(אובייקטים של DataView
הם לקריאה בלבד).
לפניכם השלבים הכלליים לשימוש בכלי לעיצוב:
הנה דוגמה לשינוי ערכי התאריך בפורמט של עמודת תאריך כך שישתמש בפורמט ארוך ("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 הוא שם מעצב מיוחד.
// 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) |
מעצב מחדש את הנתונים בעמודה שצוינה.
|
ה-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.
|
addGradientRange(from, to, color, fromBgColor,
toBgColor)
|
הקצאה של צבע רקע מטווח בהתאם לערך התא. קנה המידה של הצבע מותאם
לערך של התא בטווח מצבע גבול תחתון לצבע של
גבול עליון. חשוב לשים לב שהשיטה הזו לא תוכל להשוות ערכי מחרוזת, כמו ש-
|
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, כפי שמוצג:
לא ניתן לציין גם |
pattern |
דפוס פורמט מותאם אישית עבור הערך, בדומה לפורמט התאריך והשעה של ICU.
לדוגמה:
לא ניתן לציין גם |
timeZone |
אזור הזמן שבו יש להזין את ערך התאריך. זהו ערך מספרי שמציין את GMT + את מספר אזורי הזמן הזה (יכול להיות שלילי). אובייקט תאריך נוצר כברירת מחדל עם
אזור הזמן המשוער של המחשב שבו הן נוצרו. אפשרות זו משמשת להצגת
הערך הזה באזור זמן אחר. לדוגמה, אם יצרתם אובייקט בתאריך 17:00
במחשב ששוכן בגריניץ', אנגליה, ובזמן שצוין באזור זמן של -5
(options['timeZone'] = -5 , או באזור זמן מזרח האוקיינוס השקט בארה"ב), הערך
שיוצג היה 12 בצהריים.
|
שיטות
DateFormat
תומך בשיטות הבאות:
שיטה | תיאור |
---|---|
google.visualization.DateFormat(options) |
בונה. מידע נוסף מפורט בסעיף שלמעלה. |
format(dataTable, columnIndex) |
השיטה הרגילה של format() להחלת העיצוב על העמודה שצוינה. |
formatValue(value) |
מחזירה את הערך המפורמט של ערך נתון.
השיטה הזו לא מחייבת |
קוד לדוגמה
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 |
משחקים |
החודש בשנה. בינואר:
|
"יולי" "07" |
י' | היום בחודש. ערכי 'd' מיותרים יגרמו להוספה של אפסים בתחילת המספר. | 10 |
h | קנה מידה ב-12 שעות. ערכי 'h' מיותרים יגרמו להוספה של אפסים בתחילת המספר. | 12 |
ג' | שעה בסולם של 24 שעות. ערכי Hk נוספים יגרמו להוספת אפסים בתחילת המספר. | 0 |
m | דקות בשעה. ערכי 'M' נוספים יגרמו להוספה של אפסים בתחילת המספר. | 30 |
s | השניה בעוד דקה. הוספת ערכי '' תוסיף אפסים בתחילת המספר. | 55 |
א | שנייה קטנה. ערכי 'S' נוספים ייתווספו מימין עם אפסים. | 978 |
ה' |
היום בשבוע. התוצאות הבאות עבור "יום שלישי":
|
"שלישי" "יום שלישי" |
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 |
מחרוזת פורמט. אם צוין אחרת, המערכת תתעלם מכל שאר האפשרויות, מלבד
מחרוזת הפורמט היא קבוצת משנה של
קבוצת תבניות של ICU
.
לדוגמה, המאפיין |
prefix |
קידומת מחרוזת עבור הערך, לדוגמה "$". |
suffix |
סיומת מחרוזת עבור הערך, לדוגמה "%". |
שיטות
NumberFormat
תומך בשיטות הבאות:
שיטה | תיאור |
---|---|
google.visualization.NumberFormat(options) |
בונה. מידע נוסף מפורט בסעיף שלמעלה. |
format(dataTable, columnIndex) |
השיטה הרגילה format() להחלת עיצוב על העמודה שצוינה. |
formatValue(value) |
מחזירה את הערך המפורמט של ערך נתון. השיטה הזו לא מחייבת
|
קוד לדוגמה
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 הם
קוד לדוגמהבדוגמה הבאה מוצג מבנה עבור דפוס שיוצר רכיב עוגן, כאשר הרכיב הראשון והשני נלקחים מהשיטה var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>'); |
format(dataTable, srcColumnIndices,
opt_dstColumnIndex)
|
הקריאה לפורמט הרגיל, עם כמה פרמטרים נוספים:
בטבלה הבאה מוצגות דוגמאות לעיצוב. |
לפניכם כמה דוגמאות לקלט ולפלט של טבלה עם ארבע עמודות.
Row before formatting (4 columns, last is blank): John | Paul | Jones | [empty] var formatter = new google.visualization.PatternFormat("{0} {1} {2}"); formatter.format(data, [0,1,2], 3); Output: John | Paul | Jones | John Paul Jones var formatter = new google.visualization.PatternFormat("{1}, {0}"); formatter.format(data, [0,2], 3); Output: John | Paul | Jones | Jones, John
קוד לדוגמה
הדוגמה הבאה ממחישה איך לשלב נתונים משתי עמודות כדי ליצור כתובת אימייל. היא משתמשת באובייקט DataView כדי להסתיר את עמודות המקור המקוריות:
var data = new google.visualization.DataTable(); data.addColumn('string', 'Name'); data.addColumn('string', 'Email'); data.addRows([ ['John Lennon', 'john@beatles.co.uk'], ['Paul McCartney', 'paul@beatles.co.uk'], ['George Harrison', 'george@beatles.co.uk'], ['Ringo Starr', 'ringo@beatles.co.uk'] ]); var table = new google.visualization.Table(document.getElementById('patternformat_div')); var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>'); // Apply formatter and set the formatted value of the first column. formatter.format(data, [0, 1]); var view = new google.visualization.DataView(data); view.setColumns([0]); // Create a view with the first column only. table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});
עזרה גאדג'ט
מחלקה שעוזרת לפשט את הכתיבה של גאדג'טים שמשתמשים ב-Google Visualization API.
יצרן
google.visualization.GadgetHelper()
שיטות
שיטה | ערך החזרה | תיאור |
---|---|---|
createQueryFromPrefs(prefs) |
google.visualization.Query |
סטטי. יצירת מכונה חדשה של google.visualization.Query והגדרת המאפיינים שלה בהתאם לערכים מההעדפות של הגאדג'ט. סוג הפרמטר
prefs הוא _IG_Prefs
|
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'.
-
sendMethod – [אופציונלי, מחרוזת] מציינת באיזו שיטה רוצים
לשלוח את השאילתה. בוחרים אחד מערכי המחרוזת הבאים:
שיטות
שיטה | ערך החזרה | תיאור |
---|---|---|
abort() |
ללא |
הפסקת השליחה של שאילתות אוטומטיות שהתחילו ב-setRefreshInterval() .
|
setRefreshInterval(seconds)
|
ללא |
ההגדרה הזו קובעת שהשאילתה תקרא באופן אוטומטי לשיטה אם משתמשים בשיטה הזו, צריך להתקשר אליה לפני שמתקשרים לשיטה
אפשר לבטל את השיטה הזו על ידי התקשרות חזרה לאפס (ברירת המחדל) או על ידי התקשרות ל- |
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() |
מערך מחרוזות |
מחזירה מערך של אפס ערכים נוספים. כל רשומה היא מחרוזת קצרה עם קוד שגיאה או אזהרה שהועלתה בזמן הפעלת השאילתה. קודים אפשריים:
|
hasWarning() |
בוליאני | מחזירה true אם הפעלת השאילתה מכילה הודעות אזהרה. |
isError() |
בוליאני |
מחזירה true אם הפעלת השאילתה נכשלה, והתגובה אינה מכילה טבלת נתונים כלשהי. מחזירה <false> אם הפעלת השאילתה בוצעה בהצלחה והתגובה מכילה טבלת נתונים.
|
הצגת שגיאה
ה-API מספק מספר פונקציות שיעזרו לכם להציג הודעות שגיאה מותאמות אישית למשתמשים. כדי להשתמש בפונקציות האלה, יש לספק רכיב קונטיינר בדף (בדרך כלל <div>
,) שבו ה-API יצייר הודעת שגיאה בפורמט. הקונטיינר הזה יכול להיות אלמנט המאגר של תצוגה חזותית או מאגר רק של שגיאות. אם תציינו את רכיב המאגר החזותי, הודעת השגיאה תוצג מעל התצוגה החזותית.
לאחר מכן יש לקרוא לפונקציה המתאימה כדי להציג את הודעת השגיאה או להסיר אותה.
כל הפונקציות הן פונקציות סטטיות במרחב השמות google.visualization.errors
.
תצוגות חזותיות רבות יכולות להקרין אירוע שגיאה. מידע נוסף על אירוע זה זמין בהמשך.
ניתן לראות דוגמה לשגיאה מותאמת אישית בדוגמה לדף מעטפת של שאילתה.
תפקיד | ערך החזרה | תיאור |
---|---|---|
addError(container, message, opt_detailedMessage,
opt_options)
|
ערך מזהה מחרוזת שמזהה את אובייקט השגיאה שנוצר. זהו ערך ייחודי בדף, ואפשר להשתמש בו כדי להסיר את השגיאה או למצוא את הרכיב שמכיל אותו. |
הוספת בלוק תצוגה של שגיאה לרכיב הדף שצוין עם טקסט ועיצוב ספציפיים.
|
addErrorFromQueryResponse(container, response) |
ערך במחרוזת המזהה את אובייקט השגיאה שנוצר, או null אם התגובה לא ציינת שגיאה. זהו ערך ייחודי בדף, ואפשר להשתמש בו כדי להסיר את השגיאה או למצוא את הרכיב שמכיל אותו. |
העברה של תגובת שאילתה ומאגר הודעות שגיאה לשיטה זו: אם תגובת השאילתה מציינת שגיאת שאילתה, מציגה הודעת שגיאה ברכיב הדף שצוין. אם
תגובת השאילתה היא null, השיטה תחזיר שגיאת JavaScript. יש להעביר את
QueryResponse שהתקבל ב-handler של ההודעה להודעה הזו כדי
להציג שגיאה. היא גם תגדיר את סגנון התצוגה שמתאים לסוג (שגיאה
או אזהרה, בדומה ל-
|
removeError(id) |
בוליאני: הערך true אם השגיאה הוסרה. אחרת, הערך הוא false. |
מסירה את השגיאה שצוינה על ידי המזהה מהדף.
|
removeAll(container) |
ללא |
מסירה את כל בלוקי השגיאות ממאגר שצוין. אם המאגר שצוין לא קיים, תופיע שגיאה.
|
getContainer(errorId) |
צריך לטפל ברכיב DOM שמכיל את השגיאה שצוינה, או להשתמש ב-null (אם הוא לא נמצא). |
אחזור של כינוי לאלמנט המאגר שמכיל את השגיאה שצוינה ב-errorID.
|
אירועים
רוב הרכיבים החזותיים מפעילים אירועים כדי לציין שמשהו התרחש. כמשתמשת בתרשים, לעיתים קרובות תרצו להאזין לאירועים האלה. אם רוצים לקודד תצוגה חזותית, כדאי להפעיל את האירועים האלה בעצמך.
השיטות הבאות מאפשרות למפתחים להאזין לאירועים, להסיר גורמי 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סרגל הכלים()
זהו המרכיב ברכיב רכיב סרגל הכלים שניתן לצרף להמחשות רבות. סרגל הכלים הזה מאפשר למשתמש לייצא את נתוני התצוגה החזותית בפורמטים שונים, או לספק גרסה ניתנת להטמעה של התצוגה החזותית לשימוש במקומות שונים. אפשר לעיין בדף סרגל הכלים לקבלת מידע נוסף ודוגמה לקוד.