Гаджет JSChart - график


Оглавление



Введение


Гаджет JSChart является небольшим, но достаточно функциональным JavaScript компонентом, позволяющим отображать на ВЕБ-странице график (диаграмму) для графического представления изменения различных параметров во времени. Для отрисовки графика используется HTML5 элемент <CANVAS>. График можно использовать для отображения как аналоговых, так и дискретных параметров. Гаджет имеет довольно гибкое управление функциональностью путем передачи различных опций в конструктор JavaScript компонента. Различные варианты использования гаджета можно посмотреть на примерах ниже. С помощью мыши можно управлять масштабированием и панорамированием графика - увеличивать произвольную область для отображения и перемещать ее. Подробнее об операциях масштабирования и панорамирования рассказано в соответствующем разделе страницы.

Для загрузки минифицированного JavaScript файла гаджета JSChart перейдите по ссылке jschart-2.2.2.min.js.
Для загрузки исходного JavaScript файла гаджета JSChart перейдите по ссылке jschart-2.2.2.src.js.

Предыдущие версии можно скачать по ссылкам:
jschart-2.2.1.min.js
jschart-2.2.1.src.js


Демонстрация


Для просмотра/сокрытия исходного HTML, CSS и JavaScript кода, воспользуйтесь кнопкой Показать/Скрыть код.
Для просмотра результата работы кода, воспользуйтесь кнопкой Показать результат.

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


Минимализм


В этом примере показан минимальный объем кода, необходимый для отображения простейшего графика.

HTML

CSS

JavaScript

В начало страницы

Несколько трендов


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

HTML

CSS

JavaScript

В начало страницы

Отображение границ


В этом примере показано отображение на графике аварийных и предупредительных границ.

HTML

CSS

JavaScript

В начало страницы

Дискретный график


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

HTML

CSS

JavaScript

В начало страницы

Динамика


В этом примере показано отображение на графике динамически изменяющихся данных. Для удобства работы, если график масштабирован или панорамирован (говоря по-русски - увеличен или сдвинут), обновление данных не производится.

HTML

CSS

JavaScript

В начало страницы

Иммитация загрузки


В этом примере показано отображение на графике процесса загрузки данных с сервера (иммитация). Как и в предыдущем примере, для удобства работы, если график масштабирован или панорамирован, обновление данных не производится.

HTML

CSS

JavaScript

В начало страницы

Управление масштабированием и панорамированием


Для удобства работы графики позволяют выполнять операции масштабирования и панорамирования. Графики аналоговых параметров масштабируются и панорамируются по обоим осям, а дискретных — только по оси времени.


Управление масштабированием и панорамированием графика аналоговых параметров


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

Для панорамирования графика установите курсор в любую точку графика и, нажав и не отпуская правую кнопку мыши, передвиньте изображение графика в желаемом направлении, затем отпустите кнопку. При этом на заднем плане графика появится изображение лупы, индицирующее, что график масштабирован или панорамирован.

Для сброса масштабирования и панорамирования установите курсор мыши в любую точку графика, нажмите левую кнопку мыши и, не отпуская ее, переместите курсор в направлении влево-вверх и отпустите кнопку.

В начало страницы

Управление масштабированием и панорамированием графика дискретных параметров


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

Для панорамирования графика установите курсор в любую точку графика и, нажав и не отпуская правую кнопку мыши, передвиньте изображение графика в желаемом направлении по горизонтали, затем отпустите кнопку. При этом на заднем плане графика появится изображение лупы, индицирующее, что график масштабирован или панорамирован.

Для сброса масштабирования и панорамирования установите курсор мыши в любую точку графика, нажмите левую кнопку мыши и, не отпуская ее, переместите курсор в направлении влево и отпустите кнопку.

В начало страницы

Общие замечания по масштабированию и панорамированию


1. При выполнении операции масштабирования, начальная точка выделения должна находиться внутри сетки графика. Если это выполнить сложно из-за близости интересующего участка к краю, то в первую очередь выполните панорамирование.

2. Если в ходе масштабирования или панорамирования курсор мыши выходит за пределы графика, операция прерывается.

3. Если при выполнении операции масштабирования, сброса масштабирования и панорамирования выделенный прямоугольник слишком мал (менее 10 пикселей - экранных точек), то операция не выполняется.

4. Существует проблема панорамирования графиков в браузере Opera, связанная с выскакиванием контекстного меню при отпускании правой кнопки мыши, с последующим ее (кнопки) «залипанием». Это известная проблема Оперы - невозможность полностью подавить контекстное меню.

