了解 PaperKit

了解如何将 PaperKit 引入你的 iOS、iPadOS、macOS 以及 visionOS App。我们将介绍如何将 PencilKit 绘画与标记功能 (如形状和图像) 无缝整合，以及如何自定用户界面。了解向前兼容性的最佳实践，并探索高级自定选项，以便为你的 App 打造真正与众不同的标记体验。

章节

0:00 - 简介
1:36 - 了解 PaperKit
3:35 - PaperKit 入门
8:37 - 自定功能集

资源

相关视频

WWDC24

充分利用 Apple Pencil 的强大功能

WWDC20

欢迎大家我叫 Andreea 是 Pencil & Paper 团队的工程师很高兴为大家介绍 PaperKit PaperKit 在全系统范围内支持 Apple 独特标记体验的框架它被应用于“备忘录”、“截屏”、 “快速查看”和“手记”等 App 中

它是在各款 App 中实现丰富标记的最简单方法 PaperKit 提供了一个画布供你在上面绘画并添加各种标记元素包括形状、图像、文本框等同时支持绘画和标记元素使得 PaperKit 成为各款 App 中提供全面标记体验的绝佳补充

作为 macOS Tahoe 的新增框架 PaperKit 提供了相同的丰富标记体验因此绘画和标记元素在任何 macOS App 上都可以出色地工作正如这里展示的全新“手记”App

首先我会详细介绍 PaperKit 的主要功能并解释它背后的核心组件

然后我将通过几个步骤展示如何将 PaperKit 标记集成到 App 中

最后我将说明如何根据你的 App 的实际需求定制 PaperKit 的标记体验

我会先通过一个演示来重点介绍可用的功能我创建了一个 App 来记录我的所有食谱并在进行修改时使用标记来更新它们我从七岁起就开始烘焙我最爱的传统罗马尼亚饼干现在我把配方整理成了食谱并用星形为它们评分为了完善这份食谱我将添加一张饼干的图片只需打开“文件”App

然后将图像拖到我的食谱中

我会调整一下位置让它看起来更美观！

我还要着重强调核桃粉因为它们是关键原料

介绍完 PaperKit 的功能我将进一步拆解它的三个主要组件首先是标记控制器名为 PaperMarkupViewController 它以交互方式创建和展示 PaperKit 标记和绘画

第二个是数据模型容器名为 PaperMarkup 它负责保存和载入 PaperKit 标记和 PencilKit 绘画数据并处理标记的呈现

第三个是新的插入菜单用于在画布中对标记元素进行注释在 iOS、iPadOS 和 visionOS 26 上这个组件名为 MarkupEditViewController

在 macOS 上另一个可选方案是新的工具栏称为 MarkupToolbarViewController 配有绘画工具和用于注释的按钮

在 App 中整合 PaperKit 非常简单首先我将介绍我如何在 iOS 上将它整合到我的食谱 App 中然后介绍适用于 macOS 的步骤

我先将 UIViewController 归入子类在 viewDidLoad 方法中我初始化了一个标记数据模型容器对它进行配置以匹配视图的边界从而确保正确的布局和渲染背景接下来我创建了一个标记控制器配置了 PaperKit 提供的全套最新功能

我使用标准视图控制器嵌入过程将它添加到视图层次结构中

要创建工具选择器我初始化了一个 PencilKit 工具选择器并将标记控制器注册为观察器允许它动态响应工具选择器状态的变化

为了在我的 App 中显示工具选择器我将它分配到 PencilKitResponderState 上的 activeToolPicker 属性这是 UIResponder 上可用的新 API 用于控制当前响应器的工具选择器可见性通过配置 toolPickerVisibility 属性我可以让工具选择器保持活跃状态同时显式管理它在屏幕上的可见性这样工具选择器就能保持隐藏状态同时又能正常运行仍然会响应轻点两下和轻捏手势等交互操作并允许任何 App 支持迷你工具选择器体验有关设置工具选择器的更多信息请观看 WWDC19 的 “PencilKit 简介”以及 WWDC24 的 “充分利用 Apple Pencil 的强大功能”讲座设置工具选择器后我将配件项配置为按钮轻点按钮时会触发显示插入菜单的功能

在这个方法中我使用与标记控制器相同的功能集初始化了插入控制器

然后我将控制器的委托设置为标记视图控制器将它配置为以弹出窗口形式显示并将弹出窗口锚定到我添加到工具选取器的条形按钮项以确保正确放置

最后我以模态方式呈现了插入菜单控制器

在 macOS 上让一切正常运行也同样简单

设置标记模型和标记控制器在本质上是一样的

