תרשים הערה

  1. סקירה כללית
  2. דוגמה
  3. בטעינה
  4. פורמט נתונים
  5. אפשרויות הגדרה
  6. שיטות
  7. אירועים
  8. המדיניות בנושא נתונים
  9. Notes

סקירה כללית

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

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

דוגמה

 
<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type='text/javascript'>
      google.charts.load('current', {'packages':['annotationchart']});
      google.charts.setOnLoadCallback(drawChart);

      function drawChart() {
        var data = new google.visualization.DataTable();
        data.addColumn('date', 'Date');
        data.addColumn('number', 'Kepler-22b mission');
        data.addColumn('string', 'Kepler title');
        data.addColumn('string', 'Kepler text');
        data.addColumn('number', 'Gliese 163 mission');
        data.addColumn('string', 'Gliese title');
        data.addColumn('string', 'Gliese text');
        data.addRows([
          [new Date(2314, 2, 15), 12400, undefined, undefined,
                                  10645, undefined, undefined],
          [new Date(2314, 2, 16), 24045, 'Lalibertines', 'First encounter',
                                  12374, undefined, undefined],
          [new Date(2314, 2, 17), 35022, 'Lalibertines', 'They are very tall',
                                  15766, 'Gallantors', 'First Encounter'],
          [new Date(2314, 2, 18), 12284, 'Lalibertines', 'Attack on our crew!',
                                  34334, 'Gallantors', 'Statement of shared principles'],
          [new Date(2314, 2, 19), 8476, 'Lalibertines', 'Heavy casualties',
                                  66467, 'Gallantors', 'Mysteries revealed'],
          [new Date(2314, 2, 20), 0, 'Lalibertines', 'All crew lost',
                                  79463, 'Gallantors', 'Omniscience achieved']
        ]);

        var chart = new google.visualization.AnnotationChart(document.getElementById('chart_div'));

        var options = {
          displayAnnotations: true
        };

        chart.draw(data, options);
      }
    </script>
  </head>

  <body>
    <div id='chart_div' style='width: 900px; height: 600px;'></div>
  </body>
</html>

בטעינה

שם החבילה של google.charts.load הוא "annotationchart".

  google.charts.load("current", {packages: ['annotationchart']});

שם הכיתה של התצוגה החזותית הוא google.visualization.AnnotationChart.

  var visualization = new google.visualization.AnnotationChart(container);

פורמט נתונים

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

  • העמודה הראשונה היא מסוג date או datetime, והיא מציינת את ערך ה-X של הנקודה בתרשים. אם העמודה הזו היא מסוג date (ולא datetime), רזולוציית הזמן הקטנה ביותר בציר ה-X תהיה יום אחד.
  • לאחר מכן כל שורת נתונים מתוארת באמצעות קבוצה של אחת או שלוש עמודות נוספות, כפי שמתואר כאן:
    • ערך Y - [חובה, מספר] בעמודה הראשונה בכל קבוצה מופיע הערך של השורה בזמן המתאים מהעמודה הראשונה. תווית העמודה מוצגת בתרשים ככותרת של אותו הקו.
    • כותרת ההערה – [אופציונלי, מחרוזת] אם עמודת מחרוזת מופיעה אחרי העמודה value, והאפשרות displayAnnotations מוגדרת כ-True, לעמודה הזו תהיה כותרת קצרה שמתארת את הנקודה הזו. לדוגמה: אם הקו הזה מייצג את הטמפרטורה בברזיל, והנקודה הזו היא מספר גבוה מאוד, השם יכול להיות 'היום החם ביותר בתיעוד'.
    • טקסט ההערה - [מחרוזת אופציונלית] אם קיימת מחרוזת שנייה לסדרה הזו, ערך התא ישמש כטקסט תיאורי נוסף לנקודה הזו. כדי להשתמש בעמודה הזו צריך להגדיר את האפשרות displayAnnotations כ-True. אפשר להשתמש בתגי HTML אם מגדירים את allowHtml לערך true. בעיקרון אין מגבלת גודל, אבל חשוב לזכור שרשומות ארוכות מדי עלולות לגלוש בקטע התצוגה. העמודה הזו לא חייבת להופיע גם אם יש עמודה של כותרת הערה לנקודה הזו. התרשים לא משתמש בתווית העמודה. לדוגמה, אם זה היה היום החם ביותר בנקודת השיא, אפשר לומר משהו כמו "היום הקרוב ביותר היה קר יותר ב-10 מעלות!".

