Angular-Signaturfeld | ng-hub-ui-signature

Barrierefreies Angular-Signaturfeld, das Maus-, Touch- und Stifteingaben als skalierbare SVG-Formularwerte speichert, mit Rückgängig, Wiederholen und PNG-Export.

API-Referenz

Hier ist der vollständige Vertrag für signature: alles, was du binden, abhören, projizieren und gestalten kannst, an einem Ort gesammelt. Verdrahte, was du brauchst, und gestalte, was du willst — es ist standalone und Signals-freundlich.

Inputs

Stelle signature mit 18 Inputs ein. Binde sie wie jeden Angular-@Input.

NameTypStandardBeschreibung
labelstring''Sichtbare Feldbeschriftung und zugleich zugänglicher Name der Zeichenfläche: Das Canvas ist per aria-labelledby damit verbunden, sodass der angesagte Name nie vom sichtbaren Text abweichen kann. Ein Klick darauf fokussiert die Zeichenfläche.
formTextstring''Hilfetext für das Feld. Wo er angezeigt wird, bestimmt [formTextType]: standardmäßig unter der Zeichenfläche oder hinter einem Fragezeichen am Ende der Beschriftungszeile. Ein projiziertes <ng-template hubFormText> ersetzt den String im Block darunter und behält dort seinen Platz auch im Tooltip-Modus, da ein Tooltip einen String erwartet und das Markup verlieren würde.
formTextType'bottom' | 'tooltip''bottom'Wo [formText] angezeigt wird. bottom setzt ihn unter die Zeichenfläche, wo er ungefragt gelesen wird; tooltip hängt ihn hinter ein Fragezeichen am Ende der Beschriftungszeile, für alles, was länger als ein Satz ist. Das Zeichen wird immer gerendert, sobald es Hilfetext gibt, auch bei einer reinen Fläche, die nur über [ariaLabel] benannt ist. Seine Blase wird an <body> angehängt, daher benötigt der Tooltip-Modus auch das Tooltip-Stylesheet von ng-hub-ui-utils.
heightnumber160Logische Canvas-Höhe in CSS-Pixeln.
strokeColorstring'currentColor'Farbe, die in neuen SVG-Strichen gespeichert wird. Der Standardwert currentColor wird gegen die Zeichenfläche aufgelöst, bevor der Strich erfasst wird, sodass das Archiv eine konkrete Farbe speichert statt eines Schlüsselworts, das das Canvas nicht parsen kann.
strokeWidthnumber2Basisbreite, die in neuen SVG-Strichen gespeichert wird.
readonlybooleanfalseVerhindert das Zeichnen und erhält dabei die Signatur.
controlsbooleantrueZeigt die Aktionen Löschen, Rückgängig und Wiederholen an.
labelsPartial<HubSignatureLabels>{}Überschreibt die anwendungsweit übersetzten Aktionsbeschriftungen nur für dieses Feld.
ariaLabelstring''Zugänglicher Name für eine Fläche ohne sichtbares [label]. Ein Feld mit Beschriftung bezieht seinen Namen per aria-labelledby aus dieser Beschriftung, sodass beide nicht voneinander abweichen können, und dieser Input wird dort nicht ausgewertet. Bleibt er leer, wird er über [labels], dann HUBUI.SIGNATURE.ARIA_LABEL und schließlich den englischen Fallback Signature aufgelöst.
labelTypeHubLabelType'stacked'Wie die Beschriftung zum Feld steht: 'stacked' oder 'horizontal'. 'floating' fällt auf stacked zurück, wie bei den anderen Nicht-Textfeldern der Familie — eine schwebende Beschriftung nutzt den Platz, den der Wert eines leeren Textsteuerelements einnehmen würde, und wird von :placeholder-shown gesteuert, was ein Canvas beides nicht hat.
classliststring''Zusätzliche Klassen für das Host-Element, <hub-signature> selbst — nicht für die Zeichenfläche, die ihr eigenes .hub-signature__canvas behält. Das Canvas über einen Nachfahren-Selektor stylen oder über die --hub-signature-*-Slots anpassen.
formControlNamestring—Name des Steuerelements in der umgebenden Formulargruppe. Von HubFormControl geerbt, das ihn als eigenen Input deklariert, daher muss ReactiveFormsModule dort, wo das Feld verwendet wird, weiterhin importiert werden: Ohne die Direktive wird kein Fehler ausgelöst, und das Feld synchronisiert sich schlicht nie mit dem Formular.
requiredboolean | nullnullRendert das Pflicht-Sternchen und setzt aria-required auf der Fläche. Two-Way. Bei einer reaktiven Bindung wird es aus den Validatoren des Steuerelements abgeleitet und mit ihnen synchron gehalten; es dort von Hand zu binden wird überschrieben und warnt im Dev-Modus. Explizit nur bei einem Template-driven oder ungebundenen Feld setzen.
disabledbooleanfalseVerweigert das Zeichnen, deaktiviert die Aktionszeile und setzt aria-disabled. Two-Way, und wird auch von setDisabledState() geschrieben. Bei einem formControlName-Feld besser control.disable() / control.enable() verwenden: Die eigene Direktive von Angular deklariert ebenfalls einen disabled-Input, sodass eine Bindung beide erreicht und zwei Quellen der Wahrheit für einen Zustand entstehen.
showValidbooleanfalseOpt-in-Erfolgszustand. Ein berührtes und gültiges Feld erhält auf der Zeichenfläche den Erfolgsrahmen und -ring und rendert [validFeedback], falls angegeben. Standard ist das globale provideHubForms({ showValid }); der Erfolgszustand ist nie automatisch. Hat keine Wirkung, solange das Feld ungültig ist.
validFeedbackstring | nullnullErfolgsmeldung unter dem Feld. Erfordert beide Hälften des Opt-ins: [showValid] aktiviert und ein Steuerelement, das berührt und gültig ist.
invalidFeedbackTemplateFn((key: string, value: any) => string) | nullnullÜberschreibung pro Feld für den Builder der Fehlermeldung, vor dem globalen von provideHubForms(). Für Markup statt eines Strings stattdessen ein <ng-template hubValidationError key="required"> projizieren — die Vorlage hat vor beiden Vorrang.

