从 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, SignaturePad | HubSignatureComponent | 直接导入独立组件。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 文档