Angular 签名字段 | ng-hub-ui-signature

可访问的 Angular 签名字段,将鼠标、触摸和手写笔输入保存为可缩放 SVG 表单值,并支持撤销、重做和 PNG 导出。

API 参考

这里是 signature 的完整契约:你可以绑定、监听、投影和设置主题的一切,都集中在一处。接入你需要的部分,自定义你想要的样式——它是 standalone 的,且对 signal 友好。

输入

通过 18 个输入项精细调校 signature。像绑定任意 Angular @Input 一样绑定它们。

名称类型默认值描述
labelstring''可见的字段标签,同时也是绘制区域的无障碍名称:画布通过 aria-labelledby 与它关联,因此朗读的名称不会与可见文本不一致。点击标签会让绘制区域获得焦点。
formTextstring''字段的辅助文本。显示位置由 [formTextType] 决定:默认在绘制区域下方,或收在标签行末尾的问号后面。投影的 <ng-template hubFormText> 会替换下方区块中的字符串,即使在 tooltip 模式下它也保留在该区块中,因为 tooltip 只接受字符串,会丢掉标记。
formTextType'bottom' | 'tooltip''bottom'[formText] 的显示位置。bottom 将其放在绘制区域下方,无需请求即可阅读;tooltip 将其收在标签行末尾的问号后面,适用于超过一句话的内容。只要有辅助文本就会渲染该问号,包括仅由 [ariaLabel] 命名的裸绘制区域。其气泡会附加到 <body>,因此 tooltip 模式还需要 ng-hub-ui-utils 的 tooltip 样式表。
heightnumber160画布的逻辑高度,单位为 CSS 像素。
strokeColorstring'currentColor'新 SVG 笔画中记录的颜色。默认值 currentColor 会在捕获笔画之前相对于绘制区域解析,因此存档保存的是具体颜色,而不是画布无法解析的关键字。
strokeWidthnumber2新 SVG 笔画中记录的基础宽度。
readonlybooleanfalse禁止绘制,同时保留签名。
controlsbooleantrue显示清除、撤销和重做操作。
labelsPartial<HubSignatureLabels>{}仅对此字段覆盖应用级的已翻译操作标签。
ariaLabelstring''没有可见 [label] 的绘制区域的无障碍名称。有标签的字段通过 aria-labelledby 从该标签获取名称,因此两者不会不一致,此时不会参考该输入。留空时依次通过 [labels]、HUBUI.SIGNATURE.ARIA_LABEL 解析,最后使用英文回退值 Signature。
labelTypeHubLabelType'stacked'标签相对于字段的排布方式:'stacked' 或 'horizontal'。'floating' 会回退为 stacked,与该系列中其他非文本字段一致——浮动标签会占用空文本控件的值本应占据的空间,并由 :placeholder-shown 驱动,而画布两者都没有。
classliststring''应用于宿主元素 <hub-signature> 本身的额外类,而不是绘制区域,后者保留自己的 .hub-signature__canvas。请通过后代选择器为画布设置样式,或通过 --hub-signature-* 插槽进行主题化。
formControlNamestring—所在表单组中控件的名称。继承自 HubFormControl,后者自己声明了该输入,因此使用该字段的地方仍必须导入 ReactiveFormsModule:没有该指令时不会抛出任何错误,字段只是永远不会与表单同步。
requiredboolean | nullnull渲染必填星号,并在绘制区域上设置 aria-required。双向。在响应式绑定中,它由控件的校验器派生并与之保持同步,因此在那里手动绑定会被覆盖,并在开发模式下发出警告;仅在模板驱动或未绑定的字段上显式设置。
disabledbooleanfalse拒绝绘制,禁用操作行并设置 aria-disabled。双向,也会由 setDisabledState() 写入。在 formControlName 字段上,优先使用 control.disable() / control.enable():Angular 自己的指令也声明了 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>在由用户发起的更改之后(已提交的笔画、clear()、undo() 或 redo())触发 SVG 值;什么都不剩时触发空字符串。通过 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" 下它也保留在该区块中,因为 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>