chart

Для работы компонента требуется дополнение Charts.
ДЕМО

chart визуализирует данные с помощью Apache ECharts.

XML-элемент

chart

Java-класс

Chart

Основы

Объявите пространство имен charts в XML-дескрипторе экрана:

<view xmlns="http://jmix.io/schema/flowui/view"
      xmlns:charts="http://jmix.io/schema/charts/ui"/>

Studio автоматически добавляет пространство имен, когда вы добавляете компонент с помощью действия Add Component на верхней панели действий. См. Палитра компонентов.

Затем объявите и настройте график с помощью вложенных XML-элементов и атрибутов:

<charts:chart id="chart">
    <charts:dataSet>
        <charts:source dataContainer="vehiclesDc"
                       categoryField="year"
                       valueFields="cars motorcycles bicycles"/>
    </charts:dataSet>
    <charts:series>
        <charts:bar name="Cars"/>
        <charts:bar name="Motorcycles" stack="stack"/>
        <charts:bar name="Bicycles" stack="stack"/>
    </charts:series>
    <charts:xAxes>
        <charts:xAxis/>
    </charts:xAxes>
    <charts:yAxes>
        <charts:yAxis>
            <charts:axisLabel formatter="{value}"/>
        </charts:yAxis>
    </charts:yAxes>
</charts:chart>

Дополнительные свойства можно задать программно на Java:

@ViewComponent
private Chart chart;

@Subscribe
public void onInit(final InitEvent event) {
    chart.setLegend(new Legend().withTop("0"));
    chart.setTitle(new Title().withText("Vehicles").withSubtext("By Year"));
}

Получившийся график выглядит следующим образом:

chart component 1

При настройке графика можно обратиться к официальной документации Apache ECharts, найти нужные свойства и использовать соответствующие свойства Jmix Chart. В большинстве случаев JavaScript API и Jmix API совпадают.

Набор данных

ECharts

Свойство dataSet определяет источник данных для серий графика и позволяет переиспользовать данные между несколькими series внутри одного элемента charts.

В следующем примере набор данных настраивается в XML и подключает график к контейнеру данных vehiclesDc:

<charts:dataSet>
    <charts:source dataContainer="vehiclesDc"
                   categoryField="year"
                   valueFields="cars motorcycles bicycles"/>
</charts:dataSet>

График будет использовать атрибут year сущности для получения названия категории и атрибуты cars, motorcycles и bicycles для получения значений.

Тот же набор данных можно настроить на Java следующим образом:

chart.setDataSet(
        new DataSet().withSource(
                new DataSet.Source<EntityDataItem>()
                        .withDataProvider(new ContainerChartItems<>(vehiclesDc))
                        .withCategoryField("year")
                        .withValueFields("cars", "motorcycles", "bicycles")
        )
);
Элемент chart может включать только одну конфигурацию dataSet.

Серии

ECharts
ДЕМО

Элемент series определяет тип графика (например, линейный, столбчатый, рассеяния). Каждый тип графика может быть настроен по-разному внутри элемента series.

Основные типы графиков, поддерживаемые Jmix, включают:

В следующем примере элемент series определяет круговую диаграмму:

<charts:chart>
    <charts:dataSet>
        <charts:source dataContainer="vehiclesIn2012Dc"
                       categoryField="name"
                       valueFields="value"/>
    </charts:dataSet>
    <charts:series>
        <charts:pie>
            <charts:label formatter="{b}: {d}%"/>
        </charts:pie>
    </charts:series>
</charts:chart>

Элемент label настраивает текстовые метки сегментов круговой диаграммы. Атрибут formatter определяет шаблон, который может включать имя элемента данных и значение. Подробнее о метке и форматтере см. в документации ECharts.

Получившаяся круговая диаграмма выглядит следующим образом:

chart component series 1
Элемент chart может включать несколько конфигураций series, в таком случае данные будут общими для всех типов графиков.

Заголовок

ECharts

Свойство title отображает основной заголовок и подзаголовок графика, и настраивает содержание, позиционирование, выравнивание и стиль заголовка.

Например:

<charts:chart>
    <charts:title text="Vehicles" subtext="Ratio in 2012"
                  top="0" right="0" textAlign="CENTER">
        <charts:textStyle fontStyle="ITALIC"/>
    </charts:title>

Эта конфигурация указывает основной заголовок и подзаголовок для графика, размещенные в верхнем правом углу с центрированным текстом и курсивным стилем:

chart component title 1

Легенда

ECharts

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

<charts:chart>
    <charts:legend align="RIGHT"/>

В этом примере отображается легенда с символами справа:

chart component legend 1

Масштабирование данных

ECharts

Свойство dataZoom предоставляет две основные функции:

  • Inside data zoom позволяет пользователям масштабировать или перемещаться в координатных системах с помощью перетаскивания мышью, движения колесика мыши или жестов касания пальцем на сенсорных экранах.

  • Slider type data zoom предлагает различные функции для определения местоположения в пределах диапазона данных графика: миниатюры данных для быстрого обзора, масштабирование внутрь/наружу, выборка, перетаскивание для перемещения.

Например:

<charts:chart>
    <charts:dataZoom>
        <charts:insideDataZoom/>
        <charts:sliderDataZoom orientation="HORIZONTAL"/>
        <charts:sliderDataZoom orientation="VERTICAL" right="5%"/>
    </charts:dataZoom>

Обратите внимание на горизонтальные и вертикальные ползунки, отображаемые на графике:

chart component data zoom 1

Native JSON

