תרשים טבעת

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

סקירה כללית

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

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

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

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

הנה דוגמה פשוטה של VegaChart ששרטט תרשים עמודות. (אפשר להיעזר בדוגמה המקורית, מדריך מפורט וגם תרשים העמודות בעורך של מפות Vega.)

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

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

  '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' כדי להפנות לעמודות.

עם טבלת נתונים
        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);

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

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

אפשרויות תצורה

שם
תרשים גבולות

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

Type: אובייקט
ברירת מחדל: null
ChartArea.bottom

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

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

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

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

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

סוג: מספר או מחרוזת
ברירת מחדל: אוטומטי
התרשיםArea.top

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

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

רוחב האזור בתרשים.

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

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

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

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

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

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

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

שיטות

שיטה
draw(data, options)

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

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

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

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

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

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

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

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

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

var cli = chart.getChartLayoutInterface();

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

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

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

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

אפשר לקרוא לשיטות הבאות על האובייקט שהוחזר:

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

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

סוג החזרה: אובייקט
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)

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

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

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

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

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

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

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

סוג החזרה: אין

אירועים

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

שם
animationfinish

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

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

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

נכסים: targetID
error

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

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

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

נכסים: currentPageIndex, totalPages
onmouseover

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

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

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

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

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

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

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

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

מדיניות נתונים

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