Счетчик ui.counter

ui.counter — расширение Bitrix Framework для счетчика: небольшой овальной метки с числом.

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

JavaScript-класс Counter создает и меняет счетчик в браузере. PHP-класс Bitrix\UI\Counter\Counter формирует готовый HTML на сервере.

Выбрать API для создания счетчикаВыбрать API для создания счетчика

Используйте API, который соответствует месту формирования счетчика:

• Counter из ui.cnt — для модульного JavaScript, когда счетчик создает код в браузере.

• ui.vue3.components.counter — для Vue-приложений на ui.vue3.

• Bitrix\UI\Counter\Counter — для PHP-кода, когда HTML формирует сервер.

У кнопки свой счетчик: его задают параметры самой кнопки. Для такого сценария используйте кнопки ui.buttons.

Подключить расширениеПодключить расширение

Если вы выводите счетчик из PHP, загрузите расширение ui.counter.

\Bitrix\Main\UI\Extension::load('ui.counter');

Расширение ui.counter не содержит своего кода: оно подключает расширение ui.cnt. Короткое имя ui.cnt защищает файлы от блокировки браузерными расширениями, а имя ui.counter остается для совместимости.

Если вы работаете в модульном JavaScript, импортируйте класс и наборы значений из ui.cnt.

import { Counter, CounterColor, CounterSize, CounterStyle } from 'ui.cnt';

После загрузки расширения те же имена доступны глобально: BX.UI.Counter, BX.UI.CounterColor, BX.UI.CounterSize и BX.UI.CounterStyle. Наборы значений доступны и как свойства класса: Counter.Color, Counter.Size и Counter.Style.

Создать счетчик в JavaScriptСоздать счетчик в JavaScript

Чтобы создать счетчик, выполните основные действия:

1. Создайте экземпляр Counter.

2. Передайте число в параметр value.

3. Разместите счетчик на странице методом renderTo().

Пример. Красный счетчик с числом 12 появляется в блоке с идентификатором counter-container.

import { Counter, CounterColor, CounterSize } from 'ui.cnt';

const counter = new Counter({
    value: 12,
    color: CounterColor.DANGER,
    size: CounterSize.MEDIUM,
});

counter.renderTo(document.getElementById('counter-container'));

Метод renderTo() добавляет счетчик в конец переданного узла и возвращает DOM-узел счетчика. Если аргумент не DOM-узел, метод возвращает null и ничего не размещает.

Метод render() возвращает DOM-узел счетчика, но не размещает его на странице. Используйте его, когда узел нужно вставить самостоятельно. Повторные вызовы render(), renderTo() и getContainer() возвращают один и тот же узел.

Передать параметрыПередать параметры

Передайте в конструктор Counter объект с параметрами, чтобы задать число, оформление и поведение счетчика.

Число и предельное значениеЧисло и предельное значение

• value — число счетчика. Передавайте неотрицательное число: конструктор выводит отрицательное значение как есть, и к нулю его приводят только методы update() и setValue(). По умолчанию 0.

• maxValue — предельное число. Если value больше, счетчик показывает maxValue со знаком +, например 99+. По умолчанию 99.

• usePercentSymbol — знак процента после числа. При true счетчик выводит value целиком и не ограничивает его по maxValue. По умолчанию false.

ОформлениеОформление

• color — цвет счетчика. Значения описаны в разделе Цвет счетчика. По умолчанию CounterColor.PRIMARY.

• size — размер счетчика. Значения описаны в разделе Размер счетчика. По умолчанию CounterSize.MEDIUM.

• useAirDesign — оформление Air Design. По умолчанию false.

• style — вариант оформления Air Design. Значения описаны в разделе Стиль Air Design. По умолчанию CounterStyle.FILLED.

• border — светлая рамка вокруг счетчика. Она отделяет счетчик от цветной подложки. По умолчанию false.

Двойной счетчикДвойной счетчик

