Переход с angular2-signaturepad на ng-hub-ui-signature

angular2-signaturepad не выпускал релизов с февраля 2022 года. Это руководство сопоставляет его API с API ng-hub-ui-signature, показывает одну и ту же форму до и после и указывает, что не переносится. Новые имена проверены по исходному коду библиотеки, старые — по опубликованному пакету 4.0.2.

1 · Зачем переходить

Последний релиз angular2-signaturepad, 4.0.2, вышел 14 февраля 2022 года. Его peer-зависимости заканчиваются на Angular 13 и жёстко фиксируют signature_pad на версии 2.3.2. Репозиторий на GitHub архивирован, а в README сказано, что автор больше не пользуется пакетом и не может помогать с проблемами.

Если ваше приложение остаётся на Angular 13 или старше, переходить не обязательно. Причина для перехода — обновление Angular: ng-hub-ui-signature требует Angular 21 или новее, поэтому в большинстве проектов основная работа — это обновление фреймворка, а замена компонента — меньшая часть.

Это не замена «один в один». Селектор, класс, события и методы работы с данными меняются, а у некоторых возможностей нет аналога (см. таблицу). Взамен поле — это standalone-компонент без сторонней библиотеки рисования, он работает как элемент формы, сохраняет подпись в SVG, и им можно подписываться с клавиатуры.

2 · Установка и импорт

Удалите старый пакет и его библиотеку рисования, затем установите поле и два сопутствующих пакета. Внешний вид поля (подпись, подсказка, сообщения валидации) оформляет ng-hub-ui-forms, который подключается один раз в глобальных стилях.

До

После

Импортировать модуль не нужно: компонент standalone. Peer-зависимости: Angular 21 или новее, ng-hub-ui-forms 22.31.0 или новее и ng-hub-ui-utils 22.9.0 или новее.

3 · Соответствие API

Все публичные члены angular2-signaturepad 4.0.2 и то, что их заменяет.

ДоПослеПримечания
<signature-pad><hub-signature>Переименован. Теперь компонент рисует ещё и подпись, строку «очистить / отменить / повторить», подсказку и сообщения валидации. Чтобы получить только область рисования, используйте [controls]="false".
SignaturePadModule, SignaturePadHubSignatureComponentИмпортируйте standalone-компонент напрямую. provideHubSignature() настраивает только подписи действий и не заменяет модуль.
[options] Аналога нет Объекта опций нет. Каждая настройка — отдельный типизированный input.
options.penColor[strokeColor]По умолчанию currentColor; в начале штриха он преобразуется в реальный цвет и сохраняется вместе с каждым штрихом.
options.minWidth, options.maxWidth[strokeWidth]Одна постоянная толщина. Толщины в зависимости от скорости нет.
options.canvasHeight[height]В CSS-пикселях. Последующее изменение не масштабирует уже нарисованные штрихи.
options.canvasWidth Аналога нет Поле занимает весь контейнер. Задайте ширину в CSS.
options.backgroundColor, velocityFilterWeight, dotSize, throttle, minDistance Аналога нет Аналога нет. Фон на экране — это пользовательское CSS-свойство (--hub-signature-bg), но экспортируемый PNG прозрачный.
(onBeginEvent)(drawStart)Передаётся PointerEvent или KeyboardEvent вместо true.
(onEndEvent)(drawEnd)Вызывается только когда штрих зафиксирован. Отменённый штрих ничего не вызывает.
toDataURL(type, quality)toDataUrl(type)Аргумента качества нет. Экспортирует растр холста в размере в пикселях устройства с прозрачным фоном.
fromDataURL(dataURL) Аналога нет Аналога нет. Сохранённый PNG или JPEG нельзя загрузить обратно для редактирования.
toData(), fromData()toStrokes(), fromStrokes()Переименованы намеренно. Содержимое меняется с массивов {x, y, time} на объекты {points, color, width}, поэтому старый код не компилируется, а не ломается молча.
clear(), isEmpty()clear(), isEmpty()Те же имена. clear() дополнительно сбрасывает историю повтора и сообщает форме пустое значение.
resizeCanvas()resizeCanvas()То же имя, другое поведение. Старый метод очищал область; этот сохраняет подпись и заново измеряет поверхность.
on(), off()[readonly], [disabled]Inputs вместо методов. Они также меняют оформление и состояние ARIA.
set(option, value), queryPad() Аналога нет Настройки во время выполнения нет, как нет и встроенной библиотеки, к которой можно обратиться. Привяжите inputs к состоянию компонента.
— toSvg(), undo(), redo(), (valueChange)Новое. toSvg() — каноническая сериализация и значение формы; valueChange выдаёт его после каждого изменения пользователем.

4 · Типичное использование: до и после

Одна и та же форма согласия: сначала со старым компонентом и кнопкой ручного сохранения, затем с новым как реактивным элементом формы.

До

После

5 · Различия в поведении, которые стоит проверить

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

  • Подписи, сохранённые как data URL в PNG или JPEG, нельзя загрузить обратно для редактирования, потому что fromDataURL() нет. Показывайте их как изображение или запросите новую подпись. Не передавайте сохранённый data URL в обязательный элемент: он считается валидным, хотя область пуста.
  • Координаты штрихов абсолютны, поэтому сохранённый SVG корректно загружается только в поле той же ширины. Если вы загружаете подписи для редактирования, зафиксируйте ширину в CSS.
  • Штрихи — это ломаные постоянной толщины, без толщины по скорости и без сглаживания, поэтому новые подписи выглядят иначе, чем уже сохранённые.
  • toDataUrl() возвращает прозрачный PNG в размере в пикселях устройства, а не непрозрачный фиксированного размера. Если шаг с PDF или письмом ждёт белый фон, добавьте его сами, и экспортируйте из (drawEnd) или (valueChange), но не посреди штриха.
  • Поле, впервые отрисованное внутри закрытого модального окна или неактивной вкладки, имеет нулевую ширину. Вызовите resizeCanvas(), когда оно станет видимым, пока ещё пусто.
  • Подписываться можно и с клавиатуры: стрелки двигают перо, Пробел или Enter опускают и поднимают его, Escape отменяет штрих. Поэтому значение drawStart и drawEnd может быть KeyboardEvent; сузьте тип через instanceof, прежде чем читать свойства указателя.

6 · Документация

Полный справочник по полю с живыми примерами находится на его странице документации: Документация ng-hub-ui-signature