跳到正文

← 全部工具

给 Apple 开发者的免费工具

App Intents 与 App Shortcuts 生成器

要让操作出现在快捷指令、Siri 和聚焦搜索中，需要写一个遵循 AppIntent 的 struct（标题、@Parameter 属性和 perform()）；要给它配语音短语，就把它写进 AppShortcutsProvider。Apple 对短语的规则是：每条都包含 \(.applicationName)，最多一个参数，而且参数必须是 AppEnum 或 AppEntity；每个 App 最多 10 个 App Shortcuts、1,000 条短语。填写下方表单即可得到 Swift 代码，每条短语都会检查，另附文件放在哪里以及如何在快捷指令 App 中测试。

描述你的操作

全部在本页内完成，不上传任何内容。

Intent

留空时根据标题生成。

参数

操作需要的值。必填参数会在运行前由快捷指令询问。

固定选项（AppEnum）

快捷指令编辑器里显示的句子。参数的位置写 {name}，例如：Start {kind} timer。

App Shortcut

App 名称的位置写 {app}，参数写 {name}。也可以直接写 \(.applicationName) 和 \(\.$name)。

短语检查

  1. 需修改第 3 条短语Start a timer for {minutes} minutes in {app}

    minutes 是 Int 类型的参数。短语里只能放取值范围已知的参数：固定选项（AppEnum）或你自己的条目（AppEntity）。文本、数字这类任意值不能放进短语，Siri 会在短语之后再询问。

    来源： WWDC23: Spotlight your app with App Shortcuts · WWDC22: Implement App Shortcuts with App Intents

  2. 需修改第 4 条短语Time my work

    每条短语都必须包含 App 名称。请加上 {app}，这样 Siri 也能识别你设置的 App 名称同义词。

    来源： WWDC23: Spotlight your app with App Shortcuts · Human Interface Guidelines: App Shortcuts · App Intents: AppShortcutPhrase

Swift 代码

所有内容在一个文件里。复制到 App target 中新建的 Swift 文件，再把 perform() 里的注释换成你自己的代码。

import AppIntents

enum TimerKind: String, AppEnum {
    case pomodoro
    case deepWork
    case shortBreak

    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Timer Kind"
    static let caseDisplayRepresentations: [TimerKind: DisplayRepresentation] = [
        .pomodoro: "Pomodoro",
        .deepWork: "Deep Work",
        .shortBreak: "Short Break",
    ]
}

struct StartTimerIntent: AppIntent {
    static let title: LocalizedStringResource = "Start Timer"
    static let description = IntentDescription("Starts a focus timer.")
    static let openAppWhenRun: Bool = true

    @Parameter(title: "Kind")
    var kind: TimerKind

    @Parameter(title: "Minutes")
    var minutes: Int?

    static var parameterSummary: some ParameterSummary {
        Summary("Start \(\.$kind) timer for \(\.$minutes) minutes")
    }

    func perform() async throws -> some IntentResult {
        // Run the action here, using your app's own code.
        return .result()
    }
}

struct TimerShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: StartTimerIntent(),
            phrases: [
                "Start a timer in \(.applicationName)",
                "Start a \(\.$kind) timer in \(.applicationName)",
                "Start a timer for \(\.$minutes) minutes in \(.applicationName)",
                "Time my work",
            ],
            shortTitle: "Start Timer",
            systemImageName: "timer"
        )
    }
}

代码放在哪里

  • •在 App target 中新建 Swift 文件（File > New > File from Template > Swift File），粘贴代码。Apple 说明 intent 也可以放在 App 扩展、framework 或 Swift package 中。
  • •App Shortcuts provider 与它用到的 intent 放在一起。一个 App 只有一个 AppShortcutsProvider，所有 App Shortcut 都写在它的 appShortcuts 列表里，最常用的放在最前面。
  • •不需要额外注册。编译时会读取 intent 和 App Shortcuts，App 安装后即可使用。
  • •intent 在 App 扩展中运行时，把 openAppWhenRun 设为 true 会报错；它从 iOS 26 起已不推荐使用。App 支持 iOS 26 及以上时请用 supportedModes。
  • •AppEntity 的 id 要保持不变：快捷指令会把它保存在用户的快捷指令里。

来源： App Intents: App Shortcuts · App Intents: Creating your first app intent · App Intents: openAppWhenRun · App Intents: AppEntity