macOS 上的唯一区别是可以创建工具栏来显示插入 UI 在此基础上将工具栏的委托设置为标记控制器并使用标准的 NSViewController 嵌入流程将它添加到视图层次结构中

完成基本设置后有必要停下来思考几个关键因素这些因素在优化 App 体验时至关重要

PaperKit 可以无缝集成到 SwiftUI 环境中这些组件封装在 UIViewControllerRepresentable 中然后直接合并到 SwiftUI 视图的主体中这样基于 UIKit 的组件就能在 SwiftUI 布局中使用从而保持两个框架之间的兼容性有关如何将视图控制器集成到 SwiftUI 环境的更多信息请观看 WWDC20 的 “SwiftUI 的新功能”讲座

标记控制器包括一个允许自定处理回调的委托例如我可以实现标记更改委托方法以自动保存对标记模型的任何修改此外标记控制器遵从 Observable 协议提供了一种使用委托来管理状态和更新的替代方法

从磁盘载入数据时务必始终验证内容版本以实现向前兼容性处理版本不匹配有两种常用方法显示警报以通知需要升级或显示标记的预先渲染缩略图

PaperKit 提供了一系列工具使得实现向前兼容性变得轻而易举首先创建一个 CGContext 将缩略图呈现到其中

然后使用标记模型的绘制函数生成模型的缩略图

最后将它与标记一起保存

在版本不匹配的情况下显示这个缩略图被认为是最佳实践 “备忘录”等 App 正是使用这种方法

介绍完如何在 iOS 和 macOS 上开始使用 PaperKit 我将深入探讨如何自定 App 来打造你所设想的标记体验 PaperKit 中提供的全套标记功能称为 FeatureSet 它定义了向标记和插入控制器公开的功能和工具

FeatureSet.latest 为你提供了 PaperKit 支持的全套标记功能这是一个很好的起点因为它可以确保你及时了解框架中新增的功能

要自定你的标记体验你可以使用删除和插入功能这样你就可以完全控制你的 App 中可用的工具和交互

可以在标记中启用 HDR 支持方式是将功能集上的 colorMaximumLinearExposure 属性设置为大于 1 的数字对于 SDR 标记请设为 1 在工具选择器上也为 HDR 油墨设置这个属性对于我的 App 设为 4 能提供我想要的 HDR 效果

你为 colorMaximumLinearExposure 设置的值将会进行色调映射以降低到你的设备屏幕所支持的 HDR 亮度范围或者直接使用屏幕支持的值你可以从 UIScreen 或 NSScreen 中获取相应的值

通过使用最新的功能集并在 App 中启用 HDR 你将获得所有新功能和体验例如 PencilKit 中引入了一种名为“Reed Tool”的

全新书法工具在 HDR 模式下效果非常出色

根据你的要求配置功能集后将自定义功能集同时分配给标记控制器和插入控制器以确保 App 的标记和插入功能之间的一致性

另一个可自定的属性是标记控制器的 contentView 它可以设置为任何 UIView 例如我可以将模板用作 App 中的固定样式所有标记和绘画都将在它上面呈现通过自定 FeatureSet 配置背景视图并实施前面列出的优化步骤你的 App 可以提供同样强大的且覆盖整个系统的标记体验并支持稳健且富有创意的个性化定制

接下来该怎么做？采用 Apple 强大的标记体验使用你自己选择的工具和墨水来自定 FeatureSet 设置你自己的内容背景并为标记添加 HDR 支持

无论你是在开发轻量级的笔记工具还是打造一个丰富的创意画布 PaperKit 都能为你提供创造完美体验所需的元素我迫不及待想看到大家利用 PaperKit 创造的种种精彩

谢谢观看！

3:47 - Adopt PaperKit in iOS

// Adopt PaperKit in iOS

