VegaChart

  1. Обзор
  2. Простой пример
  3. Загрузка
  4. Формат данных
  5. Параметры конфигурации
  6. Методы
  7. События
  8. Политика данных

Обзор

VegaChart — это одна из многих возможных визуализаций, которые можно создать с помощью грамматики визуализации Vega , которая представляет собой декларативный язык для создания, сохранения и обмена проектами интерактивных визуализаций. С помощью Vega вы можете описывать внешний вид и интерактивное поведение визуализации в формате JSON, а также создавать веб-представления с помощью Canvas или SVG.

При рисовании VegaChart вы должны включить в параметры спецификацию построения диаграммы в грамматике визуализации Vega. Несколько примеров таких спецификаций приведены ниже, а еще несколько примеров можно найти на странице примеров VegaChart .

Примечание. Хотя Google Charts VegaChart может отображать любую диаграмму Vega, которую вы можете указать с помощью спецификации Vega JSON (включая все, что есть в галерее примеров ), дополнительные функции, требующие вызовов API Vega , пока недоступны.

Простой пример: гистограмма

Вот простой пример VegaChart, который рисует гистограмму. (См. исходный пример , подробное руководство и гистограмму в редакторе диаграмм Vega .)

Хотя это представляет собой еще один способ создания гистограммы в Google Charts, мы планируем интегрировать все функции других гистограмм и столбчатых диаграмм в новую реализацию, основанную на этой VegaChart.

В этом примере обратите внимание, что опция «данные» заменяется следующей, которая использует «таблицу данных», предоставленную вызовом отрисовки, в качестве «источника» для другого объекта данных, называемого «таблица», а «таблица» используется в остальная часть спецификации 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);

Однако таким образом в VegaChart можно передать только один такой DataTable, тогда как для некоторых диаграмм Vega требуется более одной таблицы данных. Мы устраним это ограничение в будущей версии Google Charts.

Тем временем вы можете указать любые дополнительные данные, которые вам нужно использовать, в опции « 'data' 'vega' », либо встроив их, либо загрузив по URL-адресу. Примеры того и другого можно найти ниже.

Параметры конфигурации

Имя
область диаграммы

Объект с элементами для настройки размещения и размера области диаграммы (где рисуется сама диаграмма, исключая оси и легенды). Поддерживаются два формата: число или число, за которым следует %. Простое число — это значение в пикселях; число, за которым следует %, представляет собой процент. Пример: chartArea:{left:20,top:0,width:'50%',height:'75%'}

Тип: объект
По умолчанию: ноль
диаграммаArea.bottom

На каком расстоянии рисовать диаграмму от нижней границы.

Тип: число или строка.
По умолчанию: авто
диаграммаArea.left

Насколько далеко рисовать диаграмму от левой границы.

Тип: число или строка.
По умолчанию: авто
ChartArea.right

Насколько далеко рисовать диаграмму от правой границы.

Тип: число или строка.
По умолчанию: авто
диаграммаArea.top

На каком расстоянии рисовать диаграмму от верхней границы.

Тип: число или строка.
По умолчанию: авто
ChartArea.width

Ширина области диаграммы.

Тип: число или строка.
По умолчанию: авто
диаграммаArea.height

Высота области диаграммы.

Тип: число или строка.
По умолчанию: авто
высота

Высота диаграммы в пикселях.

Тип: номер
По умолчанию: высота содержащего элемента.
ширина

Ширина диаграммы в пикселях.

Тип: номер
По умолчанию: ширина содержащего элемента.

Методы

Метод
draw(data, options)

Рисует диаграмму. Диаграмма принимает дальнейшие вызовы методов только после запуска события ready . Extended description .

Тип возврата: нет
getAction(actionID)

Возвращает объект действия всплывающей подсказки с запрошенным 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()

Очищает диаграмму и освобождает все выделенные ей ресурсы.

Тип возврата: нет

События

Дополнительные сведения о том, как использовать эти события, см. в разделах «Базовое взаимодействие» , «Обработка событий» и «Инициирование событий» .

Имя
animationfinish

Запускается, когда анимация перехода завершена.

Свойства: нет
click

Запускается, когда пользователь щелкает внутри диаграммы. Может использоваться для определения момента щелчка по заголовку, элементам данных, записям легенды, осям, линиям сетки или меткам.

Свойства: целевойID
error

Вызывается, когда возникает ошибка при попытке отобразить диаграмму.

Свойства: идентификатор, сообщение
legendpagination

Вызывается, когда пользователь нажимает стрелки нумерации страниц легенды. Возвращает текущий индекс страницы легенды, отсчитываемый от нуля, и общее количество страниц.

Свойства: currentPageIndex, totalPages.
onmouseover

Вызывается, когда пользователь наводит указатель мыши на визуальный объект. Возвращает индексы строк и столбцов соответствующего элемента таблицы данных.

Свойства: строка, столбец
onmouseout

Вызывается, когда пользователь уводит указатель мыши от визуального объекта. Возвращает индексы строк и столбцов соответствующего элемента таблицы данных.

Свойства: строка, столбец
ready

Диаграмма готова для вызовов внешних методов. Если вы хотите взаимодействовать с диаграммой и вызывать методы после ее рисования, вам следует настроить прослушиватель этого события до вызова метода draw и вызывать их только после того, как событие было запущено.

Свойства: нет
select

Запускается, когда пользователь щелкает визуальный объект. Чтобы узнать, что было выбрано, вызовите getSelection() .

Свойства: нет

Политика данных

Весь код и данные обрабатываются и отображаются в браузере. Никакие данные не отправляются ни на один сервер.