Swift Academy · 课时

应用意图与快捷指令

Q: 「应用意图与快捷指令」这节课中我会学到什么？

将操作提供给 Siri 和快捷指令。 你通过在浏览器中直接运行的动手代码来练习 Swift Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

将操作提供给 Siri 和快捷指令。

应用意图与快捷指令 是 CoddyKit 上的免费 Swift Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Swift Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Swift Academy 课程共包含 4 节课。

什么是 App Intents

App Intents框架会将您应用的操作公开给系统，包括 Siri、Shortcuts、Spotlight、小组件和操作按钮。您只需将一个操作描述为 Swift 类型一次，它就能在各处使用，并支持语音控制和自动化。

import AppIntents
// Define an action as a type; the system can run it
// from Siri, Shortcuts, Spotlight, widgets, etc.

定义 AppIntent

意图遵循 AppIntent，声明面向用户的 title，并实现执行实际工作的 perform()，然后返回结果。框架会自动发现它，无需注册。

import AppIntents
struct AddTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Add Task"
    func perform() async throws -> some IntentResult {
        // create the task here
        return .result()
    }
}

参数

使用 @Parameter属性包装器向用户（或 Siri）请求输入。系统会提示用户补充缺失的值，并对这些值进行验证。每个参数都有一个显示在 Shortcuts 编辑器中的标题。

import AppIntents
struct AddTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Add Task"
    @Parameter(title: "Title")
    var taskTitle: String
    func perform() async throws -> some IntentResult {
        return .result()
    }
}

返回值与对话

意图可以返回数据并播报确认信息。IntentResult 的变体（如 .result(value:dialog:)）可以让您返回一个带类型的值，以及一段由 Siri 读给用户听的语音或可见对话。

import AppIntents
struct CountTasksIntent: AppIntent {
    static var title: LocalizedStringResource = "Count Tasks"
    func perform() async throws
        -> some IntentResult & ProvidesDialog {
        let count = 5
        return .result(
            dialog: "You have \(count) tasks")
    }
}

参数摘要

parameterSummary 描述快捷指令编辑器中显示的句子，将参数自然地融入语言中，例如将 \(taskTitle) 添加到我的列表。这样一来，您的操作组合到快捷指令中时读起来会更加清晰。

import AppIntents
struct AddTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Add Task"
    @Parameter(title: "Title") var taskTitle: String
    static var parameterSummary: some ParameterSummary {
        Summary("Add \(\.$taskTitle) to my list")
    }
    func perform() async throws -> some IntentResult {
        .result()
    }
}

实体

AppEntity 表示一个系统可以理解的模型对象，例如任务、备忘录或播放列表。借助实体和查询，Siri 与快捷指令可以让用户从您的数据中选择一个值作为参数。

import AppIntents
struct TaskEntity: AppEntity {
    static var typeDisplayRepresentation:
        TypeDisplayRepresentation = "Task"
    var id: String
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(id)")
    }
    static var defaultQuery = TaskQuery()
}

实体查询

EntityQuery 告诉系统如何根据标识符查找您的实体，以及如何列出建议。这为用户在快捷指令中选择值或回答 Siri 时看到的选择器提供支持。

import AppIntents
struct TaskQuery: EntityQuery {
    func entities(for ids: [String]) async throws
        -> [TaskEntity] {
        ids.map { TaskEntity(id: $0) }
    }
    func suggestedEntities() async throws -> [TaskEntity] {
        [TaskEntity(id: "Groceries")]
    }
}

应用快捷指令

AppShortcut 可以让意图通过语音直接运行，无需任何设置——用户不必先创建快捷指令。您需要提供触发短语，其中必须包含应用名称标记，这样 Siri 才能识别上下文。

import AppIntents
struct AddTaskShortcut: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: AddTaskIntent(),
            phrases: ["Add a task in \(.applicationName)"],
            shortTitle: "Add Task",
            systemImageName: "plus")
    }
}

触发短语

短语必须包含 \(.applicationName)，这样 Siri 才能消除歧义。请提供用户可能说出的几种自然表达。系统会负责匹配，因此您无需自行解析语言。

import AppIntents
// Provide variants; applicationName is required:
// phrases: [
//   "Add a task in \(.applicationName)",
//   "Create a task with \(.applicationName)",
//   "New \(.applicationName) task"
// ]
let phrases = "include applicationName token"
_ = phrases

在 Siri 之外呈现

由于意图采用声明式设计，同一个 AddTaskIntent 可以为交互式小组件 Button(intent:)、控制中心控件或快捷指令操作提供支持——它们都会运行您的 perform()，无需额外的连接代码。

import AppIntents
import SwiftUI
// In an interactive widget:
// Button(intent: AddTaskIntent()) {
//     Label("Add", systemImage: "plus")
// }
let reuse = "one intent, many surfaces"
_ = reuse

本地化意图

标题和对话使用 LocalizedStringResource，因此可以通过字符串目录进行翻译。触发短语也会按语言进行本地化，让 Siri 能够用用户自己的语言回应。

import AppIntents
struct GreetIntent: AppIntent {
    static var title: LocalizedStringResource = "Greet"
    func perform() async throws
        -> some IntentResult & ProvidesDialog {
        .result(dialog: "Welcome back")
    }
}

快速检查

回想一下，怎样的短语才是有效的 AppShortcut 短语。

回顾

您学习了 App Intents：

通过包含 title 和 perform() 来遵循 AppIntent；通过 @Parameter 收集输入，并使用 parameterSummary 对其进行描述。
使用 AppEntity 对数据建模，并通过 EntityQuery 为选择器和建议提供支持。
通过包含 \(.applicationName) 的 AppShortcut 短语来提供语音操作。
同一个意图可以为 Siri、快捷指令、交互式小组件和控件提供支持，并通过 LocalizedStringResource 实现本地化。

常见问题解答

「应用意图与快捷指令」课时是免费的吗？

是的 — 「应用意图与快捷指令」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Swift Academy 课程的其余内容，请升级到 CoddyKit PRO。 Swift Academy 课程共包含 4 节课。

「应用意图与快捷指令」这节课中我会学到什么？

将操作提供给 Siri 和快捷指令。你通过在浏览器中直接运行的动手代码来练习 Swift Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Swift Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Swift Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「应用意图与快捷指令」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Swift Academy 课中编写并运行代码吗？

能。每节 Swift Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Swift Academy