App Intents
AppShortcut 是你主动向系统提供的一种方式，用于展示和推广你的应用可以执行的特定操作（这些操作由 AppIntent 定义）。通过 AppShortcut，你的应用功能可以更容易地被用户通过 Siri、聚焦搜索 (Spotlight) 的建议以及快捷指令 App 发现和使用。
一、基本概念#是什么？ AppShortcut 是一个结构体，它代表了一个预先配置好的 AppIntent 实例，并附带了用户可见的元数据，如：调用短语 (Invocation Phrases)：用户可以说给 Siri 来触发这个快捷方式的自然语言短语。短标题 (Short Title)：在快捷指令 App 或建议中显示的简洁名称。系统图像 (System Image)：一个 SF Symbol 图标，用于视觉表示。目的与作用：提升可发现性 (Discoverability)：让用户更容易发现你的应用能做什么。系统可以将这些 AppShortcut 展示在聚焦搜索建议、Siri 建议（例如基于用户习惯在锁屏上推荐）或者快捷指令 App 中你应用的专属区域。简化用户操作：用户可以直接使用这些预定义的快捷方式，而无需自己从头开始在快捷指令 App 中构建。这降低了用户使用你应用自动化功能的门槛。增强 Siri 集成：通过提供明确的调用短语，Siri 可以更准确地理解用户意图并执行相应的 AppIntent。短语中还可以包含参数占位符，Siri 会在需要时询问用户。引导用户使用快捷指令：向用户展示你的应用支持哪些有用的自动化操作。上下文相关性：系统可以学习何时何地向用户建议这些 AppShortcut 最为合适。二、如何定义和提供 AppShortcut#你通过实现 AppShortcutsProvider 协议来向系统提供 AppShortcut。
创建 AppShortcutsProvider:
定义一个遵循 AppShortcutsProvider 协议的类型（通常是 struct 或 enum）。
实现 appShortcuts 静态计算属性:
在这个属性中，你返回一个 [AppShortcut] 数组，包含了你的应用希望提供的所有快捷方式。
从 iOS 16/17 开始，推荐使用 @AppShortcutsBuilder，它提供了一种更简洁、声明式的 DSL (Domain Specific Language) 风格来构建 AppShortcut 数组。定义单个 AppShortcut:
每个 AppShortcut 实例通常包含以下信息：
intent: YourAppIntent: 一个你已经定义好的 AppIntent 的实例。你可以在这里预设该意图的某些参数值。
// 假设你有一个 SendMessageIntent
let prefilledIntent = SendMessageIntent()
prefilledIntent.recipient = "[email protected]" // 预设参数
// ... intent: prefilledIntent ...phrases: [ Phrase
// 示例短语，假设 StartWorkoutIntent 有 workoutType 参数
// Phrase("Start a \(\.$workoutType) in \(.applicationName)")
// Phrase("Begin new workout in \(.applicationName)").applicationName 会被替换为你的应用名称。
shortTitle: LocalizedStringResource: 显示给用户的短标题。
systemImageName: String: SF Symbol 的名称，用作图标。
description: LocalizedStringResource (可选): 更详细的描述。
appShortcutTileColor: ShortcutTileColor (可选):
AppShortcutsProvider 还可以定义一个静态属性 appShortcutTileColor，用于自定义你的应用在快捷指令 App 中快捷方式磁贴的背景颜色。
示例代码：
假设我们有一个之前定义的 StartWorkoutIntent（它有一个 workoutType 参数，类型为 WorkoutTypeEntity，这是一个 AppEnum）。
import AppIntents
// 假设 StartWorkoutIntent 和 WorkoutTypeEntity 已定义
struct MyAppShortcuts: AppShortcutsProvider {
static var appShortcutTileColor: ShortcutTileColor = .green // 自定义磁贴颜色
// 使用 @AppShortcutsBuilder (iOS 16/17+)
@AppShortcutsBuilder
static var appShortcuts: [AppShortcut] {
// 快捷方式 1: 开始一个通用的锻炼，Siri 会询问类型
AppShortcut(
intent: StartWorkoutIntent(), // 没有预设 workoutType，Siri会询问
phrases: [
"Start a workout with \(.applicationName)",
"Begin exercise in \(.applicationName)",
"Log a new workout using \(.applicationName)"
],
shortTitle: "Start a New Workout",
systemImageName: "figure.walk"
)
// 快捷方式 2: 开始一个跑步锻炼 (预设参数)
AppShortcut(
intent: {
let intent = StartWorkoutIntent()
// 假设 WorkoutTypeEntity 可以通过 ID 初始化，或者你有预定义的实体实例
// 为了简单，这里假设可以直接构造或查找
// intent.workoutType = WorkoutTypeEntity(id: "running", name: "Running") // 预设为跑步
// intent.duration = 30 // 也可以预设其他参数
return intent
}(), // IIFE (Immediately Invoked Function Expression) 来创建和配置 intent
phrases: [
// Phrase("Start a \(\.$workoutType) run with \(.applicationName)"), // 如果 workoutType 仍可被Siri覆盖
"Start my run with \(.applicationName)", // 一个更具体的短语
"Begin running workout in \(.applicationName)"
],
shortTitle: "Start Running",
systemImageName: "figure.running"
// description: "Quickly starts a running session." // 可选描述
)
// 快捷方式 3: 使用参数占位符的短语 (Siri会询问workoutType)
AppShortcut(
intent: StartWorkoutIntent(),
phrases: [
// \(\.$workoutType) 告诉 Siri 这个部分对应 intent 中的 workoutType 参数
// Siri 会尝试从用户的语音中提取，或者直接询问 "What type of workout?"
"Start a \(\StartWorkoutIntent.$workoutType) workout in \(.applicationName)",
"Begin \(\StartWorkoutIntent.$workoutType) with \(.applicationName)"
],
shortTitle: "Start Specific Workout",
systemImageName: "flame.fill"
)
}
}三、AppShortcut 如何工作？#定义与提供: 你通过实现 AppShortcutsProvider 来定义和提供 AppShortcut。系统索引: 应用安装或更新后，系统会调用你的 AppShortcutsProvider 并索引这些快捷方式。发现与建议:聚焦搜索 (Spotlight): 当用户搜索时，如果搜索词与你的 shortTitle 或应用名相关，可能会显示你的 AppShortcut。Siri 建议: 系统可能会根据用户的使用习惯、时间、地点等上下文信息，在锁屏、Siri 建议小组件等地方主动推荐你的 AppShortcut。快捷指令 App: 用户可以在快捷指令 App 中找到你应用提供的所有 AppShortcut，并将它们添加到自己的自动化流程中，或直接运行。调用:用户点击一个建议的 AppShortcut。用户对 Siri 说出你定义的某个调用短语。用户在快捷指令 App 中运行包含此 AppShortcut 的流程。执行:系统会实例化 AppShortcut 中引用的那个 AppIntent。如果 AppShortcut 中预设了参数，这些参数会传递给 AppIntent 实例。如果调用短语中包含了参数占位符 (例如 \(\.$parameterName))，并且用户在语音中指定了该参数（或者 AppShortcut 中没有预设该参数），Siri 会尝试解析或询问用户以获取参数值。最终，AppIntent 的 perform() 方法被调用，执行实际的应用逻辑。四、AppShortcut 与 AppIntent 的关系#AppIntent 是动作的定义：它描述了你的应用能做什么，需要什么参数，以及如何执行。它是具体功能的蓝图和执行者。AppShortcut 是通往 AppIntent 的便捷入口：它为某个（可能已预设部分参数的）AppIntent 实例提供了一个用户友好的名称、调用短语和图标，使其更容易被发现和调用。你可以将 AppIntent 想象成一个函数定义，而 AppShortcut 则像是一个带有特定参数（可选）的函数调用快捷方式，并且这个快捷方式还有个好听的名字和易于记忆的语音命令。
五、使用场景#常用操作快捷化：为用户最常使用的应用功能提供 AppShortcut。音乐应用：“播放我的收藏夹”、“识别这首歌”。笔记应用：“创建新笔记”、“显示我最近的笔记”。咖啡店应用：“订一杯大杯拿铁”（参数预设或通过短语指定）。引导用户使用新功能：通过 AppShortcut 推广应用的新功能。简化复杂操作：如果某个 AppIntent 有多个参数，你可以提供一些预设了部分参数的 AppShortcut，简化用户的配置过程。六、最佳实践#有意义的快捷方式：只为用户真正觉得有价值、常用的操作提供快捷方式。不要滥用。清晰自然的短语：调用短语应该尽可能自然，符合用户的说话习惯。提供多种短语变体可以提高 Siri 的识别率。简洁的标题和图标：短标题要一目了然，图标要能清晰传达快捷方式的含义。测试：在真实设备上彻底测试所有 AppShortcut，包括通过 Siri 调用、在快捷指令 App 中使用以及查看它们在建议中如何显示。本地化：确保 shortTitle、description 以及短语中的文本都已正确本地化。通过精心设计 AppShortcut，你可以显著提升应用的用户体验，让你的应用功能更加深入地融入到用户的日常和系统的各个层面。