Adopt Quick Note
System & Services 进阶 12m

接入快速备忘录

Adopt Quick Note

2021年6月8日

在 Apple 官方观看视频

一句话判断

如果你的 App 有任何用户可能想记下来的内容，不接 Quick Note 就是浪费了一个零成本的留存入口。

这场 Session 讲了什么

iPadOS 15 引入了 Quick Note（快速备忘录）功能——用户从屏幕右下角轻扫就能呼出一个浮动笔记窗口，随时记录想法。这个 Session 展示了开发者如何让自己的 App 与 Quick Note 联动：当用户在某个 App 内创建 Quick Note 时，系统可以自动将当前上下文（比如正在浏览的网页、查看的文档位置）关联到这条备忘录中，之后用户再次打开同一条备忘录时，系统会提示回到对应的 App 位置。

Quick Note 的底层其实是一个 NSTextView，但它多了「关联」（WindowScene 上的 userActivity）这一层。苹果没有发明什么新 API，而是复用了 NSUserActivity 和 WebKit 里已有的机制。对大多数 App 来说，接入工作量很小——如果你已经支持了 Handoff 或 Spotlight 索引，基本上只需几行代码就能让 Quick Note 自动捕获你的内容上下文。

值得深挖的点

NSUserActivity 的 targetContentIdentifier 才是关键。 Quick Note 关联的核心逻辑依赖于 NSUserActivity 的 targetContentIdentifier 属性。你需要在用户的当前 Activity 上设置一个稳定的、可唯一标识内容的字符串，系统会在用户创建 Quick Note 时自动抓取这个 Activity。这个 identifier 必须持久且可逆推——用户点击备忘录中的链接时，App 需要能通过这个 identifier 恢复到对应的页面状态。很多开发者已经为 Spotlight 搜索做了这件事，Quick Note 可以直接复用。

WebKit 的自动关联不需要额外代码。 对于基于 WKWebView 的内容，系统会自动处理 Quick Note 关联——URL 就是天然的 identifier。但如果你是自定义渲染的内容（比如电子书阅读器、PDF 查看器），就需要手动管理 userActivity 的生命周期，确保它在页面切换时及时更新。

代码片段

// 在 viewDidLoad 或视图出现时设置 userActivity
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)

    // 创建一个 userActivity 来标识当前内容
    let activity = NSUserActivity(activityType: "com.example.app.viewArticle")
    activity.title = article.title
    activity.targetContentIdentifier = "article/\(article.id)"

    // 设置为当前 Activity，Quick Note 会自动关联
    userActivity = activity
}
// 在 SwiftUI 中使用 onContinueUserActivity 处理从 Quick Note 跳回
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onContinueUserActivity("com.example.app.viewArticle") { activity in
                    // 从 targetContentIdentifier 恢复页面
                    if let articleId = activity.targetContentIdentifier {
                        navigateToArticle(id: articleId)
                    }
                }
        }
    }
}
// 更新 userActivity 的网页关联信息
func updateActivityForCurrentPage() {
    view.userActivity?.targetContentIdentifier = "page-\(currentPageIndex)"
    view.userActivity?.title = "第 \(currentPageIndex) 页"
    view.userActivity?.needsSave = true
}

最佳实践

  • 如果你已经实现了 Spotlight 索引（CSSearchableItem），targetContentIdentifier 应该和索引用的 identifier 保持一致，这样 Spotlight 搜索和 Quick Note 共用一套路由逻辑
  • userActivity 的生命周期要跟内容绑定而不是跟视图绑定——用户在同一页面滚动时不应该创建新的 Activity
  • 对于多窗口场景（iPad），确保每个窗口有独立的 userActivity，否则 Quick Note 可能关联到错误的窗口内容

还有什么值得关注

  • macOS Monterey 上也可以通过 Hot Corner 或快捷键触发 Quick Note，同一套 API 在 Mac 上同样适用
  • Notes app 新增了 Quick Note 智能文件夹，自动聚合所有快速备忘录
  • activity.eligibleForSearch 设为 true 可以让 Quick Note 中的链接同时出现在 Spotlight 搜索结果中
WWDC 2021