В начало страницы

Описание API


Данное описание актуально для текущей версии 2.2.2 JavaScript компонента.


Пространство имен


Для уменьшения вероятности конфликта имен с другими JavaScript библиотеками, все компоненты проекта JSGadget входят в единое пространство имен JSGadget.

В начало страницы

Объект графика JSGadget.Chart


Данный объект представляет само поле отрисовки графика. Все остальные объекты так или иначе функционируют внутри него.

Конструктор JSGadget.Chart()

Вызов: var chart = new JSGadget.Chart(owner, options);

chart - переменная, которой присваивается созданный объект.

owner - обязательный параметр, представляющий собой родительский блочный элемент HTML страницы, обычно <div>. Родитель может передаваться как в виде объекта jQuery, так и в виде строки, понятной библиотеке jQuery.

options - необязательный параметр, представляющий собой объект, определяющий различные опции. Обект options должен содержать только те поля, значения которых отличаются от значений по умолчанию. Структура объекта options и значения полей по умолчанию:

{
  gap: { //Зазоры вокруг рабочего поля графика в пикселях
    t: 8, //сверху
    r: 5, //справа
    b: 32, //снизу
    l: 40 //слева
  },
  interactive: true, //разрешить интерактивность (масштабирование и панорамирование)
  font: { //шрифт
    size: 12, //размер в пикселях
    family: "sans-serif" //семейство
  },
  mouseSens: 10, //чуствительность перемещения мыши при сбросе масштабирования и панорамирования
  digital: false, //график дискретных параметров (иначе - аналоговых)
  background: JSGadget.Chart.BACKGROUND //цвет фона (введено начиная с версии 2.2.2)
};
Цвет фона по умолчанию определен константой
JSGadget.Chart.BACKGROUND = "#e0e0e0"; //(введено начиная с версии 2.2.2)
Кроме перечисленных выше, в объекте options могут присутствовать следующие поля:

bAxis - нижняя ось графика, объект типа JSGadget.BAxis. Если обект не передается в конструктор, то он создается автоматически. Создание нижней оси вручную может потребоваться для переопределения ее поведения по умолчанию.

lAxis - левая ось графика, объект типа JSGadget.LAxis (для аналогового графика) или JSGadget.DAxis (для дискретного). Если обект не передается в конструктор, то он создается автоматически. Создание левой оси вручную может потребоваться для переопределения ее поведения по умолчанию.

trends - массив трендов графика - объектов типа JSGadget.ATrend (для аналогового графика) или JSGadget.DTrend (для дискретного). Если массив не передается в конструктор, то он создается автоматически пустым.

В начало страницы

Функция resize()


Данная функция должна вызываться после изменения размеров родительского элемента.

Вызов: chart.resize();

chart - переменная, которой был присвоен объект, созданный при вызове конструктора.

В начало страницы

Функция draw()


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

Вызов: chart.draw();

chart - переменная, которой был присвоен объект, созданный при вызове конструктора.

В начало страницы

Функция loading(show)


Данная функция должна вызываться для отображения или сокрытия индикатора загрузки данных.

Вызов: chart.loading(show);

chart - переменная, которой был присвоен объект, созданный при вызове конструктора.

show - булевский параметр, управляющий отображением или сокрытием индикатора загрузки данных. Значение true вызывает отображение индикатора загрузки, значение false вызывает сокрытие индикатора загрузки и перерисовку графика (отдельный вызов функции draw() не требуется - она вызывается автоматически).

В начало страницы

Поля объекта графика


bAxis - нижняя ось графика, объект типа JSGadget.BAxis.

lAxis - левая ось графика, объект типа JSGadget.LAxis (для аналогового графика) или JSGadget.DAxis (для дискретного).

trends - массив трендов графика - объектов типа JSGadget.ATrend (для аналогового графика) или JSGadget.DTrend (для дискретного).

В начало страницы

Объект оси графика JSGadget.Axis


Данный объект представляет базовый тип для объектов осей графика. Конкретные типы объектов осей: JSGadget.BAxis - нижняя ось (ось времени), JSGadget.LAxis - левая ось для аналогового графика и JSGadget.DAxis - левая ось для дискретного графика.

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

Конструктор JSGadget.Axis()

Вызов: var axis = new JSGadget.Axis(chart, min, max);

axis - переменная, которой присваивается созданный объект.

chart - объект графика, которому принадлежит ось. Если ось создается до конструирования графика и передается в его конструктор, то данный параметр опускается, а остальные параметры сдвигаются влево.