Outputs

Reagiere darauf, was signature tut — 5 Events, an die du deine Logik anknüpfen kannst.

NameTypBeschreibung
valueChangeOutputEmitterRef<string>Gibt den SVG-Wert nach einer vom Benutzer ausgelösten Änderung aus — ein abgeschlossener Strich, clear(), undo() oder redo() — und den leeren String, sobald nichts mehr übrig ist. Ein programmatisches Schreiben über writeValue() oder fromStrokes() gibt nichts aus, sodass das Formular nie an sich selbst zurückgespiegelt wird.
drawStartOutputEmitterRef<HubSignatureDrawEvent>Wird ausgelöst, wenn ein Benutzer einen Strich beginnt, mit dem Zeiger oder der Tastatur. Erlaubt dem Host, auf Zeichenaktivität zu reagieren — etwa ein Autosave anzuhalten oder einen Absenden-Button scharf zu schalten — ohne den Wert abzufragen. HubSignatureDrawEvent ist PointerEvent | KeyboardEvent; mit instanceof eingrenzen, wenn das Eingabegerät eine Rolle spielt.
drawEndOutputEmitterRef<HubSignatureDrawEvent>Wird ausgelöst, wenn ein Benutzer einen Strich beendet, nachdem er übernommen wurde. Wird nur beim Zeichnen durch den Benutzer ausgelöst, sodass ein programmatisches Schreiben nie wie eines aussieht, und ein abgebrochener statt beendeter Strich — pointercancel, Escape, Fokusverlust der Fläche — löst nichts aus.
disabledChangeOutputEmitterRef<boolean>Die Schreibhälfte des Two-Way-[(disabled)]. Es wird auch ausgelöst, wenn Angular setDisabledState() aufruft — also wenn das gebundene Steuerelement deaktiviert oder aktiviert wird —, sodass ein Host, der [(disabled)] an ein reaktives Feld bindet, sieht, wie das Steuerelement es steuert.
requiredChangeOutputEmitterRef<boolean | null>Die Schreibhälfte des Two-Way-[(required)]. Bei einer reaktiven Bindung wird es immer ausgelöst, wenn sich der Status des Steuerelements ändert und sein required-Validator hinzugefügt oder entfernt wurde, woher dort der Wert stammt.

