תרשים

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

סקירה כללית

VegaChart הוא אחד מהרכיבים החזותיים האפשריים שאפשר ליצור באמצעות VegaVisual Grammar: שפה הצהרתית ליצירה, לשמירה ולשיתוף של עיצובים אינטראקטיביים להמחשה חזותית. באמצעות Vega ניתן לתאר את המראה החזותי ואת ההתנהגות האינטראקטיבית של הוויזואליזציה בפורמט JSON, וליצור תצוגות מבוססות-אינטרנט באמצעות Canvas או SVG.

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

הערה: אפשר לשרטט ב-Google Charts VegaChart כל תרשים Vega שאפשר לציין באמצעות מפרט JSON של Vega (כולל כל מה שב גלריית הדוגמאות), אבל תכונות נוספות שדורשות קריאות ל- Vega API עדיין לא זמינות.

דוגמה פשוטה, תרשים העמודות

הנה דוגמה פשוטה ל-VegaCharta שממחישה תרשים עמודות. (תוכלו לראות את הדוגמה המקורית, מדריך מפורט ואת התרשים Bar Chart בעורך התרשימים של Vega).

זוהי דרך נוספת ליצור תרשים עמודות ב-Google Charts, אבל אנחנו מתכננים לשלב את כל התכונות של תרשימי העמודות והעמודות האחרים בהטמעה חדשה שמבוססת על VegaChart הזה.

בדוגמה הזו, שימו לב שהאפשרות data מוחלפת באפשרות הבאה, שמשתמשת ב-datatable שסופק על ידי בקשת השרטוט כ-source (מקור) בשביל אובייקט נתונים אחר שנקרא table, ובשאר המפרט של Vega נעשה שימוש ב-table (טבלה). 

  'data': [{'name': 'table', 'source': 'datatable'}],


<html>
  <head>
    <script src='https://www.gstatic.com/charts/loader.js'></script>
    <script>
      google.charts.load('upcoming', {'packages': ['vegachart']}).then(drawChart);

      function drawChart() {
        const dataTable = new google.visualization.DataTable();
        dataTable.addColumn({type: 'string', 'id': 'category'});
        dataTable.addColumn({type: 'number', 'id': 'amount'});
        dataTable.addRows([
          ['A', 28],
          ['B', 55],
          ['C', 43],
          ['D', 91],
          ['E', 81],
          ['F', 53],
          ['G', 19],
          ['H', 87],
        ]);

        const options = {
          "vega": {
            "$schema": "https://vega.github.io/schema/vega/v4.json",
            "width": 500,
            "height": 200,
            "padding": 5,

            'data': [{'name': 'table', 'source': 'datatable'}],

            "signals": [
              {
                "name": "tooltip",
                "value": {},
                "on": [
                  {"events": "rect:mouseover", "update": "datum"},
                  {"events": "rect:mouseout",  "update": "{}"}
                ]
              }
            ],

            "scales": [
              {
                "name": "xscale",
                "type": "band",
                "domain": {"data": "table", "field": "category"},
                "range": "width",
                "padding": 0.05,
                "round": true
              },
              {
                "name": "yscale",
                "domain": {"data": "table", "field": "amount"},
                "nice": true,
                "range": "height"
              }
            ],

            "axes": [
              { "orient": "bottom", "scale": "xscale" },
              { "orient": "left", "scale": "yscale" }
            ],

            "marks": [
              {
                "type": "rect",
                "from": {"data":"table"},
                "encode": {
                  "enter": {
                    "x": {"scale": "xscale", "field": "category"},
                    "width": {"scale": "xscale", "band": 1},
                    "y": {"scale": "yscale", "field": "amount"},
                    "y2": {"scale": "yscale", "value": 0}
                  },
                  "update": {
                    "fill": {"value": "steelblue"}
                  },
                  "hover": {
                    "fill": {"value": "red"}
                  }
                }
              },
              {
                "type": "text",
                "encode": {
                  "enter": {
                    "align": {"value": "center"},
                    "baseline": {"value": "bottom"},
                    "fill": {"value": "#333"}
                  },
                  "update": {
                    "x": {"scale": "xscale", "signal": "tooltip.category", "band": 0.5},
                    "y": {"scale": "yscale", "signal": "tooltip.amount", "offset": -2},
                    "text": {"signal": "tooltip.amount"},
                    "fillOpacity": [
                      {"test": "datum === tooltip", "value": 0},
                      {"value": 1}
                    ]
                  }
                }
              }
            ]
          }
        };

        const chart = new google.visualization.VegaChart(document.getElementById('chart-div'));
        chart.draw(dataTable, options);
      }
    </script>
  </head>

  <body>
    <div id="chart-div" style="width: 700px; height: 250px;"></div>
  </body>

