mr_nvtsk-gaugejs

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. Поэтому, если вы найдёте этот компонент или любую его часть интересной для себя, то можете использовать их свободно в любых целях.