从 angular2-signaturepad 迁移到 ng-hub-ui-signature

angular2-signaturepad 自 2022 年 2 月起没有发布过新版本。本指南把它的 API 对应到 ng-hub-ui-signature,展示同一个表单迁移前后的写法,并说明哪些内容无法沿用。新名称已对照库的源码核实,旧名称已对照已发布的 4.0.2 包核实。

1 · 为什么要迁移

angular2-signaturepad 的最后一个版本 4.0.2 发布于 2022 年 2 月 14 日。它的 peer 依赖只到 Angular 13,并把 signature_pad 固定为恰好 2.3.2。GitHub 仓库已归档,README 中说明作者已不再使用这个包,也无法协助解决问题。

如果你的应用停留在 Angular 13 或更早版本,没有必须迁移的压力。迁移的原因是 Angular 升级:ng-hub-ui-signature 需要 Angular 21 或更高版本,所以对大多数项目来说,框架升级才是大头,替换组件只是小头。

它不是原样替换。选择器、类、事件和数据方法都有变化,有些功能没有对应项(见对照表)。作为回报,这个字段是不依赖第三方绘图库的独立(standalone)组件,可以作为表单控件使用,以 SVG 保存签名,也可以用键盘签名。

2 · 安装与导入

移除旧包及其绘图库,然后安装该字段和两个配套包。字段的外观(标签、帮助文字、校验提示)由 ng-hub-ui-forms 提供样式,只需在全局样式表中加载一次。

迁移前

迁移后

无需导入模块:该组件是独立组件。peer 依赖为 Angular 21 或更高、ng-hub-ui-forms 22.31.0 或更高、ng-hub-ui-utils 22.9.0 或更高。

3 · API 对照

angular2-signaturepad 4.0.2 的全部公开成员,以及替代它们的内容。

迁移前迁移后说明
<signature-pad><hub-signature>已重命名。组件现在还会绘制标签、清除/撤销/重做按钮行、帮助文字和校验提示。只想要绘制区域时,请使用 [controls]="false"。
SignaturePadModule, SignaturePadHubSignatureComponent直接导入独立组件。provideHubSignature() 只配置操作按钮的文字,并不是模块的替代品。
[options] 无对应项 没有选项对象。每项设置都是单独的、带类型的 input。
options.penColor[strokeColor]默认值为 currentColor,会在笔画开始时解析为实际颜色,并随每一笔保存。
options.minWidth, options.maxWidth[strokeWidth]只有一个固定的笔画宽度,没有随速度变化的粗细。
options.canvasHeight[height]单位为 CSS 像素。之后再修改不会缩放已经画好的笔画。
options.canvasWidth 无对应项 字段会撑满其容器。请用 CSS 设置宽度。
options.backgroundColor, velocityFilterWeight, dotSize, throttle, minDistance 无对应项 无对应项。屏幕上的背景是一个 CSS 自定义属性(--hub-signature-bg),但导出的 PNG 是透明的。
(onBeginEvent)(drawStart)传出的值是 PointerEvent 或 KeyboardEvent,而不是 true。
(onEndEvent)(drawEnd)只有笔画被确认时才触发。被取消的笔画不会触发。
toDataURL(type, quality)toDataUrl(type)没有质量参数。导出的是画布位图,尺寸为设备像素大小,背景透明。
fromDataURL(dataURL) 无对应项 无对应项。已保存的 PNG 或 JPEG 无法重新载入用于编辑。
toData(), fromData()toStrokes(), fromStrokes()有意重命名。数据从 {x, y, time} 数组变为 {points, color, width} 对象,因此旧代码会在编译时报错,而不是悄悄出错。
clear(), isEmpty()clear(), isEmpty()名称相同。clear() 还会重置重做历史,并向表单报告空值。
resizeCanvas()resizeCanvas()名称相同,行为不同。旧方法会清空画板;这个方法保留签名并重新测量绘制区域。
on(), off()[readonly], [disabled]用 input 取代方法。它们还会改变样式和 ARIA 状态。
set(option, value), queryPad() 无对应项 没有运行时设置方法,也没有可以访问的内部库。请把 input 绑定到组件状态。
— toSvg(), undo(), redo(), (valueChange)新增。toSvg() 是规范的序列化结果,也是表单的值;valueChange 在用户每次修改后输出它。

4 · 典型用法:迁移前后对比

同一个同意书表单:先用旧组件和手动保存按钮,再用新组件作为响应式表单控件。

迁移前

迁移后

5 · 需要核对的行为差异

这些是替换之后最容易让人意外的差异。

  • 以 PNG 或 JPEG data URL 保存的签名无法重新载入用于编辑,因为没有 fromDataURL()。请把它们当作图片显示,或要求重新签名。不要把已保存的 data URL 传给必填控件:即使画板是空的,它也会被视为有效。
  • 笔画坐标是绝对值,因此保存的 SVG 只能在相同宽度的字段中如实重新载入。如果需要载入签名进行编辑,请用 CSS 固定宽度。
  • 笔画是宽度固定的折线,没有随速度变化的粗细,也没有平滑处理,因此新签名与已存档的签名看起来不同。
  • toDataUrl() 返回的是设备像素大小的透明 PNG,而不是固定尺寸的不透明图片。如果 PDF 或邮件环节需要白色背景,请自行添加,并且只在 (drawEnd) 或 (valueChange) 中导出,不要在笔画进行中导出。
  • 首次渲染在已关闭的模态框或未激活标签页中的字段,宽度为零。请在它变为可见、且仍为空时调用 resizeCanvas()。
  • 也可以用键盘签名:方向键移动笔,空格或回车落笔和抬笔,Escape 放弃当前笔画。因此 drawStart 和 drawEnd 传出的值可能是 KeyboardEvent,读取指针属性之前请先用 instanceof 收窄类型。

6 · 文档

该字段的完整参考和在线示例见其文档页面: ng-hub-ui-signature 文档