אפשרויות הגדרה

שם
allowHtml

אם המדיניות מוגדרת כ-True, כל טקסט הערה שכולל תגי HTML יוצג כ-HTML.

סוג: בוליאני
ברירת מחדל: false
allValuesSuffix

סיומת שתתווסף לכל הערכים במקרא ובתוויות שנתות בצירים האנכיים.

סוג: מחרוזת
ברירת מחדל: ללא
annotationsWidth

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

סוג: מספר
ברירת מחדל: 25
צבעים

הצבעים של הקווים והתוויות בתרשים. מערך של מחרוזות. כל רכיב הוא מחרוזת בפורמט צבע חוקי של HTML. לדוגמה, 'red' או '#00cc00'.

סוג: מערך של מחרוזות
ברירת מחדל: צבעי ברירת המחדל
dateFormat

הפורמט שמשמש להצגת פרטי התאריך בפינה השמאלית העליונה. הפורמט של השדה הזה הוא כפי שצוין על ידי gcloud SimpleDateFormat class.

סוג: מחרוזת
ברירת מחדל: 'MMMM dd, yyyy' או 'HH:mm MMMM dd, yyyy', בהתאם לסוג של העמודה הראשונה (תאריך או תאריך, בהתאמה).
displayAnnotations

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

סוג: בוליאני
ברירת מחדל: True
displayAnnotationsFilter

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

סוג: בוליאני
ברירת מחדל: false
displayDateBarSeparator

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

סוג: בוליאני
ברירת מחדל: True
displayExactValues

האם להציג גרסה מקוצרת ומעוגלת של הערכים בחלק העליון של התרשים כדי לחסוך במקום; הערך false מציין אפשרות כזו. לדוגמה, אם הערך מוגדר כ-False, הערך 56123.45 עשוי להופיע כ-56.12k.

סוג: בוליאני
ברירת מחדל: false
displayLegendDots

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

סוג: בוליאני
ברירת מחדל: True
displayLegendValues

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

סוג: בוליאני
ברירת מחדל: True
displayRangeSelector

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

המתאר בבורר הזום הוא גרסת יומן של הסדרה הראשונה בתרשים, עם התאמה לגובה של בורר הזום.

סוג: בוליאני
ברירת מחדל: True
displayZoomButtons

הגדרה שקובעת אם להציג את לחצני הזום ('1d 5d 1m' וכן הלאה), כאשר False היא לא.

סוג: בוליאני
ברירת מחדל: True
מילוי

מספר בין 0 ל-100 (כולל) שמציין את האלפא של המילוי מתחת לכל שורה בתרשים הקו. 100 פירושו 100% אטום ו-0 פירושו שאין מילוי בכלל. צבע המילוי זהה לצבע של הקו שמעליו.

סוג: מספר
ברירת מחדל: 0
legendPosition

הגדרה שקובעת אם להציג את המקרא הצבעוני באותה שורה עם לחצני הזום והתאריך ('sameRow'), או בשורה חדשה ('שורה חדשה').

סוג: מחרוזת
ברירת מחדל: 'sameRow'
מקסימלי

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

המדד הזה דומה לערך maxValue בתרשימי ליבה.

סוג: מספר
ברירת מחדל: אוטומטי
דקה

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

המדד הזה דומה לערך minValue בתרשימי ליבה.

סוג: מספר
ברירת מחדל: אוטומטי
numberFormats

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

התבניות צריכות להיות בפורמט שנקבע על ידי המחלקה Java DecimalFormat .

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

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

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

אם האפשרות הזו מצוינת, המערכת מתעלמת מהאפשרות displayExactValues.

סוג: מחרוזת או מפה של צמדים של מספר:מחרוזת
ברירת מחדל: אוטומטי
scaleColumns

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

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

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

