# 应用程序意图专家技能 iOS 26+ 上的 App Intents 框架的专家指南。该技能涵盖构建意图、实体、查询、应用程序快捷方式、交互式片段以及与 Siri、Spotlight、Apple Intelligence 和 Visual Intelligence 的集成。 ## 什么时候使用这个技能当开发人员处于以下情况时使用此技能： * 创建或修改任何“AppIntent”、“AppEntity”、“AppEnum”或“EntityQuery” * 向应用程序添加 Siri、快捷方式、Spotlight 或 Apple Intelligence 支持 * 构建 `AppShortcutsProvider` 或应用程序快捷方式 * 使用 `SnippetIntent` 实现交互式片段 * 使用“IndexedEntity”为 Spotlight 建立索引实体 * 与视觉智能或图像搜索集成 * 使用“TargetContentProvidingIntent”和“onAppIntentExecution”进行导航 * 从 SiriKit (`INIntent`) 迁移到 App Intents * 调试应用程序意图构建错误或运行时问题 ## 基于任务的路由根据开发者的需要，阅读相关的参考文件。 ###“我想创建我的第一个应用程序意图” 1. 阅读 [references/intent-fundamentals.md]() 2. 然后 [references/shortcuts-provider.md]() 以实现可发现性 ### “我希望我的应用程序内容可以在 Siri 和 Spotlight 中搜索” 1. 阅读 [references/entities-and-queries.md]() 2. 然后 [references/spotlight-indexing.md]() 3. 然后 [references/siri-integration.md]() ### “我想与 Apple Intelligence 和新 Siri 集成” 1. 阅读 [references/apple-intelligence.md]() 2. 然后 [references/siri-integration.md]() 3. 如果是框架新手，则 [references/intent-fundamentals.md]() ### “我想构建交互式片段” 1. 阅读 [references/interactive-snippets.md]() 2. 如果不熟悉意图，则 [references/intent-fundamentals.md]() ### “我想将快捷方式和 Siri 短语添加到我的应用程序中” 1. 阅读 [references/shortcuts-provider.md]() 2. 然后 [references/siri-integration.md]() ### “我想围绕应用程序意图构建我的应用程序” 1. 阅读 [references/intent-driven-architecture.md]() 2.然后[references/entities-and-queries.md]() 3. 然后 [references/intent-fundamentals.md]() ###“我想支持视觉智能/图像搜索” 1. 阅读 [references/apple-intelligence.md]() — 图像搜索部分 2.然后[references/entities-and-queries.md]() ### “我正在从 SiriKit 迁移” 1. 阅读 [references/migration-from-sirikit.md]() 2. 然后 [references/intent-fundamentals.md]() ###“我需要测试我的应用程序意图” 1. 阅读 [references/testing-intents.md]() ### “我遇到构建错误或运行时问题” 1. 阅读 [references/common-pitfalls.md]() ## 快速参考清单 ### 最低可行的应用意图 * 创建一个符合`AppIntent`的结构体 * 添加一个 `static let title: LocalizedStringResource` * 实现 `func Perform() 异步抛出 -> 一些 IntentResult` * 为任何输入添加“@Parameter” * 为所有必需参数添加“ParameterSummary” * 如果意图应使应用程序前台化，则设置“supportedModes” ### 最小可行的应用程序实体 * 创建一个符合`AppEntity`的结构体 * 添加持久的、唯一的“id”属性 * 为每个公开的属性添加`@Property`或`@CompulatedProperty` * 提供`typeDisplayRepresentation`和`displayRepresentation` * 使用“entities(for:)”方法创建一个“EntityQuery” * 在实体上设置 `static let defaultQuery` * 使用`AppDependencyManager`注册数据依赖 ### 最小可行的应用程序快捷方式 * 使用“static var appShortcuts”创建一个“AppShortcutsProvider” * 使用意图、短语、shortTitle、systemImageName 创建 `AppShortcut` 实例 * 每个短语必须包含 `\(.applicationName)` * 每个短语最多一个`@Parameter` * 当建议的实体更改时调用 `updateAppShortcutParameters()` ### 使实体可被 Spotlight 搜索 * 使实体符合“IndexedEntity” * 将“indexingKey”参数添加到“@Property”属性中 * 使用框架的索引 API 捐赠实体 * 实现“OpenIntent”，以便点击结果导航到实体 ### 添加交互式片段（iOS 26+） * 创建一个符合 `SnippetIntent` 的结构体 * 将所有视图驱动变量标记为“@Parameter” * 从“perform()”返回“.result(view:)” * 在代码片段视图中使用 `Button(intent:)` 或 `Toggle(intent:)` * 从父意图返回“ShowsSnippetIntent” * 不要在代码片段意图的执行方法中改变应用程序状态 ## 关键决策树 ### 我的意图应该遵循哪个协议？这是一个基本动作吗？ → 应用意图它会打开您的应用程序来显示内容吗？ → OpenIntent + TargetContentProvidingIntent 它会呈现交互式视图吗？ → 片段意图它应该支持撤消吗？ → 可撤销意图它与 Apple Intelligence 域匹配吗？ → 使用 @AppIntent 宏和适当的模式 ### 我应该使用哪种实体类型？这组值在编译时是固定且已知的吗？ → 应用枚举这组值是动态的吗？ → 应用程序实体我需要 Spotlight 索引吗？ → 应用实体 + 索引实体我需要图像搜索/视觉智能吗？ → AppEntity + Transferable + OpenIntent ### 我应该使用哪种查询类型？所有实体都能放入内存吗？ → 可枚举实体查询我需要基于文本的搜索吗？ → 实体字符串查询我需要按属性过滤吗？ → 实体属性查询我只需要通过ID查找吗？ → EntityQuery（基础协议） ### 属性应该是@Property、@CompulatedProperty 还是@DeferredProperty？值存储在实体结构中吗？ → @属性该值可以从其他来源（UserDefaults、模型）派生吗？ → @ComputedProperty（首选 - 较低的开销）该值的计算成本是否昂贵（网络调用、大量 I/O）？ → @DeferredProperty（异步 getter，仅在系统请求时调用） ## 框架架构笔记 * 应用程序意图使用**构建时元数据提取**。您的 Swift 源代码在编译时被读取，以生成存储在应用程序包内的应用程序意图表示。这就是为什么某些值（标题、显示表示）必须是编译时常量的原因。 * 系统读取此元数据**无需运行您的应用程序**。安装后，意图、实体和快捷方式立即可用。 * 应用程序中的每个目标都是独立处理的。跨目标共享 App Intent 类型时，请使用 AppIntentsPackage 注册每个目标。 * App Intents 现在可以存在于**Swift Packages 和静态库**中（iOS 26 中的新增功能）。 * 在应用程序的生命周期中尽早使用“AppDependencyManager.shared.add { }”注册依赖项（通常在“App.init()”中）。

应用程序意图专家技能

包含技能