</html>

בטעינה

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

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

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

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

פורמט נתונים

אופן ההעברה של הנתונים ל-VegaChart דומה מאוד לזה של תרשימים אחרים ב-Google באמצעות DataTable (או DataView). ההבדל העיקרי הוא שבמקום להסתמך על סדר העמודות כדי לקבוע את אופן השימוש בהן, VegaChart מסתמך על כך שהמזהה של כל עמודה יהיה זהה למצופה בהמחשה החזותית הספציפית של Vega שציינתם. לדוגמה, ה-DataTable הבא נוצר עם עמודות עם המזהים 'category' ו-'amount', ובאותם מזהים נעשה שימוש באפשרות 'vega' כדי להפנות לעמודות האלה.

עם DataTable
        const dataTable = new google.visualization.DataTable();
        dataTable.addColumn({type: 'string', 'id': 'category'});
        dataTable.addColumn({type: 'number', 'id': 'amount'});
        dataTable.addRows([
          ['A', 28],
          ['B', 55],
          ['C', 43],
        ]);

        const options = {
          'vega': {
            ...
            // Here we create the Vega data object named 'datatable',
            // which will be passed in via the draw() call with a DataTable.
            'data': {'name': 'datatable'},

            'scales': [
              {
                'name': 'yscale',
                // Here is an example of how to use the 'amount' field from 'datatable'.
                'domain': {'data': 'datatable', 'field': 'amount'},
              }
            ]
          }
        };

        const chart = new google.visualization.VegaChart(
          document.getElementById('chart-div'));
        chart.draw(dataTable, options);
עם נתונים מוטבעים של Vega
        // A DataTable is required, but it may be empty.
        const dataTable = new google.visualization.DataTable();
        const options = {
          'vega': {
            // Here the data is specified inline in the Vega specification.
            "data": [
              {
               "name": "table",
                "values": [
                  {"category": "A", "amount": 28},
                  {"category": "B", "amount": 55},
                  {"category": "C", "amount": 43},
                ]
              }
            ],

            'scales': [
              {
                'name': 'yscale',
                // Here is how Vega normally uses the 'amount' field from 'table'.
                "domain": {"data": "table", "field": "category"},
              }
            ]
          }
        };

        const chart = new google.visualization.VegaChart(
          document.getElementById('chart-div'));
        chart.draw(dataTable, options);

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

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

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

שם
chartArea

אובייקט עם חברים להגדרת המיקום והגודל של האזור בתרשים (שבו התרשים עצמו משורטט, לא כולל צירים ומקראים). יש שני פורמטים נתמכים: מספר או מספר ואחריו %. מספר פשוט הוא ערך בפיקסלים, ומספר ואחריו % הוא אחוז. דוגמה: chartArea:{left:20,top:0,width:'50%',height:'75%'}

Type: object (סוג אובייקט)
ברירת מחדל: null
chartArea.bottom

המרחק מהגבול התחתון לשרטוט התרשים.

סוג: מספר או מחרוזת
ברירת מחדל: אוטומטי
chartArea.left

המרחק מהגבול השמאלי לשרטוט התרשים.

סוג: מספר או מחרוזת
ברירת מחדל: אוטומטי
chartArea.right

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

סוג: מספר או מחרוזת
ברירת מחדל: אוטומטי
chartArea.top

