将自定意图迁移到 App Intents

大家好 我是 Ari 很高兴能和大家谈谈 如何将自定意图迁移 到 App Intents 在这个视频中 我将介绍 为什么要采用新的 App Intents 框架 迁移是如何工作的 包括向后兼容 以及如何实际 转换为 App Intents 首先我们来介绍为什么 要采用 App Intents 它与之前的框架 有什么不同 2016 年 我们推出了 SiriKit Intents 框架 它附带有一组 由目的驱动的系统意图 可为常见用例提供 完整的用户体验 例如收发信息 体能训练 接打电话等 接着 我们推出了自定意图 它允许你针对任何用例 定义自己的意图 从而将 App 的功能 提供给 Siri 快捷指令和建议 我们添加了 WidgetKit 它可以使用自定意图 进行小组件的配置 和预测 在 WWDC22 上 我们推出了 App Intents 这是一种新的 Swift 原生框架 它可以从 App 向系统提供意图 App Intents 是 一个值得采用的出色框架 因为它不仅与时俱进 功能强大 而且便于用户使用 它的与时俱进在于 它是为 Swift 原生设计的 得益于最新的语言功能 为支持同一功能 而要编写的代码量 大幅减少 并且不需要维护 意图定义文件 和进行代码生成 现在 你能够以轻量型 SwiftUI 视图 的形式提供代码段 它的功能强大在于 实体和查询 都支持深度用例 你可以直接在 App 进程中 运行 App Intents 无需提供扩展 而在设置和运行你的意图时 人们也有新的机会 打造个性化用户体验 同时 它还 十分便于用户使用 意图可以方便地 作为 App 快捷指令进行公开 无需任何设置 即可立即投入使用 此外 人们还可以通过新的途径 发现你的快捷指令 因为它们会显示在 聚焦的顶端 以及 Siri 提示中 而二者都可以包含在你的 App 中 为了充分发挥 新框架的所有优势 只要是为 Siri 和 快捷指令构建的自定意图 都需要升级为 App Intents SiriKit 意图 仍然得到全面支持 因此 如果你是为 Siri 域构建意图 比如收发信息或媒体 或者 如果你是将意图 与 WidgetKit 搭配使用 则应让它们保持原样 要想进一步了解 App Intents 框架 请查看我们在 WWDC22 上的讲座 “深入探索 App Intents” App 快捷指令 让人们能够非常方便地 通过 Siri 和聚焦 使用你 App 的功能 要想进一步了解 App 快捷指令 请查看“利用 App Intents 实现 App 快捷指令” 接下来 我们介绍一下迁移 借助迁移 你只需 在 Xcode 中点按一下 即可将现有的意图定义转换为 App Intents 利用同一个 App 二进制文件 可以同时支持 iOS 15 和 iOS 16 你可以让人们 现有的快捷指令 继续用于新的 App Intents 要想将你的意图定义 转换为 App Intents 你所要做的就是导航到 意图定义文件 并按下 “Convert to App Intent”按钮 Xcode 会生成 与旧意图定义 对等的 App Intents 然后 你可以通过重构 旧内容处理程序代码 来填充代码 我们将在下一节中 对这一点进行深入讨论 在 App 升级为 App Intents 时 为了让人们 获得无缝体验 系统会自动接管 从旧意图到新意图的 映射工作 让我们来谈谈具体过程 只需采用 CustomIntentMigratedAppIntent 协议 系统就会掌握足够的信息 从而知晓 如何在新旧意图之间 进行转换 在采用这一协议时 你要提供意图类 名称属性 这是用于旧自定意图 的类名称 大多数情况下 并不是 必须要你自己提供这一项 在你使用 “Convert to App Intent”按钮时 所生成的代码中 已经采用了这一协议 得益于 App Intent 的 迁移功能 你并不需要等待 App 针对 iOS 16 升级为 App Intents 事实上 利用同一个 App 二进制文件 可以轻松支持新旧 两种操作系统 为此 请在你的 App 中 同时包含旧版意图处理程序 和 App Intents 为了最大程度实现代码共享 请在一套通用的业务逻辑上 充分考量这两组意图处理程序 假设你采用迁移后的 App Intent 协议 当 App 中同时包含 这两组意图处理程序时 快捷指令就会自动 对你的意图去重 因此 在 iOS 15 或更早版本中 快捷指令 App 将仅显示 旧版意图的实现 而在 iOS 16 或更高版本中 它将仅显示 App Intent 的实现 一旦将最低部署目标 切换为 iOS 16 或更高版本 你就可以针对所迁移的意图 安全地删除 旧版意图处理程序 和意图定义 这些将不再有用 迁移时 需要考虑一件事 有些人的现有快捷指令 会依赖于你的旧意图 这些意图可能是在 快捷指令 App 中生成的 或是在 App 中 用“添加到 Siri”按钮添加的 好消息是 只要这些快捷指令 采用迁移后的 App Intent 协议 那么它们仍适用于 新的 App Intent 人们的快捷指令不会为了 使用新的 App Intents 而被覆盖 它们会自动使用 一种对新旧意图 都有效的常用格式 为了实现这一点 旧版意图 和 App Intents 的方案 必须兼容 而为了实现兼容 自定意图 和 App Intent 的参数 必须具有相同的名称 和对等的类型 你可以在不破坏 方案兼容性的前提下 做出一些更改 具体来说 你可以添加或移除参数 或使现有参数 变为非可选项 要想在 Xcode 中 检查方案的兼容性 请查看旧意图定义文件 里面有相关参数的列表 每个参数都有 各自的名称和类型 在检查器面板中 也有一个针对 意图类名称的栏位 在处理 App Intents 代码时 请确保意图类名称 与意图定义文件中的 类名称保持一致 以便系统 能将新意图和 旧意图对等起来 同时确保 App Intents 代码中的 参数名称和类型 保持兼容 同样地 Xcode 中的 “Convert to App Intents”按钮 会自动确保 方案的兼容性 也就是说 如果你使用工具 且没有做出任何更改 那么一切都会保持良好状况 接下来 我们谈谈 如何将现有的意图 实际转换为 App Intents 迁移意图要分两步进行 第一步是 迁移意图定义文件 第二步是 迁移代码 我们先从 意图定义开始 我本人钟爱汤品 不妨假设有一个 名为 Soup Chef 的 App 通过它可以下单购买汤品 它上面有一个意图 即在下单时通过参数来选择 要订购的汤品种类和数量 以及要添加的佐料 并可指定自取 或配送地点 现在 我准备将它 转换为 App Intents 为此 我要导航到 Xcode 中的意图定义文件 然后按下转换按钮 接着 我会选择 要转换的意图 -- 这里只有一个意图 然后 我会选择 新意图代码的存储位置 以及包含该意图的目标 这可以是我的 App 目标 也可以是 App Intents 扩展目标 如果我前面添加过的话 在这里 我将选中 App 目标 和 watch 目标 App Intents 无法 添加到框架目标中 接下来 我会查看 Xcode 生成的 App Intents 代码 它被分成了几个文件 分别代表 意图定义文件中所含的 所有意图 枚举和自定类型 要提请你注意 已迁移的旧意图定义 的几个特定方面 在新代码中 有一个 orderSoup 结构 它遵从 App Intent 协议 请注意 该结构 在 iOS 16 或更高版本中 被标记为可用 如果你是在 早于 iOS 16 的操作系统上 部署你的 App 则需要将该注解应用于 使用 App Intents 框架的 所有代码 意图定义文件 中的每个参数 及其元数据 都已经迁移到 App Intent 结构的 @Parameter 声明中 所有快捷指令 App 参数摘要 都已经迁移到这个 parameterSummary 声明中 以前表示为参数关系的内容 现在可以用 ParameterSummary 中的 Switch、Case 或 When 语句来表示 Soup 和 Toppings 自定类型现在是 App 实体 其中包含一些待办事项 我需要在稍后进行填写 OrderDetails 现在是 一个瞬态 App 实体 之所以称为瞬态 是因为它没有 可用于以后进行查询的 唯一标识符 OrderType 自定枚举 现在是一个 App 枚举 可直接识别的名称 被迁移为 本例的显示表示 最后 意图响应中的 所有对话框 已迁移到 IntentDialog 上的扩展中 这些对话框可用于 perform 方法 迁移器可能会生成 超出需要的字符串 因此 如果你看到 在旧意图处理程序中 有实际未使用的字符串 例如 “确认一下 你想要的是 \ (soup)？” 可随时将它们移除 在迁移完意图定义之后 现在让我们来继续迁移 意图处理代码 请注意 自动生成的 App Intent 上有一个 perform() 方法的占位符 以及一个待办事项 用于提醒需要 进行填写 我们来看看具体如何操作 在旧框架中 你要提供 意图定义文件和 一组意图处理代码 而在新框架中 所有内容 都是用代码来表示的 旧意图定义中的参数 已迁移到新的代码中 旧代码中的 resolve confirm 和 handle 方法 需要合并成 单一的 perform 方法 并在意图运行时进行调用 自定类型和动态选项 需要重构为 实体和查询 我们来看看 具体如何迁移 意图处理的每个阶段 就从 resolve 开始吧 在 resolve 阶段中 意图处理程序会验证 意图的每个参数 并提示用户 根据需要输入相应值 当迁移 resolve 方法时 应在可能的情况下 充分利用 App Intents 的 新自动解析操作 否则应将解析逻辑重构为 perform 方法 我们来看几个示例 这是我们针对 汤品参数的旧解析方法 在旧意图框架中 它后面跟着一个通用模式 试着展开汤品参数 如果为 nil 则返回解析结果 让用户通过消歧来 选择汤品 如果为 set 则返回解析结果及成功信息 并且传回已指定的 同一汤品 对于 App Intents 来说 得益于自动解析功能 这类样板代码 已不再需要 如果你有的参数 之前是用这种方式进行解析的 那么以下是如何利用 新功能的具体操作 默认情况下 迁移后的参数 将为可选项 但你可以通过将类型 更改为非可选项 来获取自动解析操作 当你将某个参数 变为非可选项时 如果它的值为空 App Intents 就会 自动要求用户通过 SoupAppEntity 查询 使用建议的实体来输入值 然后 在参数声明中 添加一个对话框 这样用户就可以 在解析系统 提示输入值时 被询问具体问题 例如 “你想要什么汤？” 完成这一操作后 以后将不再需要 该参数的任何解析代码 对于所有其他的 解析类型 应将 resolve 实现 移动到 perform() 方法的顶端 并更改 API 用法 以使用相应的 新 API 来让用户 加以说明 例如 不妨假设你的 旧 resolve 方法 用于展开数量 并抛出缺失的 needsValue 然后查看 该数量是否大于 实际可供应的汤品数 如果是 则返回错误 当将该代码 移动到 App Intents 时 我们完全不再 需要第一部分 因为我们可以独立地 将数量参数变为 非可选项 对于第二部分 有代码导致 完成处理程序 出现不受支持的解析结果 我们想将此代码摘出 并将它替换为 抛出错误的代码 以指示汤品库存不足 我们需要将 错误定义为枚举 以遵从错误和 自定本地化字符串资源 可转换协议 这样 我们就可以提供 相应的对话框 以便在遇到这种情况时 向用户进行播报或显示 如果你曾经有类似 本示例中那样动态 返回 needsValue 结果 的代码 可以将它替换为抛出 needsValueError 的代码 当抛出 needsValueError 时 系统会提示用户 通过所提供的对话框输入值 然后再次从头开始 运行 perform 方法 另一个方案是使用 requestValue 方法 当使用 requestValue 时 你可以提示用户 输入值并继续 运行 perform 方法 而无需从头开始 除了 requestValue 方法外 还有 requestDisambiguation 和 requestConfirmation 方法 可用于 替换之前的 API 用法 接下来 我们谈谈 confirm confirm 为我们提供了 一个进行额外验证 提供信息的机会 让系统询问用户 是否确认自己想继续处理 对于验证 应将 confirm 方法中的 所有验证逻辑 移动到 perform 方法中 如果需要让用户 进行确认 我们有一个比较简单的 requestConfirmation() API 这个新的 API 只执行 一次方法调用 借助 async/await 该方法将等待 用户做出确认 然后才继续 处理 perform 方法 如果用户取消确认 就会抛出错误 并停止执行 perform 方法 requestConfirmation 方法中 包含几个参数 它们会影响到确认提示 这其中包括 由 Siri 播报或显示的对话框 以代码段显示的 SwiftUI 视图 用于确认按钮的标签 -- 这里指的是顺序 -- 还有就是 showPrompt 参数 该参数用于控制是否 以提示的形式 在屏幕上显示对话框 当对话框和视图中 包含相同的信息时 这一项应设为 false 因此对于让 Siri 播报 对话框而不显示对话框 这是有意义的 接下来 我们看看 handle 对于重构 handle 你只需将代码 从 handle 方法 移动到 perform 方法 你应该能从旧 handle 方法中 移除一些验证代码 因为 resolve、confirm 和 handle 现在 都集中于一个方法中 例如 如果是从 handle 中 拷贝旧代码 你可能最终得到这样的代码 它会展开不再是可选项的参数 而这些参数现在是可以删除的 在 perform 方法的末尾 你应该返回意图结果 结果中可以包含各种栏位 例如 Siri 要播报的对话框 或者要显示的代码段视图 每一项都要求你 使用相应的协议 标注 perform 方法的 返回类型 比如 ProvidesDialog 对应于对话框 而 ShowSnippetView 对应于 SwiftUI 代码段视图 最后 我们来看看迁移 动态选项 根据参数类型 你需要填写 Query 或 DynamicOptionsProvider 在这些需要填写的地方 Xcode 会提供待办事项 对于查询 如果它是可搜索的 你需要实现相应的方法 以便按标识符 按字符串返回实体 否则将只返回当用户轻点 快捷指令中的参数时所显示的 那组建议实体 对于动态选项 你可以只返回结果方法中的 所有选项 这样就可以了！ 你即将完成 迁移到 App Intents 的工作 在真正完成之前 还有几件事 建议你了解一下 第一件事是采用 App 快捷指令 它会让你的意图 更容易被用户发现 而且人们只需要对着 Siri 说几句话 就可以使用这些意图 请将 Siri 提示添加到你的 UI 中 这样人们就能学会 如何与 Siri 进行对话 以便使用 App 的功能 快捷指令应取代之前的 “添加到 Siri”按钮 测试自定升级路径时 务必用先前版本的 App 创建快捷指令 并用新版本的 App 测试它们能否正常工作 如果你的 App 要在多个语言区中使用 应考虑进行本地化 为了将 App Intents 本地化 App Intent 中 所含的所有字符串 都应以本地化后的 字符串资源形式提供 而对于这些字符串 你可以通过提供相应 可本地化的 .strings 文件式 进行本地化处理 如果是使用复数形式的字符串 也可以使用 .strings dict 文件 在本地化 App 快捷指令时 请将字符串添加到名为 AppShortcuts.strings 的文件中 并用 ${ } 表示法 替换这些字符串中的 任何变量 总之 我们建议你 将自定意图升级为 App Intents 以便享受 iOS 16 新功能所带来的全部优势 以及更简单的 新 App Intents 开发模式 务必添加 App 快捷指令 这样人们就可以轻松地发现 并使用你 App 的功能 要想进一步了解 如何打造 出色的用户体验 请查看 WWDC22 上的讲座 “设计 App 快捷指令” 感谢观看