• isDouble — вторая подложка, сдвинутая вправо за основным счетчиком. По умолчанию false.

• secondaryColor — цвет второй подложки. Значение берется из CounterColor и действует только с isDouble: true. По умолчанию CounterColor.PRIMARY.

Поведение и размещениеПоведение и размещение

• animate — анимация при смене числа. Описана в разделе Анимировать изменение числа. По умолчанию false.

• hideIfZero — скрытие счетчика при нулевом значении. Работает только с useAirDesign: true. По умолчанию false.

• node — готовый DOM-узел под счетчик. Класс очищает узел, задает ему классы счетчика и размещает содержимое внутри. Без этого параметра класс создает новый узел.

• id — значение атрибута id у узла счетчика. По умолчанию атрибут не задается.

Выбрать цвет, размер и стильВыбрать цвет, размер и стиль

Оформление счетчика собирается из трех наборов значений. Цвет и стиль отвечают за заливку и относятся к разным режимам, размер работает в обоих.

Цвет счетчикаЦвет счетчика

Цвет счетчика задает значение CounterColor. Оно действует, когда Air Design выключен.

Значения LIGHT, WHITE и DARK рассчитаны на темный фон, поэтому на иллюстрации они показаны на темной подложке.

Размер счетчикаРазмер счетчика

Размер счетчика задает значение CounterSize. Оно определяет высоту счетчика и размер шрифта.

Стиль Air DesignСтиль Air Design

Стиль определяет сочетание фона, текста и границы счетчика в режиме Air Design. Значения дает набор CounterStyle.

Пример. Счетчик в режиме Air Design скрывается, пока число равно нулю, и показывает заливку предупреждения, когда значение приходит с сервера.

import { Counter, CounterSize, CounterStyle } from 'ui.cnt';

const counter = new Counter({
    useAirDesign: true,
    style: CounterStyle.FILLED_WARNING,
    size: CounterSize.SMALL,
    value: 0,
    hideIfZero: true,
});

counter.renderTo(document.getElementById('counter-container'));
counter.update(5);

Изменить счетчик после созданияИзменить счетчик после создания

Методы класса Counter меняют число и оформление уже созданного счетчика. Вызывайте их после того, как счетчик размещен на странице.

Пример. Счетчик непрочитанных сообщений увеличивается на единицу по текущему значению.

counter.update(counter.getRealValue() + 1);

Анимировать изменение числаАнимировать изменение числа

Передайте animate: true, чтобы счетчик менял число с анимацией. Класс подбирает анимацию по направлению изменения: одну для роста значения, другую для уменьшения. Если текущее число уже достигло maxValue, класс меняет его без анимации.

Анимация меняет порядок обновления. Метод update() возвращает управление сразу, число в узле меняется через 250 мс после вызова, а класс анимации снимается через 500 мс. Если вы читаете текст узла сразу после вызова, вы получите прежнее число.

Пример. Счетчик с анимацией показывает число 3 через 250 мс после вызова update().

import { Counter, CounterColor } from 'ui.cnt';

const counter = new Counter({
    value: 1,
    color: CounterColor.DANGER,
    animate: true,
});

counter.renderTo(document.getElementById('counter-container'));
counter.update(3);

Показать и скрыть счетчикПоказать и скрыть счетчик

Метод hide() скрывает счетчик анимацией исчезновения, метод show() возвращает его анимацией появления. Оба метода меняют только видимость: узел остается на странице, а число сохраняется.

Пример. Счетчик исчезает на время запроса и возвращается с новым числом.

counter.hide();

// после ответа сервера
counter.update(12);
counter.show();

Удалить счетчикУдалить счетчик

Метод destroy() удаляет узел счетчика со страницы и очищает свойства объекта. После вызова объект использовать нельзя: создайте новый экземпляр Counter.

Создать счетчик в PHPСоздать счетчик в PHP

