Campo de firma para Angular | ng-hub-ui-signature

Campo de firma Angular accesible que guarda trazos de ratón, táctil y lápiz como SVG escalable para formularios, con deshacer, rehacer y exportación PNG.

Referencia API

Aquí tienes el contrato completo de signature: todo lo que puedes enlazar, escuchar, proyectar y personalizar, reunido en un solo sitio. Enlaza lo que necesites y dale el estilo que quieras — es standalone y reactivo con signals.

Inputs

Ajusta signature a tu gusto con 18 inputs. Se enlazan como cualquier @Input de Angular.

NombreTipoPor defectoDescripción
labelstring''Etiqueta visible del campo y nombre accesible de la superficie de dibujo: el canvas se vincula a ella con aria-labelledby, de modo que el nombre anunciado no puede desviarse del texto visible. Al hacer clic en ella se enfoca la superficie.
formTextstring''Texto de ayuda del campo. Dónde se muestra lo decide [formTextType]: debajo de la superficie de dibujo por defecto, o tras un signo de interrogación al final de la fila de la etiqueta. Un <ng-template hubFormText> proyectado sustituye a la cadena en el bloque inferior y conserva allí su sitio incluso en modo tooltip, porque un tooltip admite una cadena y perdería el marcado.
formTextType'bottom' | 'tooltip''bottom'Dónde se muestra [formText]. bottom lo coloca bajo la superficie de dibujo, donde se lee sin tener que pedirlo; tooltip lo cuelga tras un signo de interrogación al final de la fila de la etiqueta, para cualquier texto más largo que una frase. El signo se renderiza siempre que hay texto de ayuda, también en una superficie sin etiqueta nombrada solo por [ariaLabel]. Su burbuja se añade a <body>, así que el modo tooltip también necesita la hoja de estilos del tooltip de ng-hub-ui-utils.
heightnumber160Altura lógica del canvas en píxeles CSS.
strokeColorstring'currentColor'Color registrado en los nuevos trazos SVG. El valor por defecto currentColor se resuelve contra la superficie de dibujo antes de capturar el trazo, de modo que el archivo guarda un color concreto y no una palabra clave que el canvas no sabe interpretar.
strokeWidthnumber2Ancho base registrado en los nuevos trazos SVG.
readonlybooleanfalseImpide dibujar y conserva la firma.
controlsbooleantrueMuestra las acciones de borrar, deshacer y rehacer.
labelsPartial<HubSignatureLabels>{}Sobrescribe, solo para este campo, las etiquetas de acción traducidas de toda la aplicación.
ariaLabelstring''Nombre accesible para una superficie sin [label] visible. Un campo que tiene etiqueta toma su nombre de ella mediante aria-labelledby, de modo que ambos no pueden discrepar, y este input no se consulta. Si se deja vacío se resuelve mediante [labels], luego HUBUI.SIGNATURE.ARIA_LABEL y, por último, el texto de respaldo en inglés Signature.
labelTypeHubLabelType'stacked'Cómo se coloca la etiqueta respecto al campo: 'stacked' o 'horizontal'. 'floating' recurre a stacked, igual que en los demás campos no textuales de la familia: una etiqueta flotante reutiliza el espacio que ocuparía el valor de un control de texto vacío y depende de :placeholder-shown, que un canvas no tiene.
classliststring''Clases adicionales aplicadas al elemento host, el propio <hub-signature>, no a la superficie de dibujo, que mantiene su .hub-signature__canvas. El canvas se estiliza con un selector descendiente o mediante los slots --hub-signature-*.
formControlNamestring—Nombre del control dentro del grupo de formulario que lo contiene. Se hereda de HubFormControl, que lo declara como un input propio, por lo que ReactiveFormsModule debe seguir importándose donde se use el campo: sin la directiva no se lanza ningún error y el campo simplemente nunca se sincroniza con el formulario.
requiredboolean | nullnullRenderiza el asterisco de obligatorio y establece aria-required en la superficie. Bidireccional. En un enlace reactivo se deriva de los validadores del control y se mantiene alineado con ellos, así que enlazarlo a mano ahí se sobrescribe y avisa en modo desarrollo; solo debe establecerse explícitamente en un campo template-driven o sin enlazar.
disabledbooleanfalseRechaza el dibujo, deshabilita la fila de acciones y establece aria-disabled. Bidireccional, y también lo escribe setDisabledState(). En un campo con formControlName es preferible control.disable() / control.enable(): la directiva propia de Angular también declara un input disabled, por lo que un enlace llega a ambos y deja dos fuentes de verdad para un mismo estado.
showValidbooleanfalseEstado de éxito opcional. Un campo tocado y válido adopta el borde y el anillo de éxito en la superficie de dibujo, y renderiza [validFeedback] si se indica. Por defecto toma el valor global de provideHubForms({ showValid }); el estado de éxito nunca es automático. No tiene efecto mientras el campo es inválido.
validFeedbackstring | nullnullMensaje de éxito que se muestra bajo el campo. Requiere las dos mitades de la activación opcional: [showValid] activado y un control tocado y válido.
invalidFeedbackTemplateFn((key: string, value: any) => string) | nullnullSustitución por campo del generador del mensaje de feedback inválido, con prioridad sobre el global de provideHubForms(). Para marcado en lugar de una cadena, se proyecta en su lugar un <ng-template hubValidationError key="required">: la plantilla prevalece sobre ambos.

