PaperKit 是随 iOS/iPadOS 26、macOS 26 和 visionOS 26 一同推出的统一标记框架,官方将其描述为 Notes、截图、QuickLook 和 Journal 中标记功能所使用的同一套框架。它把 PencilKit 的绘图能力与结构化标记元素(形状、文本框、图像、线条)结合到由 PaperMarkupViewController 管理的单一画布中。该框架被标注为 Beta 敏感:API 面可能发生变化,上线前应针对当前 Apple 文档核实细节。使用它需要 Swift 6.3 和 iOS 26+ SDK,且不需要任何 entitlement 或特殊的 Info.plist 条目。平台可用范围为 iOS 26.0+、iPadOS 26.0+、Mac Catalyst 26.0+、macOS 26.0+、visionOS 26.0+。
核心组件 PaperKit 包含三类核心组件:PaperMarkupViewController,作为创建与显示标记和绘图的交互式画布;PaperMarkup,作为序列化全部标记元素与 PencilKit 绘图的数据模型;以及 MarkupEditViewController 与 MarkupToolbarViewController,作为添加标记元素的插入界面。
PaperMarkupViewController 这是用于交互式标记的主视图控制器,提供可滚动的画布,同时支持自由的 PencilKit 绘图与结构化标记元素,遵循 Observable 和 PKToolPickerObserver。初始化时传入一个 PaperMarkup 和 supportedFeatureSet。主要属性包括:markup(当前数据模型)、selectedMarkup(当前选中的内容)、isEditable(画布是否接受输入)、isRulerActive(是否显示标尺覆盖层)、drawingTool(当前激活的 PencilKit 绘图工具)、contentView(渲染在标记下方的背景视图)、zoomRange(最小/最大缩放范围)以及 supportedFeatureSet(启用的 PaperKit 特性)。
触摸模式通过 PaperMarkupViewController.TouchMode 控制,有 .drawing 和 .selection 两个取值:设为 .drawing 时手指用于绘制,设为 .selection 时手指用于选择元素;directTouchAutomaticallyDraws 设为 true 时由系统根据 Pencil 状态决定。contentView 可用于在标记层下方放置模板、文档页面或被批注的图像。代理回调包括:paperMarkupViewControllerDidChangeMarkup(标记内容变化时)、paperMarkupViewControllerDidBeginDrawing(用户开始绘制时)、paperMarkupViewControllerDidChangeSelection(选中变化时)以及 paperMarkupViewControllerDidChangeContentVisibleFrame(可见帧变化时)。
PaperMarkup 数据模型 PaperMarkup 是一个 Sendable 结构体,存储所有标记元素与 PencilKit 绘图数据。创建方式包括:用 bounds 初始化新的空模型,或通过 dataRepresentation 从已保存的数据加载。保存通过 dataRepresentation() 完成,该方法是 async throws,需在异步上下文中调用。
可通过代码插入内容:insertNewTextbox 插入文本框、insertNewImage 插入图像、insertNewShape 配合 ShapeConfiguration 插入形状、insertNewLine 插入线条并指定起点终点与端点标记。形状类型包括 .rectangle、.roundedRectangle、.ellipse、.line、.arrowShape、.star、.chatBubble、.regularPolygon。其他操作包括:append(contentsOf:) 合并另一个 PaperMarkup 或 PKDrawing,transformContent 应用仿射变换,removeContentUnsupported(by:) 剥离特性集不支持的元素。数据模型属性包括 bounds(坐标空间)、contentsRenderFrame(所有内容的紧凑包围盒)、featureSet(该数据模型内容使用的特性)和 indexableContent(可提取用于搜索索引的文本)。视图控制器上的 suggestedFrameForInserting(contentInFrame:) 可获取避免与现有内容重叠的插入帧。
插入控制器 MarkupEditViewController 适用于 iOS、iPadOS、visionOS,会present一个弹出菜单用于插入形状、文本框、线条等元素,其 delegate 可设置为 PaperMarkupViewController(后者遵循该代理)。MarkupToolbarViewController 适用于 macOS 和 Mac Catalyst,提供带绘图工具与插入按钮的工具栏。两个控制器必须使用与 PaperMarkupViewController 相同的 FeatureSet。
FeatureSet 配置 FeatureSet 控制可用的标记能力。预设包括:.latest(全部当前特性,推荐的起点)、.version1(版本 1 的特性)、.empty(不启用任何特性)。可自定义:从 .latest 移除部分特性,或从 .empty 逐项 insert。可用特性包括 .drawing(自由 PencilKit 绘图)、.text(文本框插入)、.images(图像插入)、.stickers(贴纸插入)、.links(链接注释)、.loupes(放大镜元素)、.shapeStrokes(形状轮廓)、.shapeFills(形状填充)、.shapeOpacity(形状透明度控制)。
HDR 支持方面,需要在 FeatureSet 和 PKToolPicker 上同时将 colorMaximumLinearExposure 设置为大于 1.0 的值,可使用 view.window?.windowScene?.screen.potentialEDRHeadroom 匹配设备屏幕能力,纯 SDR 场景使用 1.0。形状、墨水与线条标记可通过 features.shapes、features.inks 和 features.lineMarkerPositions 配置,后者取值包括 .single、.double、.plain 或 .all。
与 PencilKit 集成 PaperKit 接受 PKTool 用于绘图,并可追加 PKDrawing 内容。可设置 drawingTool,例如 PKInkingTool(.pen, color: .black, width: 3),也可通过 append(contentsOf:) 将已有 PKDrawing 合并进标记。工具选择器(PKToolPicker)需创建、添加观察者并赋给 pencilKitResponderState.activeToolPicker,同时设置 toolPickerVisibility。将 toolPickerVisibility 设为 .hidden 时,选择器仍可用(响应 Pencil 手势)但不可见,从而实现迷你工具选择器体验。FeatureSet.ContentVersion 映射到 PKContentVersion。
SwiftUI 集成 可通过 UIViewControllerRepresentable 包装 PaperMarkupViewController:在 makeUIViewController 中创建视图控制器与工具选择器并设置代理,在 updateUIViewController 中同步 markup,并创建 Coordinator 遵循 PaperMarkupViewController.Delegate 以在标记变化时回写绑定值。
常见错误与审查清单 资料列出了若干常见错误:两个控制器使用了不匹配的 FeatureSet;加载时忽略内容版本(应先检查 markup.featureSet.isSubset(of:) 再赋值);用序列化阻塞主线程(dataRepresentation() 是异步的);忘记持有工具选择器(局部变量会被释放,应存为实例属性);为平台选择了错误的插入控制器(MarkupEditViewController 仅适用于 iOS/iPadOS/visionOS)。审查清单涵盖:导入 PaperKit、部署目标为 iOS 26+/macOS 26+/visionOS 26+、PaperMarkup 的 bounds 与内容尺寸匹配、两处使用相同的 FeatureSet、在异步上下文调用 dataRepresentation()、将 PKToolPicker 保留为存储属性、设置代理以接收变更回调、加载保存数据时检查内容版本、按平台选择正确的插入控制器、处理反序列化时的 MarkupError、以及 HDR 场景在两个对象上均设置 colorMaximumLinearExposure。
限制与说明 PaperKit 属于 Beta 敏感的新框架,API 面可能变化,上线前需对照 Apple 官方文档核实。资料未提供收费、价格、授权模式等信息。除上述内容外,其他细节暂未提供。