App Intents — AppShortcut
This article is extracted from the chat log with AI. Please identify it with caution.

AppShortcut 是你主动向系统提供的一种方式，用于展示和推广你的应用可以执行的特定操作（这些操作由 AppIntent 定义）。通过 AppShortcut，你的应用功能可以更容易地被用户通过 Siri、聚焦搜索 (Spotlight) 的建议以及快捷指令 App 发现和使用。

一、基本概念 #

  • 是什么？ AppShortcut 是一个结构体，它代表了一个预先配置好的 AppIntent 实例，并附带了用户可见的元数据，如：
    • 调用短语 (Invocation Phrases)：用户可以说给 Siri 来触发这个快捷方式的自然语言短语。
    • 短标题 (Short Title)：在快捷指令 App 或建议中显示的简洁名称。
    • 系统图像 (System Image)：一个 SF Symbol 图标，用于视觉表示。
  • 目的与作用：
    1. 提升可发现性 (Discoverability)：让用户更容易发现你的应用能做什么。系统可以将这些 AppShortcut 展示在聚焦搜索建议、Siri 建议（例如基于用户习惯在锁屏上推荐）或者快捷指令 App 中你应用的专属区域。
    2. 简化用户操作：用户可以直接使用这些预定义的快捷方式，而无需自己从头开始在快捷指令 App 中构建。这降低了用户使用你应用自动化功能的门槛。
    3. 增强 Siri 集成：通过提供明确的调用短语，Siri 可以更准确地理解用户意图并执行相应的 AppIntent。短语中还可以包含参数占位符，Siri 会在需要时询问用户。
    4. 引导用户使用快捷指令：向用户展示你的应用支持哪些有用的自动化操作。
    5. 上下文相关性：系统可以学习何时何地向用户建议这些 AppShortcut 最为合适。

二、如何定义和提供 AppShortcut #

你通过实现 AppShortcutsProvider 协议来向系统提供 AppShortcut。

  1. 创建 AppShortcutsProvider:

    定义一个遵循 AppShortcutsProvider 协议的类型（通常是 struct 或 enum）。

  2. 实现 appShortcuts 静态计算属性:

    在这个属性中，你返回一个 [AppShortcut] 数组，包含了你的应用希望提供的所有快捷方式。

    • 从 iOS 16/17 开始，推荐使用 @AppShortcutsBuilder，它提供了一种更简洁、声明式的 DSL (Domain Specific Language) 风格来构建 AppShortcut 数组。

  3. 定义单个 AppShortcut:

    每个 AppShortcut 实例通常包含以下信息：

    • intent: YourAppIntent: 一个你已经定义好的 AppIntent 的实例。你可以在这里预设该意图的某些参数值。

      // 假设你有一个 SendMessageIntent
let prefilledIntent = SendMessageIntent()
prefilledIntent.recipient = "support@example.com" // 预设参数
// ... intent: prefilledIntent ...

    • phrases: [ Phrase<YourAppIntent.IntentParameterProvider> ]: (使用 @AppShortcutsBuilder 时的现代语法) 或者 phrases: [String] (旧式或简单字符串，但推荐使用强类型的短语构建)。 这些是用户可以对 Siri 说的短语。你可以使用 \(\.$parameterName) 来引用 AppIntent 中的参数，Siri 会在需要时提示用户输入该参数的值。

      // 示例短语，假设 StartWorkoutIntent 有 workoutType 参数
// Phrase("Start a \(\.$workoutType) in \(.applicationName)")
// Phrase("Begin new workout in \(.applicationName)")

      .applicationName 会被替换为你的应用名称。

    • shortTitle: LocalizedStringResource: 显示给用户的短标题。

    • systemImageName: String: SF Symbol 的名称，用作图标。

    • description: LocalizedStringResource (可选): 更详细的描述。

  4. 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 如何工作？ #

  1. 定义与提供: 你通过实现 AppShortcutsProvider 来定义和提供 AppShortcut。
  2. 系统索引: 应用安装或更新后，系统会调用你的 AppShortcutsProvider 并索引这些快捷方式。
  3. 发现与建议:
    • 聚焦搜索 (Spotlight): 当用户搜索时，如果搜索词与你的 shortTitle 或应用名相关，可能会显示你的 AppShortcut。
    • Siri 建议: 系统可能会根据用户的使用习惯、时间、地点等上下文信息，在锁屏、Siri 建议小组件等地方主动推荐你的 AppShortcut。
    • 快捷指令 App: 用户可以在快捷指令 App 中找到你应用提供的所有 AppShortcut，并将它们添加到自己的自动化流程中，或直接运行。
  4. 调用:
    • 用户点击一个建议的 AppShortcut。
    • 用户对 Siri 说出你定义的某个调用短语。
    • 用户在快捷指令 App 中运行包含此 AppShortcut 的流程。
  5. 执行:
    • 系统会实例化 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，你可以显著提升应用的用户体验，让你的应用功能更加深入地融入到用户的日常和系统的各个层面。

本文共 2695 字，创建于 May 22, 2025
相关标签： Xcode, SwiftUI, ByAI, DeepSeek