Пользовательские конвертеры

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

Принцип работы конвертеров

Конвертер — это объект или функция, которая реализует два направления преобразования данных:

  1. fromView — преобразование значения, полученного из DOM, перед его записью в свойство компонента. Используется для нормализации или проверки данных, введённых пользователем.
  2. toView — преобразование значения из свойства компонента перед отображением в DOM. Применяется для форматирования данных, приведения типов или создания пользовательских представлений.

Простейший конвертер может выглядеть так:

const numberConverter = {
  toView(value) {
    return value != null ? value.toString() : '';
  },
  fromView(value) {
    return Number(value);
  }
};

В этом примере toView преобразует число в строку для отображения в <input>, а fromView возвращает числовое значение из введённой строки.

Связывание конвертеров с элементами

В FAST Element конвертеры подключаются через директиву :value или атрибут converter в шаблоне:

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

class MyInput extends FASTElement {
  value = 0;
}

MyInput.template = html`
  <input 
    value="${x => x.value}" 
    converter="${numberConverter}" 
  />
`;

Ключевые моменты:

  • Свойство converter может принимать объект с методами toView и fromView или просто функцию (при одностороннем преобразовании).
  • Конвертеры работают только с реактивными свойствами компонента, определёнными в классе или через @observable.
  • Если fromView возвращает undefined, значение свойства не изменяется.

Создание пользовательских конвертеров

Пользовательские конвертеры позволяют реализовать любые правила преобразования данных. Например, конвертер для форматирования даты:

const dateConverter = {
  toView(date) {
    if (!(date instanceof Date)) return '';
    return date.toLocaleDateString('ru-RU');
  },
  fromView(value) {
    const parsed = Date.parse(value);
    return isNaN(parsed) ? null : new Date(parsed);
  }
};

При использовании такого конвертера <input> будет показывать дату в привычном формате, а компонент будет работать с объектом Date.

Динамические и параметризованные конвертеры

Иногда необходимо создавать конвертеры с параметрами. Для этого используют функции, возвращающие объект конвертера:

function minMaxConverter(min, max) {
  return {
    toView(value) {
      return value != null ? value.toString() : '';
    },
    fromView(value) {
      const num = Number(value);
      if (num < min) return min;
      if (num > max) return max;
      return num;
    }
  };
}
<input value="${x => x.score}" converter="${minMaxConverter(0, 100)}" />

Такой подход делает конвертеры гибкими и повторно используемыми.

Конвертеры для сложных типов

Конвертеры не ограничены примитивными типами. Для массивов, объектов и JSON они часто используются для преобразования данных между строкой и структурой:

const jsonConverter = {
  toView(value) {
    return JSON.stringify(value, null, 2);
  },
  fromView(value) {
    try {
      return JSON.parse(value);
    } catch {
      return [];
    }
  }
};

Этот конвертер позволяет редактировать массив или объект в <textarea> и автоматически синхронизировать его с реактивным свойством.

Интеграция с двусторонним связыванием

FAST Element поддерживает двустороннее связывание через синтаксис .bind. Конвертеры в этом случае работают одинаково корректно:

<input
  value="${x => x.age}"
  @input="${(x, c) => x.age = c.event.target.value}"
  converter="${numberConverter}"
/>

В двустороннем связывании toView отвечает за отображение, а fromView — за обновление свойства при изменении DOM. Это обеспечивает чистоту данных и предотвращает ошибки типов.

Лучшие практики использования конвертеров

  • Минимизировать логику в toView и fromView — конвертер должен быть лёгким, без сложных асинхронных операций.
  • Обрабатывать ошибки ввода — всегда возвращать значение по умолчанию или null, чтобы избежать некорректного состояния свойства.
  • Использовать функции для параметризованных конвертеров — это позволяет создавать повторно используемые решения для разных полей.
  • Комбинировать конвертеры с валидацией — FAST Element поддерживает валидацию через свойства и методы компонентов, а конвертер может предварительно нормализовать данные.

Расширенные возможности

Конвертеры можно комбинировать с пользовательскими директивами и реактивными наблюдателями для реализации сложных сценариев:

  • Автоформатирование валют, процентов, телефонов.
  • Маски ввода с динамическим изменением формата.
  • Синхронизация сложных структур данных с JSON или локальным хранилищем.

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

Пользовательские конвертеры в FAST Element становятся фундаментальным инструментом для построения компонентов, где данные должны не только отображаться, но и корректно интерпретироваться при изменениях. Они создают мост между внутренним состоянием компонента и пользовательским интерфейсом, позволяя создавать богатые, безопасные и удобные для пользователя веб-компоненты.

Оглавление