GaugeJS

Описание

GaugeJS -- это простой в использовании функциональный JavaScript-компонент, позволяющий создавать разнообразные гибконастраеваемые круговые счётчики.

Ключевые особенности:

• Поддержка любого начального угла и апертуры шкалы.

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

• Отображение любого количества шкал со своими визуальными стилями как снаружи счётчика, так и внутри него.

• Гибкая настройка всех визуальных элементов (цвета, ширина линий, отступы) при помощи JS и CSS.

• Высокая скорость работы "в динамике". При изменениях в отображении компонента визуальные элементы не перерисовываются, если они уже были созданы ранее: обновляются лишь их атрибуты.

Поддержка браузеров

Desktop: Chrome 1+, FireFox 1.5+, Internet Explorer 9+, Opera 9+, Safari 3+.

Mobile: iOS Safari 3.2+, Android Browser 3+.

Детальная информация о поддержке основных веб-движков.

Установка

NPM:

npm install mr_nvtsk-gaugejs

Использование

Использование нативного компонента:

Инициализация (в объекте настроек необходимо передавать как минимум контейнер, в который будет добавлен счётчик):

var gauge = Gauge({'container': HTMLElement});

Второй способ инициализации:

var gauge = new Gauge();
gauge.create({'container': HTMLElement});

Установка значения счётчика:

gauge.set(number);

Считывание значения счётчика:

var number = gauge.get();

Изменение компонента:

gauge.change(settings);

Удаление компонента:

gauge.destroy();

Использование jQuery плагина:

Инициализация (объект настроек передавать не обязательно):

$(element).Gauge(settings);

Установка значения счётчика:

$(element).Gauge('set', number);

Считывание значения счётчика:

var number = $(element).Gauge('get');

Изменение компонента:

$(element).Gauge('change', settings);

Удаление компонента:

$(element).Gauge('destroy');

API (methods)

change(settings) - меняет счётчик, где settings -- объект с настройками компонента (см. отдельное описание).

create(settings) - создаёт счётчик, где settings -- объект с настройками компонента (см. отдельное описание).

destroy - уничтожает счётчик.

get - возвращает значение счётчика.

hide - скрывает счётчик.

show - показывает счётчик.

set(value) - устанавливает текущее значение счётчика.

API (settings)

settings (настройки компонента):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | angles | object | - | Настройки, связанные с углами счётчика (см. отдельное описание). | | class | string | - | Префикс для HTML-атрибутов class всех визуальных элементов компонента. | | container | HTMLElement | + | Контейнер, в который будет помещён компонент. В режиме jQuery плагина передаётся неявно и не является обязательным. | | gauge | object | - | Настройки, связанные со значениями счётчика (см. отдельное описание). | | height | number | - | Высота компонента. Если не передана, то вычисляется автоматически в зависимости от высоты контейнера. | | padding | number | - | Отступ cчётчика от границ контейнера. Стандартно отступ для шкалы и значений меток шкалы, состоящих из не более, чем трёх чисел, вычисляется автоматически. Но если значения слишом длинные, то можно подправить отступы вручную при помощи этой настройки. | | styles | object | - | Настройки, связанные с визуальным отображением счётчика (см. отдельное описание). | | width | number | - | Ширина компонента. Если не передана, то вычисляется автоматически в зависимости от ширины контейнера. | | visibility | boolean | - | Видимость компонента. Видимостью также можно управлять при помощи методов show и hide. |

settings.angles (настройки, связанные с углами счётчика):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | aperture | number | - | Апертура счётчика в градусах. | | origin | number | - | Угол, относительно которого будет строится счётчик. По сути является биссектрисой угла апертуры. |

settings.gauge (настройки, связанные со значениями счётчика):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | current | number | - | Текущее значение счётчика. | | end | number | - | Минимальное значение счётчика. | | start | number | - | Максимальное значение счётчика. |

settings.styles (настройки, связанные с визуальным отображением счётчика):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | indicator | object | - | Настройки, связанные с визуальным отображениям индикатора счётчика (см. отдельное описание). | | range | object | - | Настройки, связанные с визуальным отображением основного (расположен по всей апертуре счётчика) сектора линии окружности счётчика (см. отдельное описание). | | ranges | array.object | - | Настройки, связанные с визуальным отображением дополнительных секторов линии окружности счётчика (см. отдельное описание). | | scales | array.object | - | Настройки, связанные с визуальным отображением шкал счётчика (см. отдельное описание). |

settings.styles.indicator (настройки, связанные с визуальным отображением индикатора счётчика):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | color | string | - | Цвет. | | length | number | - | Длина относительно радиуса. В случае положительного значения индикатор будет простираться дальше линии окружности счётчика. В случае отрицательного значения индикатор не будет достигать линии окружности счётчика. | | originRadius | number | - | Радиус окружности основания. |

settings.styles.range (настройки, связанные с видуальным отображением основного (расположен по всей апертуре счётчика) сектора линии окружности счётчика):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | color | string | - | Цвет. | | priority | number | - | Приоритет. При пересечении несколькоих секторов линии окружности отображаться будет тот, у которого приоритет выше. | | width | number | - | Ширина линии. |

settings.styles.ranges (настройки, связанные с визуальным отображением дополнительных секторов линии окружности счётчика):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | color | string | - | Цвет. | | priority | number | - | Приоритет. | | values | object | - | Настройки значений, в пределах которых будет расположен сектор (см. отдельное описание). | | width | number | - | Ширина линии. |

settings.styles.ranges.values (настройки значений, в пределах которых будет расположен сектор):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | end | number | - | Конечное значение. Если больше максимального значения счётчика, то сектор всё равно не будет простираться за конечный угол счётчика. | | start | number | - | Начальное значение. Если меньше максимального значения счётчика, то сектор не будет простираться за начальный угол счётчика. |

settings.styles.scales (настройки, связанные с визуальным отображением шкал счётчика):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | color | string | - | Цвет. | | label | object | - | Настройки, связанные с отображением меток шкалы (см. отдельное описание). | | length | number | - | Длина линии. | | padding | number | - | Отступ шкалы относительно линии окружности счётчика. | | position | string | - | Если принимает значение "inside", то шкала находится внутри линии окружности счётчика. Если принимает значение "outside", то шкала находится вне линии окружности счётчика. | | priority | number | - | Приоритет. Если на одном значении и на одной позиции будут находиться сразу несколько шкал, то отображаться будет та, у которой наибольший приоритет. | | step | number | - | Шаг шкалы в значениях счётчика. | | width | number | - | Ширина линии. |

settings.styles.scales.labels (настройки, связанные с отображением меток шкалы):

| Настройка | Тип | Обязательность | Описание | | --------- | --- | -------------- | -------- | | color | string | - | Цвет. | | visibility | boolean | - | Видимость метки. |

Более подробно о передаваемых компоненту настройках, а также о принципе изменения стилей при помощи CSS можно узнать ознакомившись с тестовой страницей, расположенной в каталоге example.

Примеры

Разработка

Установка зависимостей:

npm install

Сборка нативного компонента:

npm run build

Сборка jQuery-плагина:

npm run build-jquery

Проверка кода:

npm run check

Лицензия

GaugeJS создавался в качестве тестового проекта для устройства на работу в KudaGo.Ru. Но было бы глупо ограничивать его использование только сотрудниками компании KudaGo.Ru. Поэтому, если вы найдёте этот компонент или любую его часть интересной для себя, то можете использовать их свободно в любых целях.