使用Swift PDFKit开发时如何在PDF页面内调整、移动PDFAnnotation?
Swift 基于 PDFKit 实现 Ink 类型 PDFAnnotation 的移动与尺寸调整交互
坐标体系适配基础
这部分是开发中最容易踩的坑,多数交互异常都和坐标系映射错误有关:
- PDF 原生坐标系原点在页面左下角,UIKit 坐标系原点在视图左上角,所有手势计算的位移、点位都必须通过
PDFView提供的坐标转换方法做双向映射 - 核心转换方法:
convert(_:to:)可以在 PDFView 视图坐标、指定 PDFPage 的坐标之间做双向转换;通过page(for: nearest:)可以判断手势触点当前所属的 PDF 页面,避免跨页场景下的位置计算错误
注释移动交互实现
所有手势都直接绑定在承载所有 PDF 内容的 PDFView 上,因为 PDFAnnotation 是纯模型对象,没有独立的视图层级可以直接绑定手势:
- 给
PDFView添加用于移动的UIPanGestureRecognizer,在手势代理中加判断:当触点落在目标注释的 bounds 范围内时,才触发移动逻辑 - 分阶段处理手势状态:
.began阶段:通过PDFView的annotationHitTest(_:)方法校验触点命中的注释,将其标记为当前选中的操作对象,记录该注释初始的bounds值作为计算基准.changed阶段:将手势产生的平移量转换为对应 PDF 页面的坐标偏移,直接在初始 bounds 的基础上叠加偏移值,修改注释bounds的 origin 位置.ended/.cancelled阶段:清除选中标记,调用注释的needsDisplay属性通知 PDFView 重绘界面
- 注意:Ink 类型的手写注释的笔迹路径会自动跟随自身 bounds 做位置对齐,不需要手动重新计算笔迹路径的坐标。
尺寸调整交互实现
对应常见的带调整手柄的缩放交互,实现逻辑如下:
- 当注释被选中时,在 PDFView 的自定义绘制流程中,于当前注释 bounds 的 4 个角、4 条边中点位置绘制共 8 个小型调整手柄,不需要添加独立的 UIView,性能开销更低
- 新增一个专门处理尺寸调整的
UIPanGestureRecognizer,通过手势代理做冲突区分:如果触点落在调整手柄的识别范围内,就触发尺寸调整逻辑,屏蔽移动手势的响应 - 分阶段处理手势状态:
.began阶段:判断用户拖动的是哪个位置的手柄(比如右下角、左侧中点),记录当前注释的初始 bounds 作为计算基准.changed阶段:根据手柄的拖动方向,对应修改注释 bounds 的尺寸值:比如拖动右下角手柄时,直接根据触点的位移调整 bounds 的 width 和 height;拖动左侧中点手柄时,同步调整 bounds 的 origin.x 和 width,保证注释右侧的位置保持固定.ended/.cancelled阶段:触发注释重绘,清除选中状态和调整手柄的绘制
- 注意:调整 Ink 注释尺寸时不要对笔迹路径做拉伸形变,只调整 bounds 的显示范围即可,避免笔迹模糊变形,符合 PDF 注释的通用规范。
交互优化细节
- 做好手势优先级与冲突处理:通过
UIGestureRecognizerDelegate的协议方法区分移动、尺寸调整、捏合缩放三类手势的响应逻辑,避免交互卡顿、跟手性差的问题 - 加边界校验:无论移动还是调整尺寸,都要实时判断注释的 bounds 不能超出当前 PDF 页面的范围,避免注释移动到页面外导致后续加载无法识别
- 处理缩放因子适配:当 PDFView 处于非 100% 缩放状态时,手势的位移计算要除以当前 PDFView 的
scaleFactor,解决高缩放比下手势跟手偏移的问题 - 加选中态视觉反馈:选中注释时绘制半透明的边框层,配合调整手柄的显示,让用户明确当前的操作对象
内容的提问来源于stack exchange,提问作者Sac Allen
相关产品推荐
相关产品推荐