כשמציגים יותר מסולם אחד, מומלץ להגדיר את האפשרות scaleType כ-allfixed' או כ'allmaximized'.

סוג: מערך של מספרים
ברירת מחדל: אוטומטי
scaleFormat

פורמט מספרים שישמש לתוויות של שנתות ציר. ברירת המחדל של '#' מוצגת כמספר שלם.

סוג: מחרוזת
ברירת מחדל: '#'
scaleType

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

  • 'maximized' - ציר ה-Y יכסה את המינימום לערך המקסימלי של הסדרה. אם יש לכם יותר מסדרה אחת, צריך להשתמש במאפיין 'allmax'.
  • 'fixed' [default] – ציר ה-Y משתנה בהתאם לערכי הנתונים:
    • אם כל הערכים הם >=0, ציר ה-Y יכסה בין אפס לערך הנתונים המקסימלי.
    • אם כל הערכים גדולים מ-0, ציר ה-Y יכסה בין אפס לערך הנתונים המינימלי.
    • אם הערכים הם חיוביים וגם שליליים, ציר ה-Y ינוע בין המקסימום של הסדרה לבין מספר המינימום של הסדרה.
      אם מדובר בכמה סדרות, משתמשים בערך 'allfixed'.
  • 'allmaximized' - זהה ל 'מקסימלי', אבל משמש כאשר מוצגים מספר סולמות. שני התרשימים יוגדלו באותו סולם. כלומר, יוצג מצג שווא ביחס לציר ה-Y, אבל כשמעבירים את העכבר מעל כל סדרה יוצג הערך האמיתי שלה.
  • 'allfixed' - זהה ל 'קבוע', אבל משמש כאשר מוצגים מספר סולמות. ההגדרה הזו מתאימה כל סולם לסדרה שעליו הוא חל (יש להשתמש בו בשילוב עם scaleColumns).

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

סוג: מחרוזת
ברירת מחדל: 'קבוע'
טבלה

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

var options: {
  table: {
    sortAscending: true,
    sortColumn: 1
  }
};
Type: object (סוג אובייקט)
ברירת מחדל: null
table.sortAscending

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

סוג: בוליאני
ברירת מחדל: false
table.sortColumn

אינדקס העמודות של טבלת ההערות שעבורו ההערות ימוינו. האינדקס חייב להיות 0 בעמודה של תווית ההערה, או 1 בעמודה של טקסט ההערה.

סוג: מספר
ברירת מחדל: 0
עובי

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

סוג: מספר
ברירת מחדל: 0
zoomEndTime

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

סוג: תאריך
ברירת מחדל: ללא
zoomStartTime

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

סוג: תאריך
ברירת מחדל: ללא

שיטות

שיטה
clearChart()

ניקוי התרשים וכל המשאבים שהוקצו לו.

סוג החזרה: ללא
draw(data, options, state)

מצייר את התרשים.

סוג החזרה: ללא
getContainer()

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

סוג החזרה: כינוי לרכיב DOM
getSelection()

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

סוג החזרה: מערך של רכיבי בחירה
getVisibleChartRange()

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

סוג החזרה: אובייקט עם המאפיינים start ו-end
hideDataColumns(columnIndexes)

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

סוג החזרה: ללא
setVisibleChartRange(start, end)

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

סוג החזרה: ללא
showDataColumns(columnIndexes)

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

סוג החזרה: ללא

אירועים

שם
rangechange

מופעל כשהמשתמש משנה את פס ההזזה של הטווח. נקודות הקצה (endpoints) החדשות של הטווח יהיו זמינות בתור event['start'] ו-event['end']: 

google.visualization.events.addListener(chart, 'rangechange', rangechange_handler);

function rangechange_handler(e) {
  console.log('You changed the range to ', e['start'], ' and ', e['end']);
}
מאפיינים: התחלה, סיום
ready

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

מאפיינים:ללא
select

מופעל כשהמשתמש לוחץ על ישות חזותית. כדי לבדוק אילו קבוצות נבחרו, אפשר להתקשר למספר getSelection().

מאפיינים:ללא

המדיניות בנושא נתונים

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