如何在快捷指令 App 中测试

  1. 在设备或模拟器上编译运行 App，等它启动。
  2. 打开快捷指令，点 + 新建快捷指令。
  3. 在操作列表中选“App”，点你的 App 图标，再选这个操作。
  4. 在摘要句子里设置参数，然后点运行。在 perform() 开头设断点，运行时会停在那里。
  5. 你的 App Shortcuts 还会出现在快捷指令中你的 App 下面和聚焦搜索里。在聚焦搜索中输入短语开头即可看到，也可以对 Siri 说出短语。

来源： App Intents: Verifying your App Intents implementation

Apple 对短语的规则

来源

Apple 的页面，查阅日期 2026 年 11 月 1 日：

工作原理

  • •表单生成一个 AppIntent：标题、说明、参数（文本、数字、开关、日期、链接、作为 AppEnum 的固定选项，或作为 AppEntity 的你自己的条目）、可选的参数摘要，以及运行时是否打开 App。
  • •需要打开 App 时，App 支持 iOS 17 至 25 就写 openAppWhenRun，支持 iOS 26 及以上则写 supportedModes（Apple 推荐的替代写法）。
  • •输入时即检查短语：App 名称标记、哪些参数可以出现、每条短语一个参数、重复短语，以及 10 个 App Shortcuts 和 1,000 条短语的上限；含固定选项的短语按选项数量计算。
  • •三种不同设置生成的文件已用 swiftc 针对 iOS 27.1 SDK 以 Swift 6 模式做过类型检查：两种面向 iOS 17，一种使用 supportedModes 面向 iOS 26。
  • •规则来自下方“来源”中列出的 Apple 页面，查阅日期为 2026 年 11 月 1 日。短语规则写在 Apple 的设计指南和 WWDC 讲座中，API 页面上没有。

能做什么，不能做什么

  • •一次生成一个 intent 和一个 App Shortcut。要再加，把 AppShortcut(...) 这一段复制到已有 provider 的 appShortcuts 列表中。
  • •不会替你写操作本身的代码。perform() 返回空结果，AppEntity 的查询在你接上自己的数据之前不返回任何条目。
  • •短语只按 Apple 写明的规则检查。Siri 能否听懂一条短语，只能在设备上试。
  • •不涉及面向 Apple 智能的 App Intent 领域、小组件、控制项、专注模式过滤器、带对话或摘要视图的结果，以及仅限 Mac 的细节（macOS 不支持 App Shortcuts，但支持 intent）。
  • •多语言短语应放在 Xcode 的 String Catalog 里；本页只写你输入的文字。

常见问题

为什么每条 App Shortcut 短语都要包含 \(.applicationName)？
Apple 规定每条短语都要包含 App 名称或其同义词，这样 Siri 才知道由哪个 App 响应。用 \(.applicationName) 标记而不是直接写名字，Siri 也会接受你设置的 App 名称同义词。
短语里可以放 String 或 Int 参数吗？
不可以。Apple 说明短语中的参数必须有已知的取值范围：AppEnum（选项固定），或 AppEntity（取值来自查询的 suggestedEntities()）。不支持“搜索 X”这类任意值。把 String 参数留在 intent 上，让 Siri 在短语之后询问。
一个 App 可以有多少个 App Shortcuts 和短语？
最多 10 个 App Shortcuts，整个 App 最多 1,000 条短语。短语数量包括参数的每个取值，所以一条带 20 个选项 AppEnum 的短语算 20 条。参数选项请尽量少。
用 openAppWhenRun 还是 supportedModes？
supportedModes 是较新的属性，需要 iOS 26 及以上；Apple 已将 openAppWhenRun 标为不推荐，并建议改用 supportedModes。如果 App 仍支持 iOS 17 至 25，openAppWhenRun = true 适用于在 App 内运行的 intent，但在 App 扩展中会报错。
App Shortcuts 需要在哪里注册吗？
不需要。编译时会读取 AppShortcutsProvider，App 一安装好就能使用，第一次打开之前也可以。如果 AppEntity 的建议条目列表有变化，调用 provider 的 updateAppShortcutParameters()，让含该参数的短语随之更新。
上架前怎么测试 intent？
先运行一次 App，打开快捷指令，点 + 新建快捷指令，选“App”，点你的 App 并选择这个操作，设置参数后点运行。在 perform() 里设断点可以逐步调试。之后在聚焦搜索中输入短语开头，或对 Siri 说出短语，检查 App Shortcuts。

用到这个工具的指南

相关工具