Поле подписи Angular | ng-hub-ui-signature

Доступное поле подписи Angular, сохраняющее ввод мышью, касанием и пером как масштабируемое SVG-значение формы, с отменой, повтором и экспортом PNG.

Справочник API

Вот полный контракт signature: всё, что можно привязать, прослушать, спроецировать и тематизировать, собрано в одном месте. Подключите то, что нужно, и оформите так, как хотите — это standalone и дружит с сигналами.

Входные свойства

Настройте signature с помощью 18 входных свойств. Привязывайте их, как любой @Input в Angular.

ИмяТипПо умолчаниюОписание
labelstring''Видимая подпись поля и одновременно доступное имя области рисования: canvas связан с ней через aria-labelledby, поэтому озвучиваемое имя не может разойтись с видимым текстом. Клик по ней переводит фокус на область рисования.
formTextstring''Вспомогательный текст поля. Где он показывается, определяет [formTextType]: по умолчанию под областью рисования или за вопросительным знаком в конце строки подписи. Проецируемый <ng-template hubFormText> заменяет строку в блоке ниже и сохраняет там своё место даже в режиме тултипа, потому что тултип принимает строку и потерял бы разметку.
formTextType'bottom' | 'tooltip''bottom'Где показывается [formText]. bottom помещает его под область рисования, где его читают без запроса; tooltip вешает его за вопросительным знаком в конце строки подписи, для всего, что длиннее одного предложения. Знак отображается всегда, когда есть вспомогательный текст, в том числе на голой области, названной только через [ariaLabel]. Его всплывающий пузырь добавляется в <body>, поэтому режиму tooltip также нужна таблица стилей тултипов ng-hub-ui-utils.
heightnumber160Логическая высота canvas в CSS-пикселях.
strokeColorstring'currentColor'Цвет, записываемый в новые SVG-штрихи. Значение по умолчанию currentColor разрешается относительно области рисования до захвата штриха, поэтому архив хранит конкретный цвет, а не ключевое слово, которое canvas не может разобрать.
strokeWidthnumber2Базовая толщина, записываемая в новые SVG-штрихи.
readonlybooleanfalseЗапрещает рисование, сохраняя подпись.
controlsbooleantrueПоказывает действия очистки, отмены и повтора.
labelsPartial<HubSignatureLabels>{}Переопределяет переведённые на уровне приложения подписи действий только для этого поля.
ariaLabelstring''Доступное имя для области без видимого [label]. Поле с подписью берёт имя из неё через aria-labelledby, поэтому они не могут расходиться, и этот input там не используется. Если он пуст, имя определяется через [labels], затем HUBUI.SIGNATURE.ARIA_LABEL, затем английское значение по умолчанию Signature.
labelTypeHubLabelType'stacked'Как подпись расположена относительно поля: 'stacked' или 'horizontal'. 'floating' откатывается к stacked, как и у других нетекстовых полей семейства — плавающая подпись занимает место, где было бы значение пустого текстового контрола, и управляется :placeholder-shown, которых у canvas нет.
classliststring''Дополнительные классы для хост-элемента, самого <hub-signature> — не для области рисования, у которой остаётся собственный .hub-signature__canvas. Стилизуйте canvas через селектор потомка или настраивайте тему через слоты --hub-signature-*.
formControlNamestring—Имя контрола внутри окружающей группы формы. Унаследовано от HubFormControl, который объявляет его как собственный input, поэтому ReactiveFormsModule по-прежнему нужно импортировать там, где используется поле: без директивы ошибки не будет, а поле просто никогда не синхронизируется с формой.
requiredboolean | nullnullОтображает звёздочку обязательности и устанавливает aria-required на области. Двусторонний. При реактивной привязке выводится из валидаторов контрола и поддерживается в соответствии с ними, поэтому ручная привязка там перезаписывается и выдаёт предупреждение в режиме разработки; задавайте явно только для template-driven или непривязанного поля.
disabledbooleanfalseЗапрещает рисование, отключает строку действий и устанавливает aria-disabled. Двусторонний, а также записывается через setDisabledState(). Для поля с formControlName предпочтительнее control.disable() / control.enable(): собственная директива Angular тоже объявляет input disabled, поэтому привязка доходит до обеих и оставляет два источника истины для одного состояния.
showValidbooleanfalseОпциональное состояние успеха. Затронутое и валидное поле получает рамку и кольцо успеха на области рисования и отображает [validFeedback], если он задан. По умолчанию берётся глобальное provideHubForms({ showValid }); состояние успеха никогда не включается автоматически. Не действует, пока поле невалидно.
validFeedbackstring | nullnullСообщение об успехе под полем. Требует обе части опции: [showValid] включён и контрол затронут и валиден.
invalidFeedbackTemplateFn((key: string, value: any) => string) | nullnullПереопределение для конкретного поля построителя сообщения о невалидности, приоритетнее глобального из provideHubForms(). Для разметки вместо строки вместо этого проецируйте <ng-template hubValidationError key="required"> — шаблон имеет приоритет над обоими.

