简介面向 iOS 开发者的轻量级 PDF 电子签章集成方案聚焦在移动端合同、协议等文档场景中快速嵌入签章能力。资源以原生静态库形式提供开发者通过少量代码即可将签章 PDF 控制器推入导航栈完成展示适合需要为业务 App 补充合同签署与预览功能的中初级 iOS 工程师参考。压缩包共 7 个文件包含 4 个 .a 静态库、2 个 .h 头文件与 1 个 .mm 实现文件整体约 55.69MB体积控制较为克制便于直接拖入工程链接使用。已有 644 人学习下载具备一定的实践参考基础。资源核心价值在于把签章渲染与 PDF 加载封装为可直接调用的控制器头文件暴露清晰接口配合实现文件可了解内部调用链路帮助读者省去从零搭建签章展示层的时间快速验证合同签署页的交互与显示效果并在此基础上按业务需求做二次扩展。1. 需求先立住为什么 iOS 端 PDF 电子签章不能只做“贴图”接到“iOS PDF 电子签章”这个需求时很多人的第一反应是不就是把签名图片盖到 PDF 上吗真动手才发现贴图只是最表层的一步。一份能交付的电子签章方案至少要同时回答四个问题签名笔迹怎么采集才不失真、签章盖上去之后 PDF 结构是否还合法、多页文档里签章位置怎么精确定位、签完的文件能不能被验证而不是“看起来像签了”。这四个问题任何一个翻车交付物就是一张好看的截图而不是一份可用的电子文档。这套方案面向两类人正在做移动端毕设或课程设计、需要一套完整可讲的技术链路的学生以及要在 iOS 应用里落地合同签署、单据确认这类功能的开发者。下面按“需求拆解 → 总体设计 → 核心模块实现 → 避坑 → 验收答辩”的顺序展开中间给到可以直接改参数复用的代码和结构读完能照着搭出一版能跑、能讲、能验收的签章流程。2. 需求拆解与技术选型四个能力域和一条数据主线先把“电子签章”这个词拆开。它不是一个功能而是四个能力域的组合手写签名采集、签章图元生成、PDF 页面合成、签署结果校验。四个域之间靠一条数据主线串起来——用户在画布上落笔产生的笔迹点序列经过平滑与压缩变成签名图元再按页面坐标映射盖到 PDF 指定位置最后整份文档落盘并留出可校验的痕迹。这条主线定清楚了后面每个模块的输入输出就不会打架。2.1 能力域划分与职责边界能力域输入输出关键约束签名采集触摸事件序列归一化笔迹点集采样率稳定、坐标与画布解耦图元生成笔迹点集透明背景签名图边缘抗锯齿、尺寸可缩放PDF 合成原 PDF 图元 坐标签署后 PDF不破坏原文档结构结果校验签署后 PDF校验结论能定位签章、能比对内容职责边界要卡死采集层不关心 PDF合成层不关心笔迹怎么来的。很多项目后期改不动就是因为采集代码里顺手把图片直接画进了 PDF 上下文耦合在一起换个签名样式就得动整条链路。2.2 iOS 侧技术栈取舍PDF 渲染与合成在 iOS 上有两条主流路线一条是基于 PDFKit 做展示、用 Core Graphics 的 PDF 上下文做合成另一条是全程走 Core Graphics 自己管页面。我的建议是展示用 PDFKit、合成用 Core Graphics原因是 PDFKit 的页面渲染和缩放体验成熟而合成阶段需要精确控制绘制顺序和坐标变换直接操作 CGPDFContext 更可控。签名采集用 UIView 子类接管 touchesBegan/Moved/Ended配合 UIBezierPath 做平滑图元导出走 UIGraphicsImageRenderer输出带 alpha 通道的 PNG。坐标映射是整条链路最容易出错的地方统一约定“以 PDF 页面左下角为原点、单位为 point”在合成前做一次坐标系翻转后面所有模块都按这个约定走能省掉大量“签章位置偏了”的排查时间。提示不要用截图方式获取签名图。截图会带上背景色和屏幕缩放盖到 PDF 上边缘发虚打印出来尤其明显。2.3 数据主线与状态流转一条签署任务的状态建议显式建模而不是散落在各个 ViewController 里待签署 → 采集中 → 图元就绪 → 合成中 → 已签署 → 校验通过/失败。每个状态对应一个明确的产物采集中产出笔迹点集图元就绪产出 PNG 数据合成中产出临时文件已签署产出最终文件路径。状态机的好处是异常可回滚——合成失败时能退回图元就绪让用户重新定位签章而不是从头再签一遍。这条主线也是答辩时最容易被追问的地方讲清楚状态和产物比讲界面怎么画更有说服力。3. 总体架构设计三层结构与签署流水线架构上我一般分三层表现层负责签名画布和 PDF 预览领域层负责笔迹处理、坐标映射和签章图元基础设施层负责 PDF 读写、文件存储和校验。三层之间只通过数据对象通信不互相持有视图引用。这样拆的直接收益是签名画布可以单独做单元测试PDF 合成可以在没有界面的情况下跑通验收时能分层演示。3.1 签署流水线的五个阶段整条流水线是加载文档 → 选择签章位置 → 采集签名 → 生成图元并合成 → 落盘校验。每个阶段有独立的失败处理。加载阶段要处理加密 PDF 和损坏文件定位阶段要处理页面旋转采集阶段要处理手指抬起过快导致的点太少合成阶段要处理图元超出页面边界校验阶段要处理签章被后续编辑覆盖。把失败分支提前列出来代码里就不会到处是“理论上不会发生”的假设。3.2 坐标映射模块的设计坐标映射是这套方案的核心难点单独拎出来说。PDF 页面有自己的 MediaBox 和 CropBox页面还可能带旋转角屏幕上的预览视图有缩放和平移。用户点选的位置是视图坐标要经过“视图坐标 → 页面显示坐标 → PDF 用户坐标”两次变换才能用于绘制。我的做法是封装一个 PageCoordinateMapper持有页面尺寸、旋转角和当前缩放比例对外只暴露两个方法视图点转 PDF 点、PDF 矩形转视图矩形。所有涉及位置的代码只调这两个方法不在业务层手写换算公式。struct PageCoordinateMapper { let pageSize: CGSize // PDF 页面尺寸单位 point let rotation: Int // 页面旋转角0/90/180/270 let scale: CGFloat // 预览缩放比例 // 视图坐标 - PDF 用户坐标原点左下 func pdfPoint(fromViewPoint p: CGPoint, viewHeight: CGFloat) - CGPoint { let x p.x / scale let y (viewHeight - p.y) / scale // 翻转 Y 轴 switch rotation { case 90: return CGPoint(x: y, y: pageSize.width - x) case 180: return CGPoint(x: pageSize.width - x, y: pageSize.height - y) case 270: return CGPoint(x: pageSize.height - y, y: x) default: return CGPoint(x: x, y: y) } } }这段代码的关键在两点Y 轴翻转和旋转补偿。iOS 视图坐标原点在左上、Y 向下PDF 用户坐标原点在左下、Y 向上不翻转就会出现“签章上下颠倒”。旋转补偿按 90 度一档处理因为绝大多数扫描件和导出文档的旋转都是直角。参数里 scale 是预览缩放比用户放大查看时点选位置仍然准确靠的就是这里统一除回去。实际项目里我会给这个结构体补一组单元测试用四个旋转角各跑一遍已知点映射错了当场暴露比在界面上肉眼比对靠谱得多。3.3 模块依赖与文件组织工程目录按层组织SignCanvas 放画布与笔迹处理PDFPipeline 放加载、合成、校验Coordinate 放映射Models 放状态与数据对象。依赖方向单向表现层依赖领域层领域层依赖基础设施层反向不允许。这样组织之后新增一种签章样式比如带边框的印章式签名只需要在领域层加一个图元生成策略合成和校验完全不用动。答辩时被问到“扩展性在哪”这就是现成的答案。4. 核心模块实现签名采集、图元生成与 PDF 合成这一章落到能跑的代码。三个模块按数据流顺序讲先采笔迹再出图元最后合成进 PDF。每段代码后面说清楚参数怎么调、失败时看哪里。4.1 签名画布与笔迹平滑直接用 UIBezierPath 逐点连线快速书写时会出现明显折线。常规做法是记录触摸点并做二次贝塞尔平滑每三个点确定一段曲线用中点作为控制点。采样上不需要每个触摸事件都存按时间或距离做一次抽稀既能减小数据量又不影响观感。final class SignCanvas: UIView { private var points: [CGPoint] [] private var lastPoint: CGPoint? override func touchesMoved(_ touches: SetUITouch, with event: UIEvent?) { guard let p touches.first?.location(in: self) else { return } // 距离抽稀移动超过 1.5pt 才记录避免点过密 if let last lastPoint, hypot(p.x - last.x, p.y - last.y) 1.5 { return } points.append(p) lastPoint p setNeedsDisplay() } override func draw(_ rect: CGRect) { guard points.count 1 else { return } let path UIBezierPath() path.move(to: points[0]) for i in 1..points.count { let mid CGPoint(x: (points[i-1].x points[i].x) / 2, y: (points[i-1].y points[i].y) / 2) path.addQuadCurve(to: mid, controlPoint: points[i-1]) } UIColor.black.setStroke() path.lineWidth 2.5 path.lineCapStyle .round path.stroke() } }抽稀阈值 1.5pt 是经验值太小点集膨胀、平滑没意义太大笔迹会丢细节。线宽 2.5 配合圆头端点缩放到 A4 尺寸打印时粗细接近真实签字笔。如果项目要求压感可以在 touchesMoved 里读 force 并映射到线宽但要注意不是所有设备都支持取值前先判断 availability否则就是玄学问题——同一份代码在不同机型上笔迹粗细不一致。4.2 签名图元导出与透明背景图元导出的核心是透明背景和固定像素密度。用 UIGraphicsImageRenderer 指定 scale导出 PNG 保留 alpha 通道。尺寸上不要按画布原始大小导出而是按目标签章在 PDF 上的物理尺寸反推像素避免盖上去模糊。func exportSignature(from canvas: SignCanvas, targetSizeInPoints: CGSize) - Data? { // 按 2 倍密度导出兼顾清晰度与体积 let format UIGraphicsImageRendererFormat() format.scale 2.0 format.opaque false // 关键保留透明背景 let renderer UIGraphicsImageRenderer(size: targetSizeInPoints, format: format) let image renderer.image { ctx in canvas.layer.render(in: ctx.cgContext) } return image.pngData() }opaque 设为 false 是这段代码里最不能省的一行设成 true 背景会变成黑色或白色实底盖到 PDF 上就是一块补丁。targetSizeInPoints 由签章框的物理尺寸决定通常一个手写签名框在 A4 上取 120×50pt 左右比较自然。导出后建议顺手校验一下 PNG 的 alpha 通道是否存在有些第三方图片处理库转码时会丢掉透明通道这是踩过的坑。4.3 PDF 合成在指定页面盖签章合成阶段用 CGPDFContext 打开原文档逐页复制在目标页绘制签章图元。要点有三个保持原文档的页面属性和元数据、绘制时用 saveGState/restoreGState 隔离变换、签章位置做边界裁剪防止越界。func stampSignature(source: URL, output: URL, pageIndex: Int, rect: CGRect, image: UIImage) throws { guard let doc CGPDFDocument(source as CFURL) else { throw StampError.invalidPDF } let ctx CGContext(output as CFURL, mediaBox: nil, nil) // mediaBox 传 nil 时沿用每页原始尺寸 for i in 1...doc.numberOfPages { guard let page doc.page(at: i) else { continue } var box page.getBoxRect(.mediaBox) ctx?.beginPage(mediaBox: box) ctx?.drawPDFPage(page) if i pageIndex { ctx?.saveGState() // 裁剪到页面范围防止签章越界污染其他内容 ctx?.clip(to: box) image.draw(in: rect) ctx?.restoreGState() } ctx?.endPage() } ctx?.closePDF() }beginPage 的 mediaBox 传每页原始尺寸保证输出文档和原件页面一致这一点在验收时会被检查——页面尺寸变了打印排版就全乱了。clip 到页面范围是防御性写法用户把签章拖到边缘时不会画出页面外。pageIndex 从 1 开始和 CGPDFDocument 的页码约定一致业务层如果习惯从 0 开始在调用前统一加一别在两处各写一套。合成失败最常见的现象是输出文件打不开先查 closePDF 有没有被调用再查输出路径是否可写。4.4 签署结果校验校验分两层结构层确认 PDF 能被正常解析、页数一致内容层确认签章图元出现在预期页面和位置。结构层用 CGPDFDocument 重新打开输出文件即可内容层可以在合成时把签章矩形记录进一个伴随的元数据文件校验时读取比对。更严格的做法是对签署前后的页面做像素级差异比对差异区域应集中在签章矩形内超出范围说明合成逻辑有问题。这套校验不追求密码学意义上的不可篡改但足以支撑课程设计和内部交付的验收演示。5. 避坑与排查五个最容易翻车的点5.1 签章位置偏移或上下颠倒现象预览里位置对导出后签章跑到页面另一侧或上下翻转。原因基本是坐标系没统一视图坐标直接拿去绘制或者旋转角没参与换算。解决所有位置换算只走 PageCoordinateMapper合成前打印一次映射前后的坐标做比对四个旋转角各测一遍。5.2 签名图边缘发虚或带底色现象签章盖上去边缘模糊或者背后有一块白底。原因是导出时 opaque 设为 true或者用了截图方式取图。解决导出统一走 UIGraphicsImageRenderer 并设 opaque false导出后检查 PNG 是否含 alpha 通道。5.3 大文档合成卡顿甚至内存告警现象几十页的 PDF 合成时界面卡死或直接被杀进程。原因是逐页绘制在主线程进行且一次性持有所有页面位图。解决合成放到后台队列逐页处理、逐页释放不要缓存整份文档的位图进度用回调回传主线程更新。5.4 加密或损坏 PDF 直接崩溃现象加载某些 PDF 时 CGPDFDocument 返回 nil后续强制解包崩溃。原因是没做空值判断加密文档需要先解锁。解决加载后先判空并给出明确错误提示加密文档走密码输入流程损坏文件直接拒绝并提示用户不要试图“修复”。5.5 签署后文件被二次编辑导致校验失败现象校验时发现签章位置的内容和记录不符。原因是签署后的文件又被其他工具改过。解决校验时同时比对页面尺寸、页数和签章区域像素差异任一不符即判定文件已变更交付时保留签署记录文件作为比对基准。6. 验收与答辩用一条可复现的检查链说话验收这套方案我习惯准备一条固定的检查链从文件到界面逐层过任何一层不过就不算完成。答辩时按这条链演示比讲架构图更有说服力因为每一步都有可见的产物。检查项操作通过标准文档加载打开普通、加密、损坏三类 PDF普通正常显示加密走密码流程损坏有明确提示不崩溃签名采集快速书写、慢速书写各一次笔迹平滑无明显折线抽稀后仍保留细节图元质量导出后放大查看边缘边缘抗锯齿、背景透明、无白底位置精度四个旋转角各盖一次签章落在点选位置无偏移无翻转结构完整用系统预览和第三方阅读器各打开一次页数、页面尺寸与原文档一致可正常打印校验闭环对签署后文件跑一次校验结构层与内容层均通过篡改后能报出差异演示顺序建议按数据主线走先展示一份原始 PDF现场签一次展示图元导出结果再展示合成后的文件在阅读器里的效果最后跑校验。中间故意制造一次失败——比如把签章拖到页面边缘——展示边界裁剪生效这比全程顺利更能说明方案考虑过异常。答辩提问高频集中在坐标映射和透明背景两处提前把映射前后的坐标打印出来备着被问到直接给数据。血泪经验是早期我总在最后一天才做整链验收结果发现加密 PDF 崩溃和旋转页偏移两个问题返工把合成模块重写了一半。从那以后我每次改完合成逻辑都强制走一遍上面这条检查链哪怕只改了一行坐标换算。希望这套结构和检查链能帮到你把签章这件事从“看起来像”做到“验得过”。本文还有配套的精品资源点击获取
简介面向 iOS 开发者的轻量级 PDF 电子签章集成方案聚焦在移动端合同、协议等文档场景中快速嵌入签章能力。资源以原生静态库形式提供开发者通过少量代码即可将签章 PDF 控制器推入导航栈完成展示适合需要为业务 App 补充合同签署与预览功能的中初级 iOS 工程师参考。压缩包共 7 个文件包含 4 个 .a 静态库、2 个 .h 头文件与 1 个 .mm 实现文件整体约 55.69MB体积控制较为克制便于直接拖入工程链接使用。已有 644 人学习下载具备一定的实践参考基础。资源核心价值在于把签章渲染与 PDF 加载封装为可直接调用的控制器头文件暴露清晰接口配合实现文件可了解内部调用链路帮助读者省去从零搭建签章展示层的时间快速验证合同签署页的交互与显示效果并在此基础上按业务需求做二次扩展。1. 需求先立住为什么 iOS 端 PDF 电子签章不能只做“贴图”接到“iOS PDF 电子签章”这个需求时很多人的第一反应是不就是把签名图片盖到 PDF 上吗真动手才发现贴图只是最表层的一步。一份能交付的电子签章方案至少要同时回答四个问题签名笔迹怎么采集才不失真、签章盖上去之后 PDF 结构是否还合法、多页文档里签章位置怎么精确定位、签完的文件能不能被验证而不是“看起来像签了”。这四个问题任何一个翻车交付物就是一张好看的截图而不是一份可用的电子文档。这套方案面向两类人正在做移动端毕设或课程设计、需要一套完整可讲的技术链路的学生以及要在 iOS 应用里落地合同签署、单据确认这类功能的开发者。下面按“需求拆解 → 总体设计 → 核心模块实现 → 避坑 → 验收答辩”的顺序展开中间给到可以直接改参数复用的代码和结构读完能照着搭出一版能跑、能讲、能验收的签章流程。2. 需求拆解与技术选型四个能力域和一条数据主线先把“电子签章”这个词拆开。它不是一个功能而是四个能力域的组合手写签名采集、签章图元生成、PDF 页面合成、签署结果校验。四个域之间靠一条数据主线串起来——用户在画布上落笔产生的笔迹点序列经过平滑与压缩变成签名图元再按页面坐标映射盖到 PDF 指定位置最后整份文档落盘并留出可校验的痕迹。这条主线定清楚了后面每个模块的输入输出就不会打架。2.1 能力域划分与职责边界能力域输入输出关键约束签名采集触摸事件序列归一化笔迹点集采样率稳定、坐标与画布解耦图元生成笔迹点集透明背景签名图边缘抗锯齿、尺寸可缩放PDF 合成原 PDF 图元 坐标签署后 PDF不破坏原文档结构结果校验签署后 PDF校验结论能定位签章、能比对内容职责边界要卡死采集层不关心 PDF合成层不关心笔迹怎么来的。很多项目后期改不动就是因为采集代码里顺手把图片直接画进了 PDF 上下文耦合在一起换个签名样式就得动整条链路。2.2 iOS 侧技术栈取舍PDF 渲染与合成在 iOS 上有两条主流路线一条是基于 PDFKit 做展示、用 Core Graphics 的 PDF 上下文做合成另一条是全程走 Core Graphics 自己管页面。我的建议是展示用 PDFKit、合成用 Core Graphics原因是 PDFKit 的页面渲染和缩放体验成熟而合成阶段需要精确控制绘制顺序和坐标变换直接操作 CGPDFContext 更可控。签名采集用 UIView 子类接管 touchesBegan/Moved/Ended配合 UIBezierPath 做平滑图元导出走 UIGraphicsImageRenderer输出带 alpha 通道的 PNG。坐标映射是整条链路最容易出错的地方统一约定“以 PDF 页面左下角为原点、单位为 point”在合成前做一次坐标系翻转后面所有模块都按这个约定走能省掉大量“签章位置偏了”的排查时间。提示不要用截图方式获取签名图。截图会带上背景色和屏幕缩放盖到 PDF 上边缘发虚打印出来尤其明显。2.3 数据主线与状态流转一条签署任务的状态建议显式建模而不是散落在各个 ViewController 里待签署 → 采集中 → 图元就绪 → 合成中 → 已签署 → 校验通过/失败。每个状态对应一个明确的产物采集中产出笔迹点集图元就绪产出 PNG 数据合成中产出临时文件已签署产出最终文件路径。状态机的好处是异常可回滚——合成失败时能退回图元就绪让用户重新定位签章而不是从头再签一遍。这条主线也是答辩时最容易被追问的地方讲清楚状态和产物比讲界面怎么画更有说服力。3. 总体架构设计三层结构与签署流水线架构上我一般分三层表现层负责签名画布和 PDF 预览领域层负责笔迹处理、坐标映射和签章图元基础设施层负责 PDF 读写、文件存储和校验。三层之间只通过数据对象通信不互相持有视图引用。这样拆的直接收益是签名画布可以单独做单元测试PDF 合成可以在没有界面的情况下跑通验收时能分层演示。3.1 签署流水线的五个阶段整条流水线是加载文档 → 选择签章位置 → 采集签名 → 生成图元并合成 → 落盘校验。每个阶段有独立的失败处理。加载阶段要处理加密 PDF 和损坏文件定位阶段要处理页面旋转采集阶段要处理手指抬起过快导致的点太少合成阶段要处理图元超出页面边界校验阶段要处理签章被后续编辑覆盖。把失败分支提前列出来代码里就不会到处是“理论上不会发生”的假设。3.2 坐标映射模块的设计坐标映射是这套方案的核心难点单独拎出来说。PDF 页面有自己的 MediaBox 和 CropBox页面还可能带旋转角屏幕上的预览视图有缩放和平移。用户点选的位置是视图坐标要经过“视图坐标 → 页面显示坐标 → PDF 用户坐标”两次变换才能用于绘制。我的做法是封装一个 PageCoordinateMapper持有页面尺寸、旋转角和当前缩放比例对外只暴露两个方法视图点转 PDF 点、PDF 矩形转视图矩形。所有涉及位置的代码只调这两个方法不在业务层手写换算公式。struct PageCoordinateMapper { let pageSize: CGSize // PDF 页面尺寸单位 point let rotation: Int // 页面旋转角0/90/180/270 let scale: CGFloat // 预览缩放比例 // 视图坐标 - PDF 用户坐标原点左下 func pdfPoint(fromViewPoint p: CGPoint, viewHeight: CGFloat) - CGPoint { let x p.x / scale let y (viewHeight - p.y) / scale // 翻转 Y 轴 switch rotation { case 90: return CGPoint(x: y, y: pageSize.width - x) case 180: return CGPoint(x: pageSize.width - x, y: pageSize.height - y) case 270: return CGPoint(x: pageSize.height - y, y: x) default: return CGPoint(x: x, y: y) } } }这段代码的关键在两点Y 轴翻转和旋转补偿。iOS 视图坐标原点在左上、Y 向下PDF 用户坐标原点在左下、Y 向上不翻转就会出现“签章上下颠倒”。旋转补偿按 90 度一档处理因为绝大多数扫描件和导出文档的旋转都是直角。参数里 scale 是预览缩放比用户放大查看时点选位置仍然准确靠的就是这里统一除回去。实际项目里我会给这个结构体补一组单元测试用四个旋转角各跑一遍已知点映射错了当场暴露比在界面上肉眼比对靠谱得多。3.3 模块依赖与文件组织工程目录按层组织SignCanvas 放画布与笔迹处理PDFPipeline 放加载、合成、校验Coordinate 放映射Models 放状态与数据对象。依赖方向单向表现层依赖领域层领域层依赖基础设施层反向不允许。这样组织之后新增一种签章样式比如带边框的印章式签名只需要在领域层加一个图元生成策略合成和校验完全不用动。答辩时被问到“扩展性在哪”这就是现成的答案。4. 核心模块实现签名采集、图元生成与 PDF 合成这一章落到能跑的代码。三个模块按数据流顺序讲先采笔迹再出图元最后合成进 PDF。每段代码后面说清楚参数怎么调、失败时看哪里。4.1 签名画布与笔迹平滑直接用 UIBezierPath 逐点连线快速书写时会出现明显折线。常规做法是记录触摸点并做二次贝塞尔平滑每三个点确定一段曲线用中点作为控制点。采样上不需要每个触摸事件都存按时间或距离做一次抽稀既能减小数据量又不影响观感。final class SignCanvas: UIView { private var points: [CGPoint] [] private var lastPoint: CGPoint? override func touchesMoved(_ touches: SetUITouch, with event: UIEvent?) { guard let p touches.first?.location(in: self) else { return } // 距离抽稀移动超过 1.5pt 才记录避免点过密 if let last lastPoint, hypot(p.x - last.x, p.y - last.y) 1.5 { return } points.append(p) lastPoint p setNeedsDisplay() } override func draw(_ rect: CGRect) { guard points.count 1 else { return } let path UIBezierPath() path.move(to: points[0]) for i in 1..points.count { let mid CGPoint(x: (points[i-1].x points[i].x) / 2, y: (points[i-1].y points[i].y) / 2) path.addQuadCurve(to: mid, controlPoint: points[i-1]) } UIColor.black.setStroke() path.lineWidth 2.5 path.lineCapStyle .round path.stroke() } }抽稀阈值 1.5pt 是经验值太小点集膨胀、平滑没意义太大笔迹会丢细节。线宽 2.5 配合圆头端点缩放到 A4 尺寸打印时粗细接近真实签字笔。如果项目要求压感可以在 touchesMoved 里读 force 并映射到线宽但要注意不是所有设备都支持取值前先判断 availability否则就是玄学问题——同一份代码在不同机型上笔迹粗细不一致。4.2 签名图元导出与透明背景图元导出的核心是透明背景和固定像素密度。用 UIGraphicsImageRenderer 指定 scale导出 PNG 保留 alpha 通道。尺寸上不要按画布原始大小导出而是按目标签章在 PDF 上的物理尺寸反推像素避免盖上去模糊。func exportSignature(from canvas: SignCanvas, targetSizeInPoints: CGSize) - Data? { // 按 2 倍密度导出兼顾清晰度与体积 let format UIGraphicsImageRendererFormat() format.scale 2.0 format.opaque false // 关键保留透明背景 let renderer UIGraphicsImageRenderer(size: targetSizeInPoints, format: format) let image renderer.image { ctx in canvas.layer.render(in: ctx.cgContext) } return image.pngData() }opaque 设为 false 是这段代码里最不能省的一行设成 true 背景会变成黑色或白色实底盖到 PDF 上就是一块补丁。targetSizeInPoints 由签章框的物理尺寸决定通常一个手写签名框在 A4 上取 120×50pt 左右比较自然。导出后建议顺手校验一下 PNG 的 alpha 通道是否存在有些第三方图片处理库转码时会丢掉透明通道这是踩过的坑。4.3 PDF 合成在指定页面盖签章合成阶段用 CGPDFContext 打开原文档逐页复制在目标页绘制签章图元。要点有三个保持原文档的页面属性和元数据、绘制时用 saveGState/restoreGState 隔离变换、签章位置做边界裁剪防止越界。func stampSignature(source: URL, output: URL, pageIndex: Int, rect: CGRect, image: UIImage) throws { guard let doc CGPDFDocument(source as CFURL) else { throw StampError.invalidPDF } let ctx CGContext(output as CFURL, mediaBox: nil, nil) // mediaBox 传 nil 时沿用每页原始尺寸 for i in 1...doc.numberOfPages { guard let page doc.page(at: i) else { continue } var box page.getBoxRect(.mediaBox) ctx?.beginPage(mediaBox: box) ctx?.drawPDFPage(page) if i pageIndex { ctx?.saveGState() // 裁剪到页面范围防止签章越界污染其他内容 ctx?.clip(to: box) image.draw(in: rect) ctx?.restoreGState() } ctx?.endPage() } ctx?.closePDF() }beginPage 的 mediaBox 传每页原始尺寸保证输出文档和原件页面一致这一点在验收时会被检查——页面尺寸变了打印排版就全乱了。clip 到页面范围是防御性写法用户把签章拖到边缘时不会画出页面外。pageIndex 从 1 开始和 CGPDFDocument 的页码约定一致业务层如果习惯从 0 开始在调用前统一加一别在两处各写一套。合成失败最常见的现象是输出文件打不开先查 closePDF 有没有被调用再查输出路径是否可写。4.4 签署结果校验校验分两层结构层确认 PDF 能被正常解析、页数一致内容层确认签章图元出现在预期页面和位置。结构层用 CGPDFDocument 重新打开输出文件即可内容层可以在合成时把签章矩形记录进一个伴随的元数据文件校验时读取比对。更严格的做法是对签署前后的页面做像素级差异比对差异区域应集中在签章矩形内超出范围说明合成逻辑有问题。这套校验不追求密码学意义上的不可篡改但足以支撑课程设计和内部交付的验收演示。5. 避坑与排查五个最容易翻车的点5.1 签章位置偏移或上下颠倒现象预览里位置对导出后签章跑到页面另一侧或上下翻转。原因基本是坐标系没统一视图坐标直接拿去绘制或者旋转角没参与换算。解决所有位置换算只走 PageCoordinateMapper合成前打印一次映射前后的坐标做比对四个旋转角各测一遍。5.2 签名图边缘发虚或带底色现象签章盖上去边缘模糊或者背后有一块白底。原因是导出时 opaque 设为 true或者用了截图方式取图。解决导出统一走 UIGraphicsImageRenderer 并设 opaque false导出后检查 PNG 是否含 alpha 通道。5.3 大文档合成卡顿甚至内存告警现象几十页的 PDF 合成时界面卡死或直接被杀进程。原因是逐页绘制在主线程进行且一次性持有所有页面位图。解决合成放到后台队列逐页处理、逐页释放不要缓存整份文档的位图进度用回调回传主线程更新。5.4 加密或损坏 PDF 直接崩溃现象加载某些 PDF 时 CGPDFDocument 返回 nil后续强制解包崩溃。原因是没做空值判断加密文档需要先解锁。解决加载后先判空并给出明确错误提示加密文档走密码输入流程损坏文件直接拒绝并提示用户不要试图“修复”。5.5 签署后文件被二次编辑导致校验失败现象校验时发现签章位置的内容和记录不符。原因是签署后的文件又被其他工具改过。解决校验时同时比对页面尺寸、页数和签章区域像素差异任一不符即判定文件已变更交付时保留签署记录文件作为比对基准。6. 验收与答辩用一条可复现的检查链说话验收这套方案我习惯准备一条固定的检查链从文件到界面逐层过任何一层不过就不算完成。答辩时按这条链演示比讲架构图更有说服力因为每一步都有可见的产物。检查项操作通过标准文档加载打开普通、加密、损坏三类 PDF普通正常显示加密走密码流程损坏有明确提示不崩溃签名采集快速书写、慢速书写各一次笔迹平滑无明显折线抽稀后仍保留细节图元质量导出后放大查看边缘边缘抗锯齿、背景透明、无白底位置精度四个旋转角各盖一次签章落在点选位置无偏移无翻转结构完整用系统预览和第三方阅读器各打开一次页数、页面尺寸与原文档一致可正常打印校验闭环对签署后文件跑一次校验结构层与内容层均通过篡改后能报出差异演示顺序建议按数据主线走先展示一份原始 PDF现场签一次展示图元导出结果再展示合成后的文件在阅读器里的效果最后跑校验。中间故意制造一次失败——比如把签章拖到页面边缘——展示边界裁剪生效这比全程顺利更能说明方案考虑过异常。答辩提问高频集中在坐标映射和透明背景两处提前把映射前后的坐标打印出来备着被问到直接给数据。血泪经验是早期我总在最后一天才做整链验收结果发现加密 PDF 崩溃和旋转页偏移两个问题返工把合成模块重写了一半。从那以后我每次改完合成逻辑都强制走一遍上面这条检查链哪怕只改了一行坐标换算。希望这套结构和检查链能帮到你把签章这件事从“看起来像”做到“验得过”。本文还有配套的精品资源点击获取
