了解 App Intents

了解 app intents 框架及其在 apple 开发者平台中愈显关键的作用。我们将向你全面介绍意图、实体、查询等核心概念。你将了解如何综合运用这些概念，以便使你的 app 与 apple 设备 (从“聚焦”和“快捷指令”等软件功能到操作按钮等硬件功能) 实现整合。我们还将介绍如何将 app intents 作为你 app 的入口，以便将来实现与 apple 智能的整合。

视频地址

此文章由AI生成，可能存在错误，如有问题，请联系djs66256@163.com

深度解析 App Intents：打造全系统可用的应用功能

引言

App Intents 框架作为 Apple 开发者生态中的重要组成部分，正在为应用带来前所未有的系统级集成能力。本文将详细解析该框架的核心概念与实现方法，帮助开发者理解如何通过 App Intents 让应用功能突破自身边界，融入整个 Apple 生态系统。

App Intents 核心概念

框架定位与价值

App Intents 不仅仅是一个功能构建框架，更是一个应用能力辐射系统。通过该框架，开发者可以实现：

• 聚焦搜索中的个性化结果展示
• 操作按钮的情境感知体验
• 小部件的可配置交互
• 控制中心的便捷控件
• Apple Pencil Pro 的自定义操作

特别值得注意的是，今年新增的 Mac 版聚焦搜索功能已能随处调用应用操作，进一步扩展了应用与系统的交互场景。

基础元素解析

在 App Intents 框架中，主要包含三类核心元素：

1. Intent（意图）：代表应用的”动词”，描述可执行的操作
2. App Enum（枚举）：表示固定值集合的类型
3. App Entity（实体）：表示动态类型

这些元素共同构成了应用的语义模型，使其能够被系统理解和调用。

实践指南

创建首个 App Intent

以一个全球地标旅行应用为例，创建一个导航至地标列表的 intent 需要以下步骤：

struct NavigateIntent: AppIntent {
    static let title: LocalizedStringResource = "导航至地标"
    static let supportedModes: IntentModes = .foreground
    
    @MainActor
    func perform() async throws -> some IntentResult {
        Navigator.shared.navigate(to: .landmarks)
        return .result()
    }
}

这段代码定义了符合 AppIntent 协议的结构体，包含本地化标题和执行逻辑的 perform 方法。由于导航操作需要在主线程执行，perform 方法被标记为 @MainActor。

参数化 Intent

为了扩展导航功能，可以创建 App Enum 定义导航选项：

enum NavigationOption: String, AppEnum {
    case landmarks
    case map
    case collections
    
    static let typeDisplayRepresentation = "导航选项"
    
    static let caseDisplayRepresentations = [
        .landmarks: "地标",
        .map: "地图",
        .collections: "收藏集"
    ]
}

然后在 intent 中添加参数：

struct NavigateIntent: AppIntent {
    @Parameter(title: "版块", requestValueDialog: "要导航到哪个版块？") 
    var navigationOption: NavigationOption
    //...其余实现
}

优化用户体验

通过 ParameterSummary 提供流畅的语句式描述：

static var parameterSummary: some ParameterSummary {
    Summary("导航至\(\.$navigationOption)版块")
}

今年新增的功能是：当 intent 包含完整 ParameterSummary 时，用户可直接从 Mac 的聚焦搜索运行该操作。

系统集成

App Shortcuts 创建

对于核心 intent，可以通过 App Shortcuts 使其在安装后立即可用：

struct TravelTrackingAppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: NavigateIntent(),
            phrases: [
                "在\(.applicationName)中导航",
                "在\(.applicationName)中导航到\(\.$navigationOption)"
            ],
            shortTitle: "导航",
            systemImageName: "arrowshape.forward"
        )
    }
}

这些快捷方式会突出显示在聚焦搜索中，并支持通过 Siri 语音触发。

数据建模

动态实体实现

地标作为应用的核心概念，需要创建 App Entity 进行建模：

struct LandmarkEntity: AppEntity {
    var id: Int { landmark.id }
    
    @ComputedProperty
    var name: String { landmark.name }
    
    static let typeDisplayRepresentation = TypeDisplayRepresentation(name: "地标")
    var displayRepresentation: DisplayRepresentation { ... }
    
    static let defaultQuery = LandmarkEntityQuery()
}

实体必须提供查询机制（EntityQuery）来回答系统查询：

struct LandmarkEntityQuery: EntityQuery {
    @Dependency var modelData: ModelData
    
    func entities(for identifiers: [Int]) async throws -> [LandmarkEntity] {
        modelData.landmarks(for: identifiers).map(LandmarkEntity.init)
    }
}

进阶功能

实体功能扩展

通过实现更多协议，可以扩展实体功能：

1. Transferable 协议：支持图像分享
2. IndexedEntity 协议：实现聚焦搜索索引
3. OpenIntent：实现深度链接

例如实现深度链接：

struct OpenLandmarkIntent: OpenIntent, TargetContentProvidingIntent {
    @Parameter(title: "地标") 
    var target: LandmarkEntity
}

// 在 SwiftUI 中处理导航
.onAppIntentExecution(OpenLandmarkIntent.self) { intent in
    path.append(intent.target.landmark)
}

查询增强

通过实现更多查询协议，可以提供更丰富的实体发现方式：

• EnumerableEntityQuery：返回所有实体
• EntityStringQuery：支持文本搜索
• EntityPropertyQuery：支持属性过滤和排序

底层原理

App Intents 采用编译时生成机制，应用源代码在构建时会被解析，生成的应用意图表示直接嵌入应用包中。这种设计使得系统在安装后即可理解应用能力，无需实际运行应用。

当在多个 target 间共享类型时，需要定义 AppIntentsPackage：

// 在Swift包中
public struct TravelTrackingKitPackage: AppIntentsPackage {}

// 在主target中
struct TravelTrackingPackage: AppIntentsPackage {
    static var includedPackages: [any AppIntentsPackage.Type] {
        [TravelTrackingKitPackage.self]
    }
}

今年新增了对 Swift 包和静态库的支持。

总结与建议

App Intents 框架为开发者提供了强大的系统集成能力，建议从小处着手，先添加一个 App Shortcut，再逐步探索框架的其他功能。通过将应用的核心功能转化为系统可理解的意图和实体，开发者可以创造更加无缝的用户体验。

相关资源

相关视频

使用 App Intents 针对”快捷指令”和”聚焦”进行开发
设计交互式摘要卡片
利用 App Intents 为用户奉上 App 的核心功能
利用 App Intents 设计提升系统体验
带你的 App 登陆 Siri
App Intents 的新功能

文档

App intent domains
App Intents
App Shortcuts
Creating your first app intent
Integrating actions with Siri and Apple Intelligence
Making actions and content discoverable and widely available