PHP-класс Bitrix\UI\Counter\Counter формирует HTML счетчика на сервере. Параметры передайте в конструктор именованными аргументами. После создания они не меняются: все свойства класса объявлены как readonly. Метод render() возвращает готовую HTML-строку.

Значения для параметров дают перечисления CounterColor, CounterSize и CounterStyle из пространства имен Bitrix\UI\Counter. Наборы значений совпадают с JavaScript.

В PHP нет параметров animate и node: анимацию и размещение в готовом узле поддерживает только JavaScript-класс.

Пример. Счетчик документов выводится в шаблоне рядом с пунктом меню и скрывается, пока документов нет.

use Bitrix\UI\Counter\Counter;
use Bitrix\UI\Counter\CounterSize;
use Bitrix\UI\Counter\CounterStyle;

\Bitrix\Main\UI\Extension::load('ui.counter');

$counter = new Counter(
    useAirDesign: true,
    style: CounterStyle::FILLED_ALERT,
    value: 7,
    size: CounterSize::SMALL,
    id: 'documents-counter',
    hideIfZero: true,
);

echo $counter->render();

Обновить серверный счетчик из JavaScriptОбновить серверный счетчик из JavaScript

Статический метод Counter.updateCounterNodeValue() меняет число у счетчика, который пришел с сервера. Метод принимает узел счетчика и новое число, собирает объект Counter по классам узла и перерисовывает содержимое. Так счетчик получает новое число после ответа сервера, без перезагрузки страницы.

Статический метод Counter.initFromCounterNode() создает объект Counter по готовому узлу и возвращает его. Используйте метод, когда серверному счетчику нужно не только новое число, но и другое оформление. Если у узла нет класса ui-counter, метод возвращает null.

Пример. Счетчик документов, отрисованный в PHP, получает новое число после ответа сервера.

import { Counter } from 'ui.cnt';

Counter.updateCounterNodeValue(document.getElementById('documents-counter'), 3);

Создать счетчик во Vue-приложенииСоздать счетчик во Vue-приложении

Расширение ui.vue3.components.counter экспортирует Vue-компонент Counter с именем BCounter. Компонент создает счетчик на основе класса Counter из ui.cnt и всегда включает Air Design, поэтому использует те же размеры и стили.

Если вы подключаете компонент из PHP, загрузите расширение ui.vue3.components.counter.

\Bitrix\Main\UI\Extension::load('ui.vue3.components.counter');

В модульном JavaScript импортируйте компонент из этого расширения, а значения для свойств — из ui.cnt.

import { Counter } from 'ui.vue3.components.counter';
import { CounterSize, CounterStyle } from 'ui.cnt';

Свойства компонента соответствуют параметрам класса.

Компонент следит за свойствами value, style, size, maxValue и border и обновляет счетчик при их изменении. Свойство percent компонент читает один раз при создании, поэтому менять его после отрисовки нельзя.

Свойств color, isDouble и hideIfZero у компонента нет. Если они нужны, создавайте счетчик классом Counter из ui.cnt.

Наборы CounterStyle и CounterSize — константы, а не данные компонента. Верните их из setup(), чтобы обратиться к ним в шаблоне.

Пример. Компонент показывает долю выполненных задач в процентах.

import { Counter } from 'ui.vue3.components.counter';
import { CounterSize, CounterStyle } from 'ui.cnt';

export const TaskProgress = {
    name: 'TaskProgress',
    components: {
        Counter,
    },
    props: {
        donePercent: {
            type: Number,
            default: 0,
        },
    },
    setup()
    {
        return {
            CounterSize,
            CounterStyle,
        };
    },
    template: `
        <Counter
            :value="donePercent"
            :size="CounterSize.LARGE"
            :style="CounterStyle.FILLED_SUCCESS"
            percent
        />
    `,
};

Связанные материалыСвязанные материалы

• Кнопки ui.buttons — счетчик внутри кнопки.

• Каталог объектов ui.entity-catalog — счетчик на группе каталога.

• Расширения — подключение JavaScript-расширений Bitrix Framework.