Числовые атрибуты

FAST Element — это современная библиотека для создания веб-компонентов на базе стандарта Custom Elements с мощной реактивностью и декларативным синтаксисом. Одной из важнейших возможностей является работа с атрибутами, которые напрямую связываются с состоянием компонента. Числовые атрибуты требуют особого подхода, так как HTML передает их как строки, а в коде часто необходимы именно числа.

Определение числового атрибута

В FAST Element числовые атрибуты определяются с помощью декоратора @attr или метода attr. Для преобразования строки атрибута в число используется параметр converter.

import { FASTElement, attr } from "@microsoft/fast-element";

export class Counter extends FASTElement {
    @attr({ converter: FASTElement.numberConverter })
    value;
}

В этом примере:

  • value — числовой атрибут компонента <counter>.
  • FASTElement.numberConverter автоматически преобразует строки в числа и обратно при чтении и записи атрибута.

Особенности числовых атрибутов

  1. Приведение типов HTML всегда передает атрибуты как строки. Без конвертера числовые значения будут храниться как строки, что приведет к некорректным вычислениям:

    this.value + 1 // если this.value = "5", результат = "51"

    С numberConverter результат вычислений будет корректным числом.

  2. Обработка отсутствующих значений Если атрибут не задан, FAST Element устанавливает значение null по умолчанию. Это важно учитывать при математических операциях:

    if (this.value === null) {
    this.value = 0;
}

  3. Реактивность Любое изменение числового атрибута через свойство автоматически обновляет DOM, если атрибут используется в шаблоне:

    import { html, FASTElement } from "@microsoft/fast-element";

export class Counter extends FASTElement {
    @attr({ converter: FASTElement.numberConverter })
    value;

    increment() {
        this.value++;
    }
}

const template = html<Counter>`
    <button @click="${x => x.increment()}">Увеличить</button>
    <p>Значение: ${x => x.value}</p>
`;

Ограничения и валидация

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

@attr({ converter: FASTElement.numberConverter })
value;

set value(v) {
    const number = Math.max(0, Math.min(100, v));
    this.$value = number;
}

get value() {
    return this.$value ?? 0;
}

Такой подход предотвращает выход значения за допустимые пределы.

Преобразование пользовательских форматов

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

const customNumberConverter = {
    fromAttribute(value) {
        return parseFloat(value.replace(',', '.'));
    },
    toAttribute(value) {
        return value.toString();
    }
};

@attr({ converter: customNumberConverter })
price;

Это позволяет компоненты работать с локализованными данными или специфическими форматами.

Числовые атрибуты и шаблон

В шаблоне FAST Element числовые значения можно использовать напрямую. При этом привязка работает с реактивностью, и любое изменение свойства обновляет отображение:

const template = html<MyComponent>`
    <div>Счётчик: ${x => x.value}</div>
    <button @click="${x => x.value += 5}">Добавить 5</button>
`;

Важный момент — в шаблоне не нужно вручную преобразовывать типы, если использован numberConverter.

Связь атрибутов с событиями

Числовые атрибуты часто связаны с событиями изменения состояния:

increment() {
    this.value++;
    this.$emit('value-changed', { detail: this.value });
}

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

Резюме ключевых практик

  • Использовать FASTElement.numberConverter для простых чисел.
  • Проверять null при отсутствии атрибута.
  • При необходимости реализовывать кастомные конвертеры для локализованных или нестандартных форматов.
  • Ограничивать значения через геттер/сеттер для обеспечения корректности данных.
  • Привязка к шаблону автоматически поддерживает реактивность, что упрощает обновление DOM.

Числовые атрибуты в FAST Element предоставляют удобный способ работы с числами напрямую через HTML и JavaScript, обеспечивая типовую безопасность и реактивное обновление интерфейса. Их грамотное использование позволяет создавать сложные компоненты с минимальным количеством ручного кода.

Оглавление