min и max - необязательный минимум и максимум оси. Для оси времени задается в формате UNIX - число секунд, прошедших с полуночи 1 января 1970 года. Для вертикальной оси аналогового графика - соответствующее значение. Для вертикальной оси дискретного графика данные параметры игнорируются.

В начало страницы

Функция setMinMax(min, max)


Данная функция должна вызываться для одновременного изменения минимума и максимума оси.

Вызов: axis.setMinMax(min, max);

axis - переменная, представляющая объект оси.

min и max - устанавлевыемые минимум и максимум оси. Для оси времени задается в формате UNIX - число секунд, прошедших с полуночи 1 января 1970 года. Для вертикальной оси аналогового графика - соответствующее значение.

В начало страницы

Объект тренда графика JSGadget.Trend


Данный объект представляет базовый тип для объектов тренда графика. Конкретные типы трендов: JSGadget.ATrend - тренд аналогового графика и JSGadget.DTrend - тренд дискретного графика.

Дочерние типы трендов наследуют интерфейс базового типа JSGadget.Trend.

Конструктор аналогового тренда JSGadget.ATrend()

Вызов: var trend = new JSGadget.ATrend(chart, options);

trend - переменная, которой присваивается созданный объект.

chart - объект графика, которому принадлежит тренд. Если тренд создается до конструирования графика и передается в его конструктор, то данный параметр опускается, а остальные параметры сдвигаются влево.

options - необязательный параметр, представляющий собой объект, определяющий различные опции. Обект options должен содержать только те поля, значения которых отличаются от значений по умолчанию. Структура объекта options и значения полей по умолчанию:
{
  color: null, //цвет, если не задан, то циклически выбирается из набора по умолчанию
  xFld: "x", //имя поля данных для горизонтальной оси (для данных в виде вложенного массива - индекс)
  yFld: "y", //имя поля данных для вертикальной оси (для данных в виде вложенного массива - индекс)
  width: 2 //толщина линии
};
Кроме перечисленных выше, в объекте options может присутствовать поле данных:

data - массив данных для отображения. Может представлять собой как массив объектов, так и массив массивов.

Массив цветов по умолчанию (RGB):

[
  "#0000ff", "#00ff00", "#ff0000", "#00ffff",
  "#ffff00", "#ff00ff", "#000000", "#ffffff",
  "#ff8000", "#ff0080", "#80ff00", "#00ff80",
  "#8000ff", "#0080ff", "#ff8080", "#80ff80",
  "#8080ff", "#800000", "#008000", "#000080",
  "#808000", "#008080", "#800080", "#808080"
];

В начало страницы

Конструктор дискретного тренда JSGadget.DTrend()

Вызов: var trend = new JSGadget.DTrend(chart, options);

trend - переменная, которой присваивается созданный объект.

chart - объект графика, которому принадлежит тренд. Если тренд создается до конструирования графика и передается в его конструктор, то данный параметр опускается, а остальные параметры сдвигаются влево.

options - необязательный параметр, представляющий собой объект, определяющий различные опции. Обект options должен содержать только те поля, значения которых отличаются от значений по умолчанию. Структура объекта options и значения полей по умолчанию:
{
  color: "blue", //цвет
  xFld: "x", //имя поля данных для горизонтальной оси (для данных в виде вложенного массива - индекс)
  yFld: "y", //имя поля данных для вертикальной оси (для данных в виде вложенного массива - индекс)
  width: 2, //толщина линии
  text0: "false", //текстовое значение высокого уровня
  text1: "true", //текстовое значение низкого уровня
  title: undefined //название тренда
};
Кроме перечисленных выше, в объекте options может присутствовать поле данных:

data - массив данных для отображения. Может представлять собой как массив объектов, так и массив массивов.

В начало страницы

Поле данных тренда


data - массив данных для отображения. Может представлять собой как массив объектов, так и массив массивов. Для оси времени задается в формате UNIX - число секунд, прошедших с полуночи 1 января 1970 года. Для вертикальной оси аналогового графика - соответствующее численное значение или null для разрыва. Для вертикальной оси дискретного графика - соответствующее булевское или целое значение из набора [0, 1], или null для разрыва.

В начало страницы

История версий


2.2.2
Появилась возможность в конструкторе JavaScript компонента JSChart задавать цвет фона графика.

2.2.1
JavaScript компонент JSChart вошел в состав проекта JSGadget и его пространства имен JSGadget

До 2.2.1
До версии 2.2.1 JavaScript компонент Chart существовал, как самостоятельный проект.

В начало страницы
Демонстрация