Переход с 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, SignaturePad | HubSignatureComponent | Импортируйте 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