override func viewDidLoad() {
    super.viewDidLoad()
    
    let markupModel = PaperMarkup(bounds: view.bounds)
    let paperViewController = PaperMarkupViewController(markup: markupModel, supportedFeatureSet: .latest)
    view.addSubview(paperViewController.view)
    addChild(paperViewController)
    paperViewController.didMove(toParent: self)
    becomeFirstResponder()    

    let toolPicker = PKToolPicker()
    toolPicker.addObserver(paperViewController)
    
    pencilKitResponderState.activeToolPicker = toolPicker
    pencilKitResponderState.toolPickerVisibility = .visible
    
    toolPicker.accessoryItem = UIBarButtonItem(barButtonSystemItem: .add, target: self, action: #selector(plusButtonPressed(_:)))
}

@objc func plusButtonPressed(_ button: UIBarButtonItem) {
    let markupEditViewController = MarkupEditViewController(supportedFeatureSet: .latest)    
    markupEditViewController.delegate = paperViewController
    markupEditViewController.modalPresentationStyle = .popover
    markupEditViewController.popoverPresentationController?.barButtonItem = button
    present(markupEditViewController, animated: true)
}

6:11 - Adopt PaperKit in macOS

// Adopt PaperKit in macOS

override func viewDidLoad() {
    super.viewDidLoad()
    
    let markupModel = PaperMarkup(bounds: view.bounds)
    let paperViewController = PaperMarkupViewController(markup: markupModel, supportedFeatureSet: .latest)
    view.addSubview(paperViewController.view)
    addChild(paperViewController)

    // Create toolbar for macOS
    let toolbarViewController = MarkupToolbarViewController(supportedFeatureSet: .latest)
    toolbarViewController.delegate = paperViewController
    view.addSubview(toolbarViewController.view)
    
    // Set layout
    setupLayoutConstraints()
}

7:18 - Auto-save markup changes

// Auto-save markup changes
    
func paperMarkupViewControllerDidChangeMarkup(_ paperMarkupViewController: PaperMarkupViewController) {
    let markupModel = paperMarkupViewController.markup
    Task {
        // Create a data blob and save it
        let data = try await markupModel.dataRepresentation()
        try data.write(toFile: paperKitDataURL)
    }
}

8:02 - Thumbnail for forward compatibility

// Thumbnail for forward compatibility

func updateThumbnail(_ markupModel: PaperMarkup) async throws {
    // Set up CGContext to render thumbnail in
    let thumbnailSize = CGSize(width: 200, height: 200)
    let context = makeCGContext(size: thumbnailSize)
    context.setFillColor(gray: 1, alpha: 1)
    context.fill(renderer.format.bounds)            

    // Render the PaperKit markup
    await markupModel.draw(in: context, frame: CGRect(origin: .zero, size: thumbnailSize))
    
    thumbnail = context.makeImage()
}

9:02 - Customized markup FeatureSet

// Customized markup FeatureSet
    
var featureSet: FeatureSet = .latest

featureSet.remove(.text)
featureSet.insert(.stickers)

// HDR support
featureSet.colorMaximumLinearExposure = 4
toolPicker.colorMaximumLinearExposure = 4

let paperViewController = PaperMarkupViewController(supportedFeatureSet: featureSet)
let markupEditViewController = MarkupEditViewController(supportedFeatureSet: featureSet)

10:50 - Custom background on markup controller

// Custom background on markup controller

let template = UIImage(named: "MyTemplate.jpg")
let templateView = UIImageView(image: template)
paperViewController.contentView = templateView

0:00 - 简介
借助 PaperKit，你可以在各个 iOS 和 macOS App (包括“备忘录”、“截屏”、QuickLook 和“手记”App) 中打造丰富的标记体验。这个框架提供了画布，支持绘制和添加形状、图像、文本输入栏等。PaperKit 简化了将标记功能集成到任何 App 的流程，能够为用户带来顺畅的使用体验。
1:36 - 了解 PaperKit
这个示例 App 是一款食谱管理工具，支持用户通过标记功能来创建、更新和注释食谱。这个 App 包含标记控制器、数据模型容器，以及用于便捷注释的插入菜单或工具栏 (具体取决于操作系统)。这个演示中通过添加图像、高亮显示食材以及为传统罗马尼亚饼干食谱评分，展示了这些功能特性。
3:35 - PaperKit 入门
要将 PaperKit 集成到 iOS App 中，需继承 UIViewController 并初始化标记数据模型容器和控制器。随后设置 PencilKit 工具选择器，并配置插入菜单控制器，使它在按钮配件项触发时以弹出框形式显示。你还可以将 PaperKit 无缝集成到 SwiftUI 环境中。标记控制器包含用于自定处理回调的委托，并遵循 Observable 协议进行状态管理。从磁盘加载数据时，验证内容版本以确保向前兼容性至关重要。PaperKit 提供了用于生成预渲染缩略图的工具，以防出现版本不匹配的情况。
8:37 - 自定功能集
PaperKit 的 FeatureSet 定义了 App 中可用的标记功能。你可以从 FeatureSet.latest 开始，以包含所有最新功能。要自定 App，你可以使用提供的函数移除或插入工具和交互。要启用 HDR 支持，请将 colorMaximumLinearExposure 属性设置为大于 1 的值，这个值会色调映射到设备支持的 HDR 余量。这样做可以提升标记的视觉质量，尤其是在使用 PencilKit 中推出的书法芦苇笔等新工具时。你还可以自定标记控制器的 contentView 以显示任何 UIView (例如模板)，从而为标记和绘图提供一致的背景。