-
探索 App Intents 框架的新功能
利用高级功能提升 App Intents 的应用效果，从而打造更快速、更灵活、更相关的使用体验。了解如何使用 ValueRepresentation 和 RelevantEntities 让你的内容更易于发现并呈现在不同的 App 中，如何利用 EntityCollection 提升性能，以及如何借助 SyncableEntity 实现跨设备扩展。探索更丰富的参数类型，包括联合值以及能够顺畅处理取消事件的长时间运行意图。
章节
- 0:00 - Introduction
- 2:40 - Share entities across apps with ValueRepresentation
- 3:45 - Register relevant entities with RelevantEntities
- 7:05 - Handle entities efficiently with EntityCollection
- 8:55 - Use entities across devices with SyncableEntity
- 11:01 - Richer parameter types
- 12:38 - Union value parameters
- 13:26 - Extend execution with LongRunningIntent
- 15:27 - Target the right process with ExecutionTargets
- 17:14 - Next steps
资源
-
搜索此视频…
大家好 我叫Moe 是App Intents团队的工程师 很高兴与大家分享 App Intents的新功能 这些功能将随2027年 的新版本一同推出 App Intents是让你向系统其他部分 表达App操作和内容的框架 向系统的其他部分开放 以自然且深度集成的方式 从Siri和Shortcuts 到Spotlight和Widgets App Intents一直是 Apple平台上最出色体验 背后的引擎 如今也是 Apple 智能的核心支柱 在2027年的新版本中 基于大家的功能需求 我们带来了更多控制力 和更强的灵活性 以及更流畅的 开发者体验 今天我们将探讨三个领域 首先从实体开始 我将展示在App间 共享实体的新方式 告知系统实体的相关时机 并批量处理它们 接下来我将介绍 对原生类型的新支持 以及联合值 与Shortcuts的完整集成 最后我将展示 如何让Intent运行更长时间 优雅地处理取消 并指定正确的进程执行 今天我将专注于新功能 如果你刚接触App Intents 或需要复习基础知识 建议查看WWDC25的 "Get to know App Intents" 该视频介绍了 地标旅行追踪App 我将基于它 使用今天介绍的API继续构建 你可以下载示例代码 跟着一起操作 让我们深入了解新内容 实体是你App的内容 例如地标或播放列表 它们存在于你的App内 但用户并非如此 他们随时在不同App间切换 让我用旅行追踪App 结合Mail和Maps举几个例子 我创建了一个快捷指令 用于与朋友分享旅行创意 它会找到附近的地标 并连同信息一起发送 我的实体遵循 CoreTransferable框架中的Transferable协议 快捷指令可以将其 以Mail可用的格式共享 效果非常好 但如果不是 将其发送给朋友 而是想获取 前往该地标的路线呢 那就行不通了 Maps需要一些结构化信息 如坐标或地址 或者可以导航的内容 但这类数据 没有关联的数据格式 可以放入文件或数据中 现有的文件和数据表示形式 适用于已知格式 例如PDF或图像 但不适合 没有格式的结构化类型 这就是 ValueRepresentation的用武之地 这是一种新的表示类型 让你可以共享结构化类型 而系统已能理解这些类型 这是我的LandmarkEntity 代表旅行追踪App中的地点 它已遵循Transferable协议 我只需添加ValueRepresentation 与现有表示形式并列即可 在ValueRepresentation内部 我导出地标的 坐标和名称 作为GeoToolbox框架中的 PlaceDescriptor PlaceDescriptor包含 坐标和其他元数据 供Maps导航使用 如果我的实体已有 PlaceDescriptor @Property 我可以完全跳过闭包 直接使用键路径 结果相同 代码更少
回到我的快捷指令 点击运行 地标以PlaceDescriptor的形式 传递给Maps Maps随即打开 并显示前往地标的路线
你的实体现在有更多方式 在App间传递 现在来聊 如何帮助系统在合适时机推荐它们 假设你正在开发 类似CosmoTunes的音乐App 即该视频中的示例App "Explore advanced App Intents features for Siri and Apple Intelligence" 你的App有一个全新的 高节奏播放列表 非常适合跑步时使用 当有人在健身App中 设置跑步锻炼时 他们会看到 推荐的播放列表 如何让你的播放列表 出现在这些推荐中呢
目前有两种方式 让系统获取你的内容 第一种是通过Spotlight 为内容建立索引 这让用户能够 搜索到你的内容 在Spotlight界面中 包括语义搜索 这也是Siri 检索你内容的主要方式 第二种方式 是交互捐献 当用户在App中执行操作时 你将这些交互捐献给系统 通过IntentDonationManager API 随着时间推移 系统会学习这些规律 并在将来推荐类似操作 Siri也会利用这些交互 提供更个性化的体验 但新的播放列表呢 没人在Spotlight中搜索它 因为他们不知道它的存在 也没人播放过它 所以没有可捐献的交互 你需要一种方式 告知系统这个播放列表很相关 以便在合适的时机 将其呈现出来 介绍RelevantEntities 通过RelevantEntities 你可以向系统推荐实体 并提供其相关时机 和原因的上下文 工作原理如下 首先确定 相关实体 本例中为你的跑步播放列表 接下来创建一个上下文 告知系统 当有人开始跑步时 这些播放列表是相关的 然后调用updateEntities 将其注册 系统会在合适的上下文中 将这些播放列表作为建议呈现 即使它们从未被播放过 实体会保持注册状态 直到你将其移除 你可以对特定上下文 调用removeAllEntities 从上下文中移除特定实体 或清除所有上下文中 的全部实体
现在你有更多选项 帮助用户发现你的内容 如何在它们之间选择呢 当你希望内容可被搜索 且能被Siri检索时 使用Spotlight 使用交互捐献 来帮助Siri和系统学习 用户如何使用你的App 从而识别规律 并推荐用户可能 想要重复的操作 使用RelevantEntities 向系统提示 哪些内容在特定情境中相关 以便系统在合适时机推荐 如需深入了解这些主题 请查阅Spotlight新文档 以及交互捐献相关文档 你的实体已可共享 系统也知道它们的相关时机 现在让我们提升它们的效率
回到旅行追踪App 该App有地标照片 我还希望让用户 保存自己的旅行照片 于是我添加了相册视图 为了让系统能够 访问这些照片 我定义了一个PhotoEntity 并为照片设置了App Schema 这让系统获得所需上下文 以便跨Siri使用我的照片 Shortcuts和Spotlight
我还创建了一个Intent 用于为照片添加关键词标签 以便用户轻松整理和查找 随着照片库增大 我注意到了一个问题 一次性标记大量照片 比预期慢很多 让我们通过代码 来了解原因
这个Intent很简单 只是为照片添加关键词 它接受照片实体列表 和一个标签作为@Parameter perform方法只是 将标签应用到每张照片 那么问题究竟在哪里
这与App Intents 解析参数的方式有关 在Intent运行之前 系统会解析每个实体 这意味着调用实体查询 填充所有属性 以便Intent获取所需的一切 对大多数Intent来说 这正是你想要的 但在我的情况下 这意味着解析数百乃至数千个照片实体 即使代码只需要 实体ID来更新数据模型 那么如何解决这个问题 EntityCollection解决了这个问题 这是一种新类型 存储实体标识符数组 而不是完整解析的实体 当你使用EntityCollection 作为参数类型时 系统只将标识符 传递给Intent的perform方法 而不解析完整实体 以下是更新后的代码 我将@Parameter类型 改为EntityCollection 并将标识符直接 传递给我的标记方法 就是这样
为了验证修复有效 我创建了一个快捷指令 查找并标记1000张照片 首先使用照片实体的 常规数组
然后使用EntityCollection 几乎是即时完成的 代码改动很小 但性能差异 非常显著
那么当同一实体需要 在多台设备上工作时会发生什么
在2027年的新版本中 Siri可以跨设备继续对话 你的实体 也可以参与这些对话
如果你的App在多台设备上运行 用户可能在一台设备上 开始与Siri的对话 然后在另一台设备上继续 但这存在一个挑战 如果我在iPhone上让Siri 将照片添加到相册 然后切换到另一台设备 让Siri为该照片添加标签 Siri可能找不到那张照片 为了理解原因 让我们思考实体的识别方式 每个实体都需要一个ID 这是系统查找它的方式 你的实体ID可能 在每台设备上本地生成 本地ID在创建它的设备上 运行良好 但每台设备 都会生成自己的本地ID 因此同一实体在不同设备上 可能有不同的ID 为了让Siri 跨设备引用你的实体 需要一个在所有设备上 都相同的稳定ID 可以来自你的服务器 或CloudKit记录ID 然后你需要一种方式 告知系统你的实体ID是稳定的 这就是SyncableEntity的作用 它向系统声明 你的实体ID是稳定的 并且可以跨设备使用 以下是使用方法 首先将SyncableEntity协议 添加到我的实体 然后需要提供稳定ID 如果你的实体已经使用 在所有设备上相同的ID 例如服务器分配的UUID 或CloudKit记录ID 则无需进行更多更改 但如果使用本地标识符 如CoreData行ID 则需要两者 一个本地ID和一个稳定ID SyncableEntityIdentifier 将它们配对为单个ID 在设备上 代码使用本地ID 跨设备时 系统使用稳定ID
到目前为止 我们专注于实体 现在来谈谈 使用这些实体的Intent Intent接受参数 即用户提供的输入 如日期、姓名或地址 声明@Parameter时 系统会提供原生选择器 Siri理解能力 以及免费的本地化支持 我们正在将相同的支持 扩展到更多原生类型 我们增加了对Duration的原生支持 不再需要构建自定义时间选择器 以及PersonNameComponents 用于结构化姓名输入 而不是普通字符串 以及更多
每种类型都有原生选择器 并在Intent支持的所有地方使用 Siri、Shortcuts和Widgets 这些都是单独的类型 每个@Parameter对应一种类型 但有时一个参数 需要接受多种类型 联合值是一个Swift枚举 每个case包装不同的类型 让单个参数 代表多个选项之一 现在App中同时有地标 和旅行照片 我想要一个Widget 显示来自相册的照片 或地标合集 通过@UnionValue 支持输入参数 我可以用一个Widget满足两种需求 以下是代码 我将联合值定义为枚举 使用@UnionValue宏 每个case 包装不同的实体类型 一个用于地标合集 一个用于相册 该宏生成 系统所需的一切 类型信息、case元数据 以及选择器支持
我还配置了 每个选项在选择器中的显示方式 typeDisplayRepresentation 是整体类型的标签 caseDisplayRepresentations将每个case 映射到选择器中显示的名称 这不仅限于Widgets @UnionValue参数 在Intent支持的所有地方均有效 包括Shortcuts
如需了解更多 请查阅旅行追踪示例代码项目 及其对应的文章 到目前为止介绍的内容 让你的实体和参数 更具表现力和效率 现在来谈谈执行 当你的Intent运行时 无论来自Siri、Shortcuts或任何系统界面 它只有30秒来完成 这对大多数日常操作有效 但并非每个Intent都那么快 现在我的App支持 标记和整理照片 我希望让用户 分享他们的旅行照片 上传到共享相册 无需打开App 于是我创建了一个上传Intent 并在Widget中 添加了一个触发按钮 但对于大尺寸照片 上传需要时间 Intent不断失败 因为无法完成 在30秒限制内 LongRunningIntent解决了这个问题 它让Intent运行 超过30秒限制 并管理App的 后台任务生命周期 Intent运行期间 进度更新会自动以实时活动呈现 现在来看代码
这是我写的 用于上传照片的Intent 我遵循LongRunningIntent协议 接受照片文件作为输入 然后将工作包装在 performBackgroundTask中 以实现延长执行
LongRunningIntent要求 Intent上报进度 以便系统知道 它仍在运行而非卡住 由于它基于 ProgressReportingIntent 我获得了内置的进度对象 来追踪工作 我计算文件的分块数量 并设置总数 然后上传每个分块 并随时更新进度
以下是Intent运行时的情况 它可以运行更长时间 实时活动上有一个停止按钮 用户可以随时取消 不过如果Intent能在 停止前收到通知就更好了
CancellableIntent让Intent 在取消时优雅清理 无论用户点击了取消 还是系统超时 或需要回收资源 以下是添加取消支持的方法
我添加CancellableIntent 并实现onCancel处理程序 当取消原因发生时 处理程序会给出原因 我可以用它 来清理部分上传 或取消进行中的请求 LongRunningIntent还支持 在支持的设备上后台访问GPU 用于照片处理 或设备端推理等任务 只需确保在App的授权中 添加GPU访问权限 如需了解 后台运行任务的机制 请查阅WWDC25的该视频 到目前为止 我们介绍了Intent的运行时长 以及停止时发生的情况 来谈谈哪个进程运行它 随着App增长 你可能将 部分Intent移入Widget扩展 或App Intents扩展 这些轻量级独立进程 无需启动App即可处理请求
你还可以创建共享Swift包 或框架 用于存放Intent和实体 并将其导入 App和扩展 事实上 这正是我在 旅行追踪App中所做的 我所有的Intent都存放在共享包中 由主App和Widget扩展 共同导入 当Intent、实体和查询 都存放在这样的共享包中时 由App和扩展链接 系统需要决定 当请求到来时 哪个进程运行每个Intent 它根据启发式规则选择目标 如果App已在运行 则优先使用App 否则启动扩展 但有时这并非正确的选择 例如 我想在Widget中 添加一个收藏按钮 让用户直接从主屏幕 将照片标记为收藏 我的Widget与App 共享数据模型 但两个进程 写入同一数据存储 可能导致冲突 于是我给Widget只读访问权限 由主App处理所有写入 当用户点击该按钮时 Intent需要在主App中运行 ExecutionTargets让你告知系统 具体哪个进程 应该运行你的Intent 方法如下
你可以指定主App
appIntentsExtension widgetKitExtension 或任意组合 通过ExecutionTargets 你可以覆盖系统的启发式规则 精确控制 哪个进程处理你的Intent 以上就是我想分享的新功能 接下来的行动: 为实体添加ValueRepresentation 以便在App间 传递结构化数据 向系统注册相关内容 以便在合适时机呈现 采用EntityCollection 提升Intent速度 在处理大量实体时 为任何需要超过30秒才能完成的 Intent添加LongRunningIntent 逐步构建App的Siri体验 请查阅"Code-along: Make your app available to Siri" 如需使用新的AppIntentsTesting框架 测试Intent 请查阅"Validate your App Intents adoption with AppIntentsTesting" 期待看到你的作品 感谢观看！
-
-
0:01 - Share structured entities with ValueRepresentation
struct LandmarkEntity: AppEntity, Transferable { var id: Int var landmark: Landmark // contains CLLocationCoordinate2D static var transferRepresentation: some TransferRepresentation { ValueRepresentation( exporting: { entity in PlaceDescriptor( representations: [.coordinate(entity.landmark.locationCoordinate)], commonName: entity.landmark.name ) } ) } } // If the entity already has a PlaceDescriptor property, use a key-path — much less code: struct LandmarkEntity: AppEntity, Transferable { var id: Int @Property var placeDescriptor: PlaceDescriptor static var transferRepresentation: some TransferRepresentation { ValueRepresentation(exporting: \.placeDescriptor) } } -
5:18 - Register relevant entities with RelevantEntities
// Suggest playlists for the workout session let playlistEntities = [dailyRun, runningMix] let workoutContext = AppEntityContext.audio(.workout(activityType: .running)) try await RelevantEntities.shared.updateEntities( playlistEntities, for: workoutContext ) // Clear all entities for a context try await RelevantEntities.shared.removeAllEntities(for: workoutContext) // Remove specific entities from a context try await RelevantEntities.shared.removeEntities(playlistEntities, from: workoutContext) // Or remove all entities across all contexts try await RelevantEntities.shared.removeAllEntities() -
7:15 - Handle large entity sets with EntityCollection
struct TagPhotosIntent: AppIntent { static let title: LocalizedStringResource = "Tag Travel Photos" @Parameter var photos: EntityCollection<PhotoEntity> // was: [PhotoEntity] @Parameter var tag: String func perform() async throws -> some IntentResult { modelData.tagPhotos(ids: photos.identifiers, tag: tag) // was: tagPhotos(photos, tag: tag) return .result() } } -
10:14 - Make entity IDs stable with SyncableEntity
// If your ID is already stable across devices (server UUID, CloudKit record ID): struct PhotoEntity: AppEntity, SyncableEntity { var id: Int // Already stable across devices — that's it } // If you use local IDs, pair a local and a stable ID: struct PhotoEntity: AppEntity, SyncableEntity { var id: SyncableEntityIdentifier<String, String> init(localID: String, stableID: String) { self.id = SyncableEntityIdentifier(local: localID, stable: stableID) } } -
11:58 - Accept multiple types with @UnionValue
@UnionValue enum TravelGalleryContent { case landmarkCollection(LandmarkCollectionEntity) case photoAlbum(PhotoAlbumEntity) static let typeDisplayRepresentation: TypeDisplayRepresentation = "Travel Gallery" static let caseDisplayRepresentations: [Cases: DisplayRepresentation] = [ .landmarkCollection: "Landmark Collection", .photoAlbum: "Photo Album" ] } -
13:41 - Run beyond 30 s with LongRunningIntent + CancellableIntent
struct UploadPhotoIntent: LongRunningIntent, CancellableIntent { static let title: LocalizedStringResource = "Upload Photo" @Parameter var photo: IntentFile func perform() async throws -> some IntentResult & ProvidesDialog { let result = try await performBackgroundTask { let chunks = calculateChunks(for: photo) progress.totalUnitCount = Int64(chunks) for chunk in 1...chunks { try Task.checkCancellation() try await uploadChunk(chunk) progress.completedUnitCount = Int64(chunk) } return "Upload complete!" } onCancel: { reason in cleanup(for: reason) } return .result(dialog: "\(result)") } } -
16:54 - Control which process runs your intent with ExecutionTargets
// Write operation — needs the main app struct UpdateFavoriteIntent: AppIntent { static var allowedExecutionTargets: ExecutionTargets { .main } } // Standalone download — runs in the extension struct DownloadPhotoIntent: AppIntent { static var allowedExecutionTargets: ExecutionTargets { .appIntentsExtension } } // Display-only — runs in the widget extension struct GetLandmarkStatusIntent: AppIntent { static var allowedExecutionTargets: ExecutionTargets { .widgetKitExtension } } // Works in either — lets the system choose struct TagPhotosIntent: AppIntent { static var allowedExecutionTargets: ExecutionTargets { [.main, .appIntentsExtension] } }
-
-
- 0:00 - Introduction
The 2027 App Intents updates — more control, flexibility, and a smoother developer experience across Siri, Shortcuts, Spotlight, Widgets, and Apple Intelligence. Three areas: entity enhancements, richer parameters, and intent execution, built on the Landmarks Travel Tracking sample.
- 2:40 - Share entities across apps with ValueRepresentation
Beyond Transferable's File and Data representations, the new ValueRepresentation shares structured types the system understands, for example exporting a landmark as a PlaceDescriptor (GeoToolbox) so it flows to Maps for directions. Use a key-path if the entity already has the property.
- 3:45 - Register relevant entities with RelevantEntities
Spotlight indexing and interaction donation can't surface never-seen, never-used content. RelevantEntities lets you suggest entities with a context (such as running playlists when a workout starts) via updateEntities, and remove them by context, by entity, or entirely.
- 7:05 - Handle entities efficiently with EntityCollection
Resolving every entity before an intent runs is costly at scale (tagging thousands of photos). EntityCollection passes just identifiers to perform() without full resolution, a one-line parameter-type change that made tagging 1000 photos nearly instant.
- 8:55 - Use entities across devices with SyncableEntity
Siri conversations now continue across devices, but local IDs differ per device. SyncableEntity declares a stable ID (server UUID or CloudKit record ID); when you only have local IDs, SyncableEntityIdentifier pairs a local and a stable ID so on-device code uses local and the system uses stable.
- 11:01 - Richer parameter types
Declaring a @Parameter gives a native picker, Siri understanding, and localization for free, now extended to more native types like Duration (no custom time pickers) and PersonNameComponents, working across Siri, Shortcuts, and Widgets.
- 12:38 - Union value parameters
A @UnionValue enum lets one parameter accept multiple types, for example a single widget showing photos from either a landmark collection or a photo album. The macro generates type info, case metadata, and picker support (typeDisplayRepresentation, caseDisplayRepresentations), and works everywhere including Shortcuts.
- 13:26 - Extend execution with LongRunningIntent
Intents normally have 30 seconds; LongRunningIntent runs beyond it, manages the background task lifecycle, and shows progress as a Live Activity. Wrap work in performBackgroundTask and report progress (it builds on ProgressReportingIntent). Add CancellableIntent's onCancel to clean up gracefully; it also supports background GPU access.
- 15:27 - Target the right process with ExecutionTargets
When intents live in a shared package linked by the app and extensions, the system picks a process by heuristics, not always right (for example a widget favorite button needs the writing main app). ExecutionTargets overrides this to target the main app, an App Intents extension, a WidgetKit extension, or any combination.
- 17:14 - Next steps
Add ValueRepresentation to carry structured data, register relevant content, adopt EntityCollection for large entity sets, and add LongRunningIntent for work over 30 seconds. See "Code-along: Make your app available to Siri" and "Validate your App Intents adoption with AppIntentsTesting."