События

Реагируйте на то, что делает signature, — 5 событий, к которым можно подключить вашу логику.

ИмяТипОписание
valueChangeOutputEmitterRef<string>Генерирует SVG-значение после изменения, инициированного пользователем — зафиксированного штриха, clear(), undo() или redo() — и пустую строку, когда ничего не остаётся. Программная запись через writeValue() или fromStrokes() ничего не генерирует, поэтому форма никогда не получает эхо самой себя.
drawStartOutputEmitterRef<HubSignatureDrawEvent>Генерируется, когда пользователь начинает штрих указателем или клавиатурой. Позволяет хосту реагировать на активность рисования — приостановить автосохранение, активировать кнопку отправки — без опроса значения. HubSignatureDrawEvent — это PointerEvent | KeyboardEvent; сужайте через instanceof, когда важно устройство ввода.
drawEndOutputEmitterRef<HubSignatureDrawEvent>Генерируется, когда пользователь заканчивает штрих, после его фиксации. Срабатывает только для рисования пользователем, поэтому программная запись никогда не выглядит как оно, а штрих, который был отменён, а не завершён — pointercancel, Escape, уход фокуса с области — ничего не генерирует.
disabledChangeOutputEmitterRef<boolean>Записывающая половина двустороннего [(disabled)]. Срабатывает также, когда Angular вызывает setDisabledState() — то есть когда привязанный контрол отключается или включается, — поэтому хост, привязывающий [(disabled)] к реактивному полю, видит, как им управляет контрол.
requiredChangeOutputEmitterRef<boolean | null>Записывающая половина двустороннего [(required)]. При реактивной привязке срабатывает каждый раз, когда меняется статус контрола и его валидатор required был добавлен или удалён, — именно оттуда там берётся значение.

Методы

Управляйте signature из кода — 10 методов его программного интерфейса.

ИмяСигнатураВозвращаетОписание
clearclear(): void—Удаляет все штрихи и генерирует пустое значение.
undoundo(): void—Удаляет последний зафиксированный штрих.
redoredo(): void—Восстанавливает последний отменённый штрих.
cancelStrokecancelStroke(event?: PointerEvent): void—Отбрасывает штрих в процессе рисования, не сообщая о нём. Привязан к pointercancel и является путём, по которому идут Escape и уход фокуса с области: отменённое взаимодействие не должно попасть в значение формы.
toSvgtoSvg(): string—Возвращает масштабируемое SVG-значение формы.
toDataUrltoDataUrl(type?: string): string—Экспортирует отрисованную подпись, по умолчанию в PNG.
resizeCanvasresizeCanvas(): void—Заново измеряет элемент, пересоздаёт растровое изображение в физических пикселях устройства и перерисовывает. [height] вызывает его за вас; вызывайте вручную, когда поле становится видимым после раскладки с нулевой шириной — внутри закрытого модального окна, неактивной вкладки, свёрнутого аккордеона, — так как единственное автоматическое измерение происходит при первом рендере, а ResizeObserver нет. Вызывайте, пока поле пусто: штрихи сохраняют координаты, в которых были захвачены, поэтому повторное измерение подписанного поля до новой ширины перекадрирует подпись, и toSvg() будет выдавать viewBox, не соответствующий геометрии внутри.
isEmptyisEmpty(): booleanbooleanПоказывает, было ли что-то нарисовано. Позволяет форме валидировать поле без разбора сериализованного SVG, что раньше было единственным способом это узнать.
toStrokestoStrokes(): HubSignatureStroke[]HubSignatureStroke[]Зафиксированные штрихи в виде структурированной геометрии. toSvg() остаётся каноническим значением формы — это для вызывающих, которым нужны сами точки, например для воспроизведения подписи или миграции с библиотеки, хранившей группы точек.
fromStrokesfromStrokes(strokes: readonly HubSignatureStroke[]): void—Перерисовывает поле из структурированной геометрии. Программная запись, как writeValue(): она не сообщает формам Angular об изменении пользователем.

Шаблоны

Сделайте его своим — 2 слотов шаблона позволяют проецировать собственную разметку.

ИмяОписаниеПример
hubFormTextВспомогательный текст в виде разметки, заменяющий строку [formText] в блоке под областью рисования. Оба экспортируются из ng-hub-ui-forms, поэтому разметка, написанная для hub-input, переносится сюда без изменений. Он сохраняет своё место в блоке даже при formTextType="tooltip", потому что тултип принимает строку и потерял бы разметку — знак по-прежнему открывается со строкой [formText].<ng-template hubFormText>Sign with a pointer, or carry the pen with <kbd>Space</kbd>.</ng-template>
hubValidationErrorСообщение для одного ключа ошибки валидации, приоритетнее [invalidFeedbackTemplateFn] и глобального построителя provideHubForms(). Переопределяется только названный ключ; любая другая ошибка по-прежнему откатывается к построителю. Данные ошибки приходят как неявное значение контекста.<ng-template hubValidationError key="required">Sign before filing the contract.</ng-template>