VegaChart

بررسی اجمالی

VegaChart یکی از بسیاری از تجسم‌های ممکن است که ممکن است با استفاده از Vega Visualization Grammar ایجاد شود، که یک زبان اعلامی برای ایجاد، ذخیره و به اشتراک گذاری طرح‌های تجسم تعاملی است. با Vega، می توانید ظاهر بصری و رفتار تعاملی یک تجسم را در قالب JSON توصیف کنید و نماهای مبتنی بر وب را با استفاده از Canvas یا SVG ایجاد کنید.

هنگام ترسیم VegaChart، باید در داخل گزینه ها مشخصاتی برای نحوه ساخت نمودار در گرامر تجسم Vega قرار دهید. چند نمونه از این مشخصات در زیر آمده است، و چندین نمونه دیگر را می‌توانید در صفحه نمونه‌های VegaChart بیابید.

توجه: در حالی که Google Charts VegaChart می‌تواند هر نمودار Vega را که می‌توانید با مشخصات Vega JSON مشخص کنید (از جمله همه موارد موجود در گالری مثال ) ترسیم کند، ویژگی‌های اضافی که نیاز به تماس با Vega API دارند هنوز در دسترس نیستند.

یک مثال ساده، نمودار میله ای

در اینجا یک مثال ساده از VegaChart است که نمودار میله ای را ترسیم می کند. ( نمونه اصلی ، یک آموزش دقیق ، و نمودار میله ای در ویرایشگر نمودار Vega را ببینید.)

در حالی که این نشان‌دهنده راه دیگری برای تولید نمودار میله‌ای در نمودارهای Google است، ما قصد داریم تمام ویژگی‌های دیگر نمودارهای نوار و ستون را در یک پیاده‌سازی جدید بر اساس این VegaChart ادغام کنیم.

در این مثال، توجه داشته باشید که گزینه 'data' با گزینه زیر جایگزین شده است، که از 'datatable' ارائه شده توسط call draw به عنوان '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);

فرمت داده

داده‌ها را می‌توان به روشی بسیار مشابه با سایر نمودارهای Google، با استفاده از DataTable (یا DataView) به VegaChart ارسال کرد. تفاوت اصلی این است که 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);
    

با این حال، تنها یک چنین DataTable را می توان از این طریق به VegaChart ارسال کرد، در حالی که برخی نمودارهای Vega به بیش از یک جدول داده نیاز دارند. ما این محدودیت را در نسخه بعدی نمودارهای Google برطرف خواهیم کرد.

در عین حال، می‌توانید هر داده اضافی را که باید در گزینه « 'data' 'vega' » استفاده کنید، یا با داخل کردن آن یا با بارگیری آن از یک URL، مشخص کنید. نمونه هایی از هر دو را می توان در زیر مشاهده کرد.

گزینه های پیکربندی

نام
نمودار مساحت

یک شی با اعضا برای پیکربندی مکان و اندازه ناحیه نمودار (جایی که خود نمودار رسم شده است، به استثنای محورها و افسانه ها). دو فرمت پشتیبانی می شود: یک عدد یا یک عدد به دنبال ٪. یک عدد ساده یک مقدار در پیکسل است. یک عدد به دنبال آن % یک درصد است. مثال: chartArea:{left:20,top:0,width:'50%',height:'75%'}

نوع: شی
پیش فرض: null
نمودارArea.bottom

چقدر می توان نمودار را از حاشیه پایین رسم کرد.

نوع: عدد یا رشته
پیش فرض: خودکار
نمودار Area.left

چقدر می توان نمودار را از حاشیه سمت چپ رسم کرد.

نوع: عدد یا رشته
پیش فرض: خودکار
نمودار Area.right

چقدر می توان نمودار را از حاشیه سمت راست رسم کرد.

نوع: عدد یا رشته
پیش فرض: خودکار
نمودار Area.top

چقدر می توان نمودار را از حاشیه بالایی رسم کرد.

نوع: عدد یا رشته
پیش فرض: خودکار
نمودار مساحت.عرض

عرض منطقه نمودار

نوع: عدد یا رشته
پیش فرض: خودکار
نمودار مساحت.ارتفاع

ارتفاع منطقه نمودار

نوع: عدد یا رشته
پیش فرض: خودکار
ارتفاع

ارتفاع نمودار، بر حسب پیکسل.

نوع: شماره
پیش فرض: ارتفاع عنصر حاوی
عرض

عرض نمودار، بر حسب پیکسل.

نوع: شماره
پیش فرض: عرض عنصر حاوی

مواد و روش ها

روش
draw(data, options)

نمودار را رسم می کند. نمودار فراخوانی های متد بیشتر را فقط پس از فعال شدن رویداد ready می پذیرد. Extended description

نوع بازگشت: ندارد
getAction(actionID)

شی عمل راهنمای tooltip را با actionID درخواستی برمی گرداند.

نوع بازگشت: شی
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')

مقادیر نسبت به ظرف نمودار هستند. بعد از ترسیم نمودار این را صدا بزنید.

نوع بازگشت: شی
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()

نمودار را پاک می کند و تمام منابع اختصاص داده شده آن را آزاد می کند.

نوع بازگشت: ندارد

مناسبت ها

برای اطلاعات بیشتر در مورد نحوه استفاده از این رویدادها، به Basic Interactivity ، Handling Events و Firing Events مراجعه کنید.

نام
animationfinish

هنگامی که انیمیشن انتقال کامل شد فعال می شود.

خواص: هیچ
click

هنگامی که کاربر در داخل نمودار کلیک می کند فعال می شود. می توان برای شناسایی زمانی که عنوان، عناصر داده، ورودی های افسانه، محورها، خطوط شبکه یا برچسب ها کلیک می شود، استفاده کرد.

ویژگی ها: targetID
error

هنگامی که هنگام تلاش برای ارائه نمودار، خطایی رخ می دهد، فعال می شود.

ویژگی ها: شناسه، پیام
legendpagination

هنگامی که کاربر روی فلش های صفحه بندی افسانه کلیک می کند فعال می شود. نمایه صفحه مبتنی بر صفر افسانه فعلی و تعداد کل صفحات را به عقب پس می دهد.

ویژگی ها: currentPageIndex، totalPages
onmouseover

هنگامی که کاربر روی یک موجودیت بصری حرکت می‌کند فعال می‌شود. شاخص های سطر و ستون عنصر جدول داده مربوطه را به عقب ارسال می کند.

خواص: سطر، ستون
onmouseout

زمانی که کاربر از یک موجود بصری دور می‌شود، فعال می‌شود. شاخص های سطر و ستون عنصر جدول داده مربوطه را به عقب ارسال می کند.

خواص: سطر، ستون
ready

نمودار برای تماس های متد خارجی آماده است. اگر می‌خواهید با نمودار تعامل داشته باشید و پس از ترسیم روش‌ها را فراخوانی کنید، باید قبل از فراخوانی متد draw ، شنونده‌ای برای این رویداد تنظیم کنید و تنها پس از فعال شدن رویداد، آنها را فراخوانی کنید.

خواص: هیچ
select

هنگامی که کاربر روی یک موجودیت بصری کلیک می کند فعال می شود. برای اطلاع از آنچه انتخاب شده است، getSelection() را فراخوانی کنید.

خواص: هیچ

سیاست داده

تمام کدها و داده ها در مرورگر پردازش و ارائه می شوند. هیچ داده ای به هیچ سروری ارسال نمی شود.