המרחק מהגבול העליון לשרטוט התרשים.

סוג: מספר או מחרוזת
ברירת מחדל: אוטומטי
chartArea.width

רוחב שטח התרשים.

סוג: מספר או מחרוזת
ברירת מחדל: אוטומטי
chartArea.height

גובה השטח של התרשים.

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

גובה התרשים, בפיקסלים.

סוג: מספר
ברירת מחדל: גובה הרכיב שמכיל
רוחב

רוחב התרשים, בפיקסלים.

סוג: מספר
ברירת מחדל: רוחב הרכיב שמכיל

שיטות

שיטה
draw(data, options)

מצייר את התרשים. בתרשים יתקבלו קריאות נוספות ל-method, רק אחרי שהאירוע ready מופעל. Extended description.

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

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

Return Type (סוג החזרה): אובייקט
getBoundingBox(id)

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

var cli = chart.getChartLayoutInterface();

גובה השטח של התרשים
cli.getBoundingBox('chartarea').height
הרוחב של העמודה השלישית בסדרה הראשונה של תרשים עמודות או תרשים עמודות אנכי
cli.getBoundingBox('bar#0#2').width
תיבה תוחמת של מתקן התלייה החמישי בתרשים עוגה
cli.getBoundingBox('slice#4')
תיבת קישור של נתוני התרשים של תרשים אנכי (למשל, עמודה):
cli.getBoundingBox('vAxis#0#gridline')
תיבת קישור של נתוני התרשים של תרשים אופקי (למשל, עמודות):
cli.getBoundingBox('hAxis#0#gridline')

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

Return Type (סוג החזרה): אובייקט
getChartAreaBoundingBox()

מחזירה אובייקט שמכיל את השדות השמאליים, החלק העליון, הרוחב והגובה של תוכן התרשים (כלומר, לא כולל תוויות ומקרא):

var cli = chart.getChartLayoutInterface();

cli.getChartAreaBoundingBox().left
cli.getChartAreaBoundingBox().top
cli.getChartAreaBoundingBox().height
cli.getChartAreaBoundingBox().width

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

Return Type (סוג החזרה): אובייקט
getChartLayoutInterface()

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

אפשר לקרוא ל-methods הבאות באובייקט שמוחזר:

  • getBoundingBox
  • getChartAreaBoundingBox
  • getHAxisValue
  • getVAxisValue
  • getXLocation
  • getYLocation

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

Return Type (סוג החזרה): אובייקט
getHAxisValue(xPosition, optional_axis_index)

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

דוגמה: chart.getChartLayoutInterface().getHAxisValue(400)

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

סוג החזרה: מספר
getImageURI()

מחזירה את התרשים שעבר סריאליזציה ל-URI של תמונה.

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

ראו הדפסת תרשימי PNG.

סוג החזרה: מחרוזת
getSelection()

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

סוג החזרה: מערך של רכיבי בחירה
getVAxisValue(yPosition, optional_axis_index)

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

דוגמה: chart.getChartLayoutInterface().getVAxisValue(300)

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

סוג החזרה: מספר
getXLocation(dataValue, optional_axis_index)

הפונקציה מחזירה את קואורדינטת ה-x של dataValue ביחס לקצה השמאלי של הקונטיינר בתרשים.

דוגמה: chart.getChartLayoutInterface().getXLocation(400)

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

סוג החזרה: מספר
getYLocation(dataValue, optional_axis_index)

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

דוגמה: chart.getChartLayoutInterface().getYLocation(300)

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

סוג החזרה: מספר
removeAction(actionID)

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

סוג החזרה: none
setAction(action)

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

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

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

סוג החזרה: none
setSelection()

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

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

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

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

אירועים

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

שם
animationfinish

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

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

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

נכסים: targetID
error

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

מאפיינים: מזהה, הודעה
legendpagination

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

מאפיינים: currentPageIndex, total Pages
onmouseover

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

מאפיינים: שורה, עמודה
onmouseout

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

מאפיינים: שורה, עמודה
ready

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

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

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

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

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

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