Outputs

Reacciona a lo que hace signature: 5 eventos a los que enganchar tu lógica.

NombreTipoDescripción
valueChangeOutputEmitterRef<string>Emite el valor SVG tras un cambio originado por el usuario (un trazo confirmado, clear(), undo() o redo()) y la cadena vacía cuando no queda nada. Una escritura programática mediante writeValue() o fromStrokes() no emite nada, de modo que nunca devuelve el eco al propio formulario.
drawStartOutputEmitterRef<HubSignatureDrawEvent>Se emite cuando el usuario empieza un trazo, con el puntero o con el teclado. Permite al host reaccionar a la actividad de dibujo (pausar un autoguardado, activar un botón de envío) sin consultar el valor periódicamente. HubSignatureDrawEvent es PointerEvent | KeyboardEvent; se estrecha con instanceof cuando importa el dispositivo de entrada.
drawEndOutputEmitterRef<HubSignatureDrawEvent>Se emite cuando el usuario termina un trazo, después de confirmarlo. Se dispara solo con el dibujo del usuario, de modo que una escritura programática nunca lo parece, y un trazo cancelado en lugar de terminado (pointercancel, Escape, el foco abandonando la superficie) no emite nada.
disabledChangeOutputEmitterRef<boolean>La mitad de escritura del [(disabled)] bidireccional. También se dispara cuando Angular llama a setDisabledState(), es decir, cuando el control enlazado se deshabilita o se habilita, de modo que un host que enlaza [(disabled)] en un campo reactivo ve cómo lo gobierna el control.
requiredChangeOutputEmitterRef<boolean | null>La mitad de escritura del [(required)] bidireccional. En un enlace reactivo se dispara siempre que cambia el estado del control y se ha añadido o quitado su validador required, que es de donde procede ahí el valor.

Métodos

Controla signature desde el código — 10 métodos en su superficie programática.

NombreFirmaDevuelveDescripción
clearclear(): void—Elimina todos los trazos y emite el valor vacío.
undoundo(): void—Elimina el último trazo confirmado.
redoredo(): void—Restaura el último trazo deshecho.
cancelStrokecancelStroke(event?: PointerEvent): void—Descarta el trazo en curso sin notificarlo. Está vinculado a pointercancel y es el camino que siguen Escape y la pérdida de foco de la superficie: una interacción cancelada no debe llegar al valor del formulario.
toSvgtoSvg(): string—Devuelve el valor de formulario en SVG escalable.
toDataUrltoDataUrl(type?: string): string—Exporta la firma renderizada, en PNG por defecto.
resizeCanvasresizeCanvas(): void—Vuelve a medir el elemento, reconstruye el bitmap en píxeles de dispositivo y repinta. [height] lo ejecuta por ti; llámalo a mano cuando el campo pasa a ser visible tras haberse maquetado con ancho cero (dentro de un modal cerrado, una pestaña inactiva, un acordeón colapsado), ya que la única medición automática ocurre en el primer renderizado y no hay ResizeObserver. Llámalo mientras el campo esté vacío: los trazos conservan las coordenadas con las que se capturaron, así que volver a medir un campo ya firmado con otro ancho reencuadra la firma y hace que toSvg() emita un viewBox que ya no coincide con la geometría interior.
isEmptyisEmpty(): booleanbooleanIndica si se ha dibujado algo. Permite a un formulario validar el campo sin analizar el SVG serializado, que antes era la única forma de preguntarlo.
toStrokestoStrokes(): HubSignatureStroke[]HubSignatureStroke[]Los trazos confirmados como geometría estructurada. toSvg() sigue siendo el valor canónico del formulario; esto es para quien necesita los propios puntos, por ejemplo para reproducir una firma o migrar desde una librería que guardaba grupos de puntos.
fromStrokesfromStrokes(strokes: readonly HubSignatureStroke[]): void—Repinta el campo a partir de geometría estructurada. Es una escritura programática, como writeValue(): no notifica un cambio del usuario a los formularios de Angular.

Templates

Hazlo tuyo — 2 plantillas para proyectar tu propio marcado.

NombreDescripciónEjemplo
hubFormTextTexto de ayuda como marcado, que sustituye a la cadena [formText] en el bloque bajo la superficie de dibujo. Ambos son exports de ng-hub-ui-forms, así que el marcado escrito para un hub-input se traslada aquí sin cambios. Conserva su sitio en el bloque incluso con formTextType="tooltip", porque el tooltip admite una cadena y perdería el marcado; el signo sigue abriéndose con la cadena [formText].<ng-template hubFormText>Sign with a pointer, or carry the pen with <kbd>Space</kbd>.</ng-template>
hubValidationErrorEl mensaje para una clave de error de validación, con prioridad sobre [invalidFeedbackTemplateFn] y sobre el generador global de provideHubForms(). Solo se sustituye la clave que nombra; cualquier otro error sigue recurriendo al generador. La carga del error llega como valor implícito del contexto.<ng-template hubValidationError key="required">Sign before filing the contract.</ng-template>