Methoden

Steuere signature aus dem Code heraus — 10 Methoden auf der programmatischen Schnittstelle.

NameSignaturRückgabeBeschreibung
clearclear(): void—Entfernt alle Striche und gibt den leeren Wert aus.
undoundo(): void—Entfernt den zuletzt übernommenen Strich.
redoredo(): void—Stellt den zuletzt rückgängig gemachten Strich wieder her.
cancelStrokecancelStroke(event?: PointerEvent): void—Verwirft den laufenden Strich, ohne ihn zu melden. An pointercancel gebunden und der Weg, den Escape und der Fokusverlust der Fläche nehmen: Eine abgebrochene Interaktion darf den Formularwert nicht erreichen.
toSvgtoSvg(): string—Gibt den skalierbaren SVG-Formularwert zurück.
toDataUrltoDataUrl(type?: string): string—Exportiert die gerenderte Signatur, standardmäßig als PNG.
resizeCanvasresizeCanvas(): void—Misst das Element neu, baut das Bitmap in Geräte-Pixeln neu auf und zeichnet neu. [height] führt es für dich aus; von Hand aufrufen, wenn das Feld sichtbar wird, nachdem es mit Breite null gelayoutet wurde — in einem geschlossenen Modal, einem inaktiven Tab, einem eingeklappten Accordion —, da die einzige automatische Messung beim ersten Rendern stattfindet und es keinen ResizeObserver gibt. Aufrufen, solange das Feld leer ist: Striche behalten die Koordinaten, in denen sie erfasst wurden, daher rahmt ein erneutes Messen eines signierten Feldes auf eine neue Breite die Signatur neu und lässt toSvg() eine viewBox ausgeben, die nicht mehr zur Geometrie darin passt.
isEmptyisEmpty(): booleanbooleanGibt an, ob etwas gezeichnet wurde. Erlaubt einem Formular, das Feld zu validieren, ohne das serialisierte SVG zu parsen, was zuvor die einzige Möglichkeit war.
toStrokestoStrokes(): HubSignatureStroke[]HubSignatureStroke[]Die übernommenen Striche als strukturierte Geometrie. toSvg() bleibt der kanonische Formularwert — dies ist für Aufrufer gedacht, die die Punkte selbst benötigen, etwa um eine Signatur abzuspielen oder von einer Bibliothek zu migrieren, die Punktgruppen speicherte.
fromStrokesfromStrokes(strokes: readonly HubSignatureStroke[]): void—Zeichnet das Feld aus strukturierter Geometrie neu. Ein programmatisches Schreiben wie writeValue(): Es meldet keine Benutzeränderung an Angular Forms.

Templates

Mach es zu deinem — 2 Template-Slots lassen dich eigenes Markup projizieren.

NameBeschreibungBeispiel
hubFormTextHilfetext als Markup, der den String [formText] im Block unter der Zeichenfläche ersetzt. Beide sind Exporte von ng-hub-ui-forms, sodass das für ein hub-input geschriebene Markup unverändert hierher wandert. Er behält seinen Platz im Block auch unter formTextType="tooltip", da der Tooltip einen String erwartet und das Markup verlieren würde — das Zeichen öffnet sich weiterhin mit dem String [formText].<ng-template hubFormText>Sign with a pointer, or carry the pen with <kbd>Space</kbd>.</ng-template>
hubValidationErrorDie Meldung für einen Validierungsfehlerschlüssel, vor [invalidFeedbackTemplateFn] und dem globalen Builder von provideHubForms(). Nur der benannte Schlüssel wird überschrieben; jeder andere Fehler fällt weiterhin auf den Builder zurück. Die Fehlerdaten kommen als impliziter Kontextwert an.<ng-template hubValidationError key="required">Sign before filing the contract.</ng-template>