Свойство nativeJson предоставляет возможность конфигурации с помощью непосредственной строки JSON, если Java API компонента или атрибутов XML недостаточно для выполнения необходимых настроек. Эта функция предоставляет доступ ко всем возможностям конфигурации ECharts.

Например:

<charts:chart>
    <charts:nativeJson>
        <![CDATA[{
            "title": {
                "text": "Vehicles",
                "subtext": "Ratio in 2012",
                "top": "0",
                "right": "0",
                "textAlign": "CENTER",
                "textStyle": {
                  "fontStyle": "italic"
                }
            }
        }]]>
    </charts:nativeJson>

Здесь элемент nativeJson настраивает заголовок графика так же, как в XML-конфигурации выше.

Конфигурация nativeJson объединяется с существующими свойствами и переопределяет соответствующие свойства, определенные в XML.

Панель инструментов

ECharts

Свойство toolbox предоставляет группу утилитных инструментов, которая включает в себя экспорт, просмотр данных, динамическое переключение типов, увеличение области данных и сброс настроек.

Например, следующая конфигурация добавляет возможность экспорта графика в виде изображения PNG:

<charts:chart>
    <charts:toolbox>
        <charts:features>
            <charts:saveAsImage title="Export to PNG" type="PNG"/>
        </charts:features>
    </charts:toolbox>

Обратите внимание на значок загрузки в правом верхнем углу графика:

chart component export 1

Атрибуты

Следующие атрибуты относятся к chart:

Название Описание Значение по умолчанию

animation

Включает или отключает анимацию графика.

true

animationDelay

Задает задержку перед начальной анимацией в миллисекундах.

—

animationDelayUpdate

Задает задержку перед анимацией обновления в миллисекундах.

—

animationDuration

Задает продолжительность начальной анимации в миллисекундах.

—

animationDurationUpdate

Задает продолжительность анимации обновления в миллисекундах.

—

animationEasing

Задает функцию сглаживания начальной анимации.

—

animationEasingUpdate

Задает функцию сглаживания анимации обновления.

—

animationThreshold

Задает максимальное количество графических элементов, при котором анимация остается включенной.

—

backgroundColor

Задает цвет фона графика в формате CSS.

—

blendMode

Задает глобальный режим смешивания. Допустимые значения: SOURCE_OVER, SOURCE_IN, SOURCE_OUT, SOURCE_ATOP, DESTINATION_OVER, DESTINATION_IN, DESTINATION_OUT, DESTINATION_ATOP, LIGHTER, COPY, XOR, MULTIPLY, SCREEN, OVERLAY, DARKEN, LIGHTEN, COLOR_DODGE, COLOR_BURN, HARD_LIGHT, SOFT_LIGHT, DIFFERENCE, EXCLUSION, HUE, SATURATION, COLOR и LUMINOSITY.

SOURCE_OVER

colorPalette

Задает разделенный запятыми набор CSS-цветов для серий графика.

—

hoverLayerThreshold

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

—

renderer

Выбирает клиентский механизм отрисовки. Допустимые значения: CANVAS и SVG.

CANVAS

useUtc

Определяет, должна ли ECharts разбирать и отображать значения времени в UTC.

—

Компонент поддерживает следующие общие атрибуты:

id - alignSelf - classNames - colspan - css - height - maxHeight - maxWidth - minHeight - minWidth - visible - width

Обработчики

Следующие события относятся к chart:

Чтобы сгенерировать заглушку обработчика в Jmix Studio, используйте вкладку Handlers панели инспектора Jmix UI, или команду Generate Handler, доступную на верхней панели контроллера экрана и через меню Code → Generate (Alt+Insert / Cmd+N).
Название Описание

ChartClickEvent

Возникает при щелчке по элементу графика.

ChartDataZoomEvent

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

ChartDoubleClickEvent

Возникает при двойном щелчке по элементу графика.

ChartFinishedEvent

Возникает после завершения отрисовки и всех анимаций.

ChartGlobalCursorTakenEvent

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

ChartGlobalOutEvent

Возникает, когда указатель покидает область графика.

ChartLegendInverseSelectEvent

Возникает при инвертировании выбора элементов легенды.

ChartLegendScrollEvent

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

ChartLegendSelectAllEvent

Возникает при выборе всех элементов легенды.

ChartLegendSelectChangedEvent

Возникает при изменении состояния выбора элемента легенды.

ChartMagicTypeChangedEvent

Возникает, когда инструмент панели управления изменяет тип серии графика.

ChartMouseDownEvent

Возникает при нажатии кнопки указателя над графиком.

ChartMouseMoveEvent

Возникает при перемещении указателя над графиком.

ChartMouseOutEvent

Возникает, когда указатель покидает элемент графика.

ChartMouseOverEvent

Возникает, когда указатель входит в область элемента графика.

ChartMouseUpEvent

Возникает при отпускании кнопки указателя над графиком.

ChartRenderedEvent

Возникает после отрисовки или повторной отрисовки графика.

ChartRestoreEvent

Возникает, когда действие восстановления на панели управления сбрасывает конфигурацию графика.

Компонент поддерживает следующие общие обработчики:

AttachEvent - DetachEvent

Элементы

chart может содержать вложенные элементы title, legend, scrollableLegend, tooltip, toolbox, brush, grid, aria, xAxes, yAxes, polar, radiusAxis, angleAxis, radar, dataZoom, visualMap, axisPointer, dataSet, series, textStyle, stateAnimation и nativeJson. Они соответствуют параметрам модели конфигурации Apache ECharts.

См. также