Поле подписи Angular | ng-hub-ui-signature
Доступное поле подписи Angular, сохраняющее ввод мышью, касанием и пером как масштабируемое SVG-значение формы, с отменой, повтором и экспортом PNG.
Справочник API
Вот полный контракт signature: всё, что можно привязать, прослушать, спроецировать и тематизировать, собрано в одном месте. Подключите то, что нужно, и оформите так, как хотите — это standalone и дружит с сигналами.
Входные свойства
Настройте signature с помощью 18 входных свойств. Привязывайте их, как любой @Input в Angular.
| Имя | Тип | По умолчанию | Описание |
|---|---|---|---|
label | string | '' | Видимая подпись поля и одновременно доступное имя области рисования: canvas связан с ней через aria-labelledby, поэтому озвучиваемое имя не может разойтись с видимым текстом. Клик по ней переводит фокус на область рисования. |
formText | string | '' | Вспомогательный текст поля. Где он показывается, определяет [formTextType]: по умолчанию под областью рисования или за вопросительным знаком в конце строки подписи. Проецируемый <ng-template hubFormText> заменяет строку в блоке ниже и сохраняет там своё место даже в режиме тултипа, потому что тултип принимает строку и потерял бы разметку. |
formTextType | 'bottom' | 'tooltip' | 'bottom' | Где показывается [formText]. bottom помещает его под область рисования, где его читают без запроса; tooltip вешает его за вопросительным знаком в конце строки подписи, для всего, что длиннее одного предложения. Знак отображается всегда, когда есть вспомогательный текст, в том числе на голой области, названной только через [ariaLabel]. Его всплывающий пузырь добавляется в <body>, поэтому режиму tooltip также нужна таблица стилей тултипов ng-hub-ui-utils. |
height | number | 160 | Логическая высота canvas в CSS-пикселях. |
strokeColor | string | 'currentColor' | Цвет, записываемый в новые SVG-штрихи. Значение по умолчанию currentColor разрешается относительно области рисования до захвата штриха, поэтому архив хранит конкретный цвет, а не ключевое слово, которое canvas не может разобрать. |
strokeWidth | number | 2 | Базовая толщина, записываемая в новые SVG-штрихи. |
readonly | boolean | false | Запрещает рисование, сохраняя подпись. |
controls | boolean | true | Показывает действия очистки, отмены и повтора. |
labels | Partial<HubSignatureLabels> | {} | Переопределяет переведённые на уровне приложения подписи действий только для этого поля. |
ariaLabel | string | '' | Доступное имя для области без видимого [label]. Поле с подписью берёт имя из неё через aria-labelledby, поэтому они не могут расходиться, и этот input там не используется. Если он пуст, имя определяется через [labels], затем HUBUI.SIGNATURE.ARIA_LABEL, затем английское значение по умолчанию Signature. |
labelType | HubLabelType | 'stacked' | Как подпись расположена относительно поля: 'stacked' или 'horizontal'. 'floating' откатывается к stacked, как и у других нетекстовых полей семейства — плавающая подпись занимает место, где было бы значение пустого текстового контрола, и управляется :placeholder-shown, которых у canvas нет. |
classlist | string | '' | Дополнительные классы для хост-элемента, самого <hub-signature> — не для области рисования, у которой остаётся собственный .hub-signature__canvas. Стилизуйте canvas через селектор потомка или настраивайте тему через слоты --hub-signature-*. |
formControlName | string | — | Имя контрола внутри окружающей группы формы. Унаследовано от HubFormControl, который объявляет его как собственный input, поэтому ReactiveFormsModule по-прежнему нужно импортировать там, где используется поле: без директивы ошибки не будет, а поле просто никогда не синхронизируется с формой. |
required | boolean | null | null | Отображает звёздочку обязательности и устанавливает aria-required на области. Двусторонний. При реактивной привязке выводится из валидаторов контрола и поддерживается в соответствии с ними, поэтому ручная привязка там перезаписывается и выдаёт предупреждение в режиме разработки; задавайте явно только для template-driven или непривязанного поля. |
disabled | boolean | false | Запрещает рисование, отключает строку действий и устанавливает aria-disabled. Двусторонний, а также записывается через setDisabledState(). Для поля с formControlName предпочтительнее control.disable() / control.enable(): собственная директива Angular тоже объявляет input disabled, поэтому привязка доходит до обеих и оставляет два источника истины для одного состояния. |
showValid | boolean | false | Опциональное состояние успеха. Затронутое и валидное поле получает рамку и кольцо успеха на области рисования и отображает [validFeedback], если он задан. По умолчанию берётся глобальное provideHubForms({ showValid }); состояние успеха никогда не включается автоматически. Не действует, пока поле невалидно. |
validFeedback | string | null | null | Сообщение об успехе под полем. Требует обе части опции: [showValid] включён и контрол затронут и валиден. |
invalidFeedbackTemplateFn | ((key: string, value: any) => string) | null | null | Переопределение для конкретного поля построителя сообщения о невалидности, приоритетнее глобального из provideHubForms(). Для разметки вместо строки вместо этого проецируйте <ng-template hubValidationError key="required"> — шаблон имеет приоритет над обоими. |
События
Реагируйте на то, что делает signature, — 5 событий, к которым можно подключить вашу логику.
| Имя | Тип | Описание |
|---|---|---|
valueChange | OutputEmitterRef<string> | Генерирует SVG-значение после изменения, инициированного пользователем — зафиксированного штриха, clear(), undo() или redo() — и пустую строку, когда ничего не остаётся. Программная запись через writeValue() или fromStrokes() ничего не генерирует, поэтому форма никогда не получает эхо самой себя. |
drawStart | OutputEmitterRef<HubSignatureDrawEvent> | Генерируется, когда пользователь начинает штрих указателем или клавиатурой. Позволяет хосту реагировать на активность рисования — приостановить автосохранение, активировать кнопку отправки — без опроса значения. HubSignatureDrawEvent — это PointerEvent | KeyboardEvent; сужайте через instanceof, когда важно устройство ввода. |
drawEnd | OutputEmitterRef<HubSignatureDrawEvent> | Генерируется, когда пользователь заканчивает штрих, после его фиксации. Срабатывает только для рисования пользователем, поэтому программная запись никогда не выглядит как оно, а штрих, который был отменён, а не завершён — pointercancel, Escape, уход фокуса с области — ничего не генерирует. |
disabledChange | OutputEmitterRef<boolean> | Записывающая половина двустороннего [(disabled)]. Срабатывает также, когда Angular вызывает setDisabledState() — то есть когда привязанный контрол отключается или включается, — поэтому хост, привязывающий [(disabled)] к реактивному полю, видит, как им управляет контрол. |
requiredChange | OutputEmitterRef<boolean | null> | Записывающая половина двустороннего [(required)]. При реактивной привязке срабатывает каждый раз, когда меняется статус контрола и его валидатор required был добавлен или удалён, — именно оттуда там берётся значение. |
Методы
Управляйте signature из кода — 10 методов его программного интерфейса.
| Имя | Сигнатура | Возвращает | Описание |
|---|---|---|---|
clear | clear(): void | — | Удаляет все штрихи и генерирует пустое значение. |
undo | undo(): void | — | Удаляет последний зафиксированный штрих. |
redo | redo(): void | — | Восстанавливает последний отменённый штрих. |
cancelStroke | cancelStroke(event?: PointerEvent): void | — | Отбрасывает штрих в процессе рисования, не сообщая о нём. Привязан к pointercancel и является путём, по которому идут Escape и уход фокуса с области: отменённое взаимодействие не должно попасть в значение формы. |
toSvg | toSvg(): string | — | Возвращает масштабируемое SVG-значение формы. |
toDataUrl | toDataUrl(type?: string): string | — | Экспортирует отрисованную подпись, по умолчанию в PNG. |
resizeCanvas | resizeCanvas(): void | — | Заново измеряет элемент, пересоздаёт растровое изображение в физических пикселях устройства и перерисовывает. [height] вызывает его за вас; вызывайте вручную, когда поле становится видимым после раскладки с нулевой шириной — внутри закрытого модального окна, неактивной вкладки, свёрнутого аккордеона, — так как единственное автоматическое измерение происходит при первом рендере, а ResizeObserver нет. Вызывайте, пока поле пусто: штрихи сохраняют координаты, в которых были захвачены, поэтому повторное измерение подписанного поля до новой ширины перекадрирует подпись, и toSvg() будет выдавать viewBox, не соответствующий геометрии внутри. |
isEmpty | isEmpty(): boolean | boolean | Показывает, было ли что-то нарисовано. Позволяет форме валидировать поле без разбора сериализованного SVG, что раньше было единственным способом это узнать. |
toStrokes | toStrokes(): HubSignatureStroke[] | HubSignatureStroke[] | Зафиксированные штрихи в виде структурированной геометрии. toSvg() остаётся каноническим значением формы — это для вызывающих, которым нужны сами точки, например для воспроизведения подписи или миграции с библиотеки, хранившей группы точек. |
fromStrokes | fromStrokes(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> |