iOS App Intents 开发指南：集成 Siri、快捷指令、小组件与 Apple Intelligence

app-intents by dpearson2699/swift-ios-skills

518 周安装量

321 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/dpearson2699/swift-ios-skills --skill app-intents

iOS 开发 Swift

🇨🇳中文介绍

App Intents (iOS 26+)

实现、审查和扩展 App Intents，以将应用功能暴露给 Siri、快捷指令、聚焦搜索、小组件、控制中心和 Apple Intelligence。

分类工作流

步骤 1：确定集成界面

确定意图针对的系统功能：

界面	协议	起始版本
Siri / 快捷指令	`AppIntent`	iOS 16
可配置小组件	`WidgetConfigurationIntent`	iOS 17

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 2：定义数据模型

创建 AppEntity 影子模型（请勿直接遵循核心数据模型）。
为固定的参数选项创建 AppEnum 类型。
为解析选择正确的 EntityQuery 变体。
使用 IndexedEntity 和 @Property(indexingKey:) 标记可搜索的实体。

步骤 3：实现意图

遵循 AppIntent（或专门的子协议）。
为所有面向用户的输入声明 @Parameter 属性。
实现 perform() async throws -> some IntentResult。
为快捷指令 UI 添加 parameterSummary。
通过 AppShortcutsProvider 注册短语。

在快捷指令应用中构建并运行以确认参数解析。
在 Xcode 中使用意图预览测试 Siri 短语。
确认 IndexedEntity 类型的聚焦搜索结果。
检查 WidgetConfigurationIntent 意图的小组件配置。

系统通过 init() 实例化结构体，设置参数，然后调用 perform()。为快捷指令 UI 声明 title 和 parameterSummary。

struct OrderSoupIntent: AppIntent {
    static var title: LocalizedStringResource = "Order Soup"
    static var description = IntentDescription("Place a soup order.")

    @Parameter(title: "Soup") var soup: SoupEntity
    @Parameter(title: "Quantity", default: 1) var quantity: Int

    static var parameterSummary: some ParameterSummary {
        Summary("Order \(\.$soup)") { \.$quantity }
    }

    func perform() async throws -> some IntentResult {
        try await OrderService.shared.place(soup: soup.id, quantity: quantity)
        return .result(dialog: "Ordered \(quantity) \(soup.name).")
    }
}

可选成员：description (IntentDescription)、openAppWhenRun (Bool)、isDiscoverable (Bool)、authenticationPolicy (IntentAuthenticationPolicy)。

使用 @Parameter 声明每个面向用户的输入。可选参数不是必需的；带有 default 的非可选参数会被预填充。

// 错误：没有默认值的非可选参数 —— 系统无法预览
@Parameter(title: "Count")
var count: Int

// 正确：提供默认值或设为可选
@Parameter(title: "Count", default: 1)
var count: Int

@Parameter(title: "Count")
var count: Int?

基本类型：Int、Double、Bool、String、URL、Date、DateComponents。框架类型：Currency、Person、IntentFile。度量单位：Measurement<UnitLength>、Measurement<UnitTemperature> 等。自定义类型：任何 AppEntity 或 AppEnum。

常见的初始化器模式

// 基本
@Parameter(title: "Name")
var name: String

// 带默认值
@Parameter(title: "Count", default: 5)
var count: Int

// 数字滑块
@Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0, 100))
var volume: Int

// 选项提供者（动态列表）
@Parameter(title: "Category", optionsProvider: CategoryOptionsProvider())
var category: Category

// 带内容类型的文件
@Parameter(title: "Document", supportedContentTypes: [.pdf, .plainText])
var document: IntentFile

// 带单位的度量值
@Parameter(title: "Distance", defaultUnit: .miles, supportsNegativeNumbers: false)
var distance: Measurement<UnitLength>

所有初始化器变体请参阅 references/appintents-advanced.md。

创建与应用数据对应的影子模型 —— 切勿直接遵循核心数据模型类型。

struct SoupEntity: AppEntity {
    static let defaultQuery = SoupEntityQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Soup"
    var id: String

    @Property(title: "Name") var name: String
    @Property(title: "Price") var price: Double

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)", subtitle: "$\(String(format: "%.2f", price))")
    }

    init(from soup: Soup) {
        self.id = soup.id; self.name = soup.name; self.price = soup.price
    }
}

必需项：id、defaultQuery（静态）、displayRepresentation、typeDisplayRepresentation（静态）。使用 @Property(title:) 标记属性以暴露用于过滤/排序。没有 @Property 的属性保持内部使用。

EntityQuery (4 种变体)

1. EntityQuery (基础 —— 通过 ID 解析)

struct SoupEntityQuery: EntityQuery {
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
    }
    func suggestedEntities() async throws -> [SoupEntity] {
        SoupStore.shared.featured.map { SoupEntity(from: $0) }
    }
}

2. EntityStringQuery (自由文本搜索)

struct SoupStringQuery: EntityStringQuery {
    func entities(matching string: String) async throws -> [SoupEntity] {
        SoupStore.shared.search(string).map { SoupEntity(from: $0) }
    }
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
    }
}

3. EnumerableEntityQuery (有限集合)

struct AllSoupsQuery: EnumerableEntityQuery {
    func allEntities() async throws -> [SoupEntity] {
        SoupStore.shared.allSoups.map { SoupEntity(from: $0) }
    }
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
    }
}

4. UniqueAppEntityQuery (单例，iOS 18+)

用于像应用设置这样的单实例实体。

struct AppSettingsEntity: UniqueAppEntity {
    static let defaultQuery = AppSettingsQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Settings"
    var displayRepresentation: DisplayRepresentation { "App Settings" }

    var id: String { "app-settings" }
}

struct AppSettingsQuery: UniqueAppEntityQuery {
    func entity() async throws -> AppSettingsEntity {
        AppSettingsEntity()
    }
}

支持过滤/排序的 EntityPropertyQuery 请参阅 references/appintents-advanced.md。

定义固定的可选值集合。必须由 LosslessStringConvertible 原始值支持（使用 String）。

enum SoupSize: String, AppEnum {
    case small, medium, large

    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Size"

    static var caseDisplayRepresentations: [SoupSize: DisplayRepresentation] = [
        .small: "Small",
        .medium: "Medium",
        .large: "Large"
    ]
}



// 错误：使用 Int 原始值
enum Priority: Int, AppEnum { // 编译器错误 —— Int 不是 LosslessStringConvertible
    case low = 1, medium = 2, high = 3
}

// 正确：使用 String 原始值
enum Priority: String, AppEnum {
    case low, medium, high
    // ...
}

AppShortcutsProvider

注册预构建的快捷指令，这些快捷指令无需用户配置即可出现在 Siri 和快捷指令应用中。

struct MyAppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OrderSoupIntent(),
            phrases: [
                "Order \(\.$soup) in \(.applicationName)",
                "Get soup from \(.applicationName)"
            ],
            shortTitle: "Order Soup",
            systemImageName: "cup.and.saucer"
        )
    }

    static var shortcutTileColor: ShortcutTileColor = .navy
}

每个短语必须包含 \(.applicationName)。
短语可以引用参数：\(\.$soup)。
当动态选项值改变时，调用 updateAppShortcutParameters()。
使用 negativePhrases 防止 Siri 误激活。

捐赠意图，以便系统学习用户模式并在聚焦搜索中建议它们：

let intent = OrderSoupIntent()
intent.soup = favoriteSoupEntity
try await intent.donate()

遵循 PredictableIntent 以便 Siri 预测即将发生的操作。

交互式小组件意图

在小组件中将 AppIntent 与 Button/Toggle 一起使用。使用 WidgetConfigurationIntent 处理可配置的小组件参数。

struct ToggleFavoriteIntent: AppIntent {
    static var title: LocalizedStringResource = "Toggle Favorite"
    @Parameter(title: "Item ID") var itemID: String

    func perform() async throws -> some IntentResult {
        FavoriteStore.shared.toggle(itemID)
        return .result()
    }
}

// 在小组件视图中：
Button(intent: ToggleFavoriteIntent(itemID: entry.id)) {
    Image(systemName: entry.isFavorite ? "heart.fill" : "heart")
}

WidgetConfigurationIntent

struct BookWidgetConfig: WidgetConfigurationIntent {
    static var title: LocalizedStringResource = "Favorite Book"
    @Parameter(title: "Book", default: "The Swift Programming Language") var bookTitle: String
}

// 连接到 WidgetKit：
struct MyWidget: Widget {
    var body: some WidgetConfiguration {
        AppIntentConfiguration(kind: "FavoriteBook", intent: BookWidgetConfig.self, provider: MyTimelineProvider()) { entry in
            BookWidgetView(entry: entry)
        }
    }
}

控制中心小组件 (iOS 18+)

使用 ControlConfigurationIntent 和 ControlWidget 在控制中心和锁定屏幕上暴露控件。

struct LightControlConfig: ControlConfigurationIntent {
    static var title: LocalizedStringResource = "Light Control"
    @Parameter(title: "Light", default: .livingRoom) var light: LightEntity
}

struct ToggleLightIntent: AppIntent {
    static var title: LocalizedStringResource = "Toggle Light"
    @Parameter(title: "Light") var light: LightEntity
    func perform() async throws -> some IntentResult {
        try await LightService.shared.toggle(light.id)
        return .result()
    }
}

struct LightControl: ControlWidget {
    var body: some ControlWidgetConfiguration {
        AppIntentControlConfiguration(kind: "LightControl", intent: LightControlConfig.self) { config in
            ControlWidgetToggle(config.light.name, isOn: config.light.isOn, action: ToggleLightIntent(light: config.light))
        }
    }
}

聚焦搜索和 IndexedEntity (iOS 18+)

遵循 IndexedEntity 以支持聚焦搜索。在 iOS 26+ 上，使用 indexingKey 处理结构化元数据：

struct RecipeEntity: IndexedEntity {
    static let defaultQuery = RecipeQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Recipe"
    var id: String

    @Property(title: "Name", indexingKey: .title) var name: String   // iOS 26+
    @ComputedProperty(indexingKey: .description)                      // iOS 26+
    var summary: String { "\(name) -- a delicious recipe" }

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)")
    }
}

在系统 UI 中显示交互式片段：

struct OrderStatusSnippet: SnippetIntent {
    static var title: LocalizedStringResource = "Order Status"
    func perform() async throws -> some IntentResult & ShowsSnippetView {
        let status = await OrderTracker.currentStatus()
        return .result(view: OrderStatusSnippetView(status: status))
    }
    static func reload() { /* 通知系统刷新 */ }
}

// 调用意图可以通过以下方式显示此片段：
// return .result(snippetIntent: OrderStatusSnippet())

IntentValueQuery (视觉智能)

struct ProductValueQuery: IntentValueQuery {
    typealias Input = String
    typealias Result = ProductEntity
    func values(for input: String) async throws -> [ProductEntity] {
        ProductStore.shared.search(input).map { ProductEntity(from: $0) }
    }
}

让核心数据模型遵循 AppEntity。 应创建专用的影子模型。核心模型带有与意图生命周期冲突的持久化逻辑。
短语中缺少 \(.applicationName)。 每个 AppShortcut 短语必须包含应用程序名称标记。Siri 用它来消除歧义。
没有默认值的非可选 @Parameter。 系统无法预览或预填充此类参数。让非可选参数具有 default，或者将它们标记为可选。
```
// 错误
@Parameter(title: "Count")
var count: Int

// 正确
@Parameter(title: "Count", default: 1)
var count: Int
```
为 AppEnum 使用 Int 原始值。 AppEnum 要求 RawRepresentable 且 RawValue: LosslessStringConvertible。请使用 String。
忘记 suggestedEntities()。 没有它，快捷指令选择器将不显示默认值。
在 entities(for:) 中为缺失的实体抛出错误。 应省略缺失的实体。
过时的聚焦搜索索引。 当实体数据更改时，调用 updateAppShortcutParameters()。
缺少 typeDisplayRepresentation。 AppEntity 和 AppEnum 都需要它。
使用已弃用的 @AssistantEntity(schema:) / @AssistantEnum(schema:)。 请改用 @AppEntity(schema:) 和 @AppEnum(schema:)。注意：@AssistantIntent(schema:) 仍然有效。
阻塞 perform()。 perform() 是异步的 —— 对 I/O 使用 await。

每个 AppIntent 都有描述性的 title（动词 + 名词，标题大小写）
@Parameter 类型是可选的或具有默认值以供系统预览
AppEntity 类型是影子模型，而不是核心数据模型的遵循
AppEntity 具有 displayRepresentation 和 typeDisplayRepresentation
EntityQuery.entities(for:) 省略缺失的 ID；实现了 suggestedEntities()
AppEnum 使用带有 caseDisplayRepresentations 的 String 原始值
AppShortcutsProvider 短语包含 \(.applicationName)；定义了 parameterSummary
IndexedEntity 属性在 iOS 26+ 上使用 @Property(indexingKey:)
控制中心意图遵循 ControlConfigurationIntent；小组件意图遵循 WidgetConfigurationIntent
没有已弃用的 @AssistantEntity / @AssistantEnum 宏（注意：@AssistantIntent(schema:) 仍然有效）
perform() 使用 async/await（非阻塞）；在预期的隔离上下文中运行；意图类型是 Sendable

有关 @Parameter 变体、EntityPropertyQuery、助手模式、聚焦过滤器、SiriKit 迁移、错误处理、确认流程、身份验证、URL 可表示类型和聚焦搜索索引的详细信息，请参阅 references/appintents-advanced.md。

🇺🇸English

App Intents (iOS 26+)

Implement, review, and extend App Intents to expose app functionality to Siri, Shortcuts, Spotlight, widgets, Control Center, and Apple Intelligence.

Triage Workflow
AppIntent Protocol
@Parameter
AppEntity
EntityQuery (4 Variants)
AppEnum
AppShortcutsProvider
Siri Integration
Interactive Widget Intents
Control Center Widgets (iOS 18+)
Spotlight and IndexedEntity (iOS 18+)
iOS 26 Additions
Common Mistakes
Review Checklist
References

Triage Workflow

Step 1: Identify the integration surface

Determine which system feature the intent targets:

Surface	Protocol	Since
Siri / Shortcuts	`AppIntent`	iOS 16
Configurable widget	`WidgetConfigurationIntent`	iOS 17
Control Center	`ControlConfigurationIntent`	iOS 18
Spotlight search	`IndexedEntity`	iOS 18
Apple Intelligence	`@AppIntent(schema:)`	iOS 18
Interactive snippets	`SnippetIntent`	iOS 26
Visual Intelligence	`IntentValueQuery`	iOS 26

Step 2: Define the data model

Create AppEntity shadow models (do NOT conform core data models directly).
Create AppEnum types for fixed parameter choices.
Choose the right EntityQuery variant for resolution.
Mark searchable entities with IndexedEntity and @Property(indexingKey:).

Step 3: Implement the intent

Conform to AppIntent (or a specialized sub-protocol).
Declare @Parameter properties for all user-facing inputs.
Implement perform() async throws -> some IntentResult.
Add parameterSummary for Shortcuts UI.
Register phrases via AppShortcutsProvider.

Step 4: Verify

Build and run in Shortcuts app to confirm parameter resolution.
Test Siri phrases with the intent preview in Xcode.
Confirm Spotlight results for IndexedEntity types.
Check widget configuration for WidgetConfigurationIntent intents.

AppIntent Protocol

The system instantiates the struct via init(), sets parameters, then calls perform(). Declare a title and parameterSummary for Shortcuts UI.

struct OrderSoupIntent: AppIntent {
    static var title: LocalizedStringResource = "Order Soup"
    static var description = IntentDescription("Place a soup order.")

    @Parameter(title: "Soup") var soup: SoupEntity
    @Parameter(title: "Quantity", default: 1) var quantity: Int

    static var parameterSummary: some ParameterSummary {
        Summary("Order \(\.$soup)") { \.$quantity }
    }

    func perform() async throws -> some IntentResult {
        try await OrderService.shared.place(soup: soup.id, quantity: quantity)
        return .result(dialog: "Ordered \(quantity) \(soup.name).")
    }
}

Optional members: description (IntentDescription), openAppWhenRun (Bool), isDiscoverable (Bool), authenticationPolicy (IntentAuthenticationPolicy).

@Parameter

Declare each user-facing input with @Parameter. Optional parameters are not required; non-optional parameters with a default are pre-filled.

// WRONG: Non-optional parameter without default -- system cannot preview
@Parameter(title: "Count")
var count: Int

// CORRECT: Provide a default or make optional
@Parameter(title: "Count", default: 1)
var count: Int

@Parameter(title: "Count")
var count: Int?

Supported value types

Primitives: Int, Double, Bool, String, URL, Date, DateComponents. Framework: Currency, Person, IntentFile. Measurements: Measurement<UnitLength>, Measurement<UnitTemperature>, and others. Custom: any or .

Common initializer patterns

// Basic
@Parameter(title: "Name")
var name: String

// With default
@Parameter(title: "Count", default: 5)
var count: Int

// Numeric slider
@Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0, 100))
var volume: Int

// Options provider (dynamic list)
@Parameter(title: "Category", optionsProvider: CategoryOptionsProvider())
var category: Category

// File with content types
@Parameter(title: "Document", supportedContentTypes: [.pdf, .plainText])
var document: IntentFile

// Measurement with unit
@Parameter(title: "Distance", defaultUnit: .miles, supportsNegativeNumbers: false)
var distance: Measurement<UnitLength>

See references/appintents-advanced.md for all initializer variants.

AppEntity

Create shadow models that mirror app data -- never conform core data model types directly.

struct SoupEntity: AppEntity {
    static let defaultQuery = SoupEntityQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Soup"
    var id: String

    @Property(title: "Name") var name: String
    @Property(title: "Price") var price: Double

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)", subtitle: "$\(String(format: "%.2f", price))")
    }

    init(from soup: Soup) {
        self.id = soup.id; self.name = soup.name; self.price = soup.price
    }
}

Required: id, defaultQuery (static), displayRepresentation, typeDisplayRepresentation (static). Mark properties with @Property(title:) to expose for filtering/sorting. Properties without @Property remain internal.

EntityQuery (4 Variants)

1. EntityQuery (base -- resolve by ID)

struct SoupEntityQuery: EntityQuery {
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
    }
    func suggestedEntities() async throws -> [SoupEntity] {
        SoupStore.shared.featured.map { SoupEntity(from: $0) }
    }
}

2. EntityStringQuery (free-text search)

struct SoupStringQuery: EntityStringQuery {
    func entities(matching string: String) async throws -> [SoupEntity] {
        SoupStore.shared.search(string).map { SoupEntity(from: $0) }
    }
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
    }
}

3. EnumerableEntityQuery (finite set)

struct AllSoupsQuery: EnumerableEntityQuery {
    func allEntities() async throws -> [SoupEntity] {
        SoupStore.shared.allSoups.map { SoupEntity(from: $0) }
    }
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore.shared.soups.filter { identifiers.contains($0.id) }.map { SoupEntity(from: $0) }
    }
}

4. UniqueAppEntityQuery (singleton, iOS 18+)

Use for single-instance entities like app settings.

struct AppSettingsEntity: UniqueAppEntity {
    static let defaultQuery = AppSettingsQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Settings"
    var displayRepresentation: DisplayRepresentation { "App Settings" }

    var id: String { "app-settings" }
}

struct AppSettingsQuery: UniqueAppEntityQuery {
    func entity() async throws -> AppSettingsEntity {
        AppSettingsEntity()
    }
}

See references/appintents-advanced.md for EntityPropertyQuery with filter/sort support.

AppEnum

Define fixed sets of selectable values. Must be backed by a LosslessStringConvertible raw value (use String).

enum SoupSize: String, AppEnum {
    case small, medium, large

    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Size"

    static var caseDisplayRepresentations: [SoupSize: DisplayRepresentation] = [
        .small: "Small",
        .medium: "Medium",
        .large: "Large"
    ]
}



// WRONG: Using Int raw value
enum Priority: Int, AppEnum { // Compiler error -- Int is not LosslessStringConvertible
    case low = 1, medium = 2, high = 3
}

// CORRECT: Use String raw value
enum Priority: String, AppEnum {
    case low, medium, high
    // ...
}

AppShortcutsProvider

struct MyAppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OrderSoupIntent(),
            phrases: [
                "Order \(\.$soup) in \(.applicationName)",
                "Get soup from \(.applicationName)"
            ],
            shortTitle: "Order Soup",
            systemImageName: "cup.and.saucer"
        )
    }

    static var shortcutTileColor: ShortcutTileColor = .navy
}

Phrase rules

Every phrase MUST include \(.applicationName).
Phrases can reference parameters: \(\.$soup).
Call updateAppShortcutParameters() when dynamic option values change.
Use negativePhrases to prevent false Siri activations.

Siri Integration

Donating intents

Donate intents so the system learns user patterns and suggests them in Spotlight:

let intent = OrderSoupIntent()
intent.soup = favoriteSoupEntity
try await intent.donate()

Predictable intents

Conform to PredictableIntent for Siri prediction of upcoming actions.

Interactive Widget Intents

Use AppIntent with Button/Toggle in widgets. Use WidgetConfigurationIntent for configurable widget parameters.

struct ToggleFavoriteIntent: AppIntent {
    static var title: LocalizedStringResource = "Toggle Favorite"
    @Parameter(title: "Item ID") var itemID: String

    func perform() async throws -> some IntentResult {
        FavoriteStore.shared.toggle(itemID)
        return .result()
    }
}

// In widget view:
Button(intent: ToggleFavoriteIntent(itemID: entry.id)) {
    Image(systemName: entry.isFavorite ? "heart.fill" : "heart")
}

WidgetConfigurationIntent

struct BookWidgetConfig: WidgetConfigurationIntent {
    static var title: LocalizedStringResource = "Favorite Book"
    @Parameter(title: "Book", default: "The Swift Programming Language") var bookTitle: String
}

// Connect to WidgetKit:
struct MyWidget: Widget {
    var body: some WidgetConfiguration {
        AppIntentConfiguration(kind: "FavoriteBook", intent: BookWidgetConfig.self, provider: MyTimelineProvider()) { entry in
            BookWidgetView(entry: entry)
        }
    }
}

Control Center Widgets (iOS 18+)

Expose controls in Control Center and Lock Screen with ControlConfigurationIntent and ControlWidget.

struct LightControlConfig: ControlConfigurationIntent {
    static var title: LocalizedStringResource = "Light Control"
    @Parameter(title: "Light", default: .livingRoom) var light: LightEntity
}

struct ToggleLightIntent: AppIntent {
    static var title: LocalizedStringResource = "Toggle Light"
    @Parameter(title: "Light") var light: LightEntity
    func perform() async throws -> some IntentResult {
        try await LightService.shared.toggle(light.id)
        return .result()
    }
}

struct LightControl: ControlWidget {
    var body: some ControlWidgetConfiguration {
        AppIntentControlConfiguration(kind: "LightControl", intent: LightControlConfig.self) { config in
            ControlWidgetToggle(config.light.name, isOn: config.light.isOn, action: ToggleLightIntent(light: config.light))
        }
    }
}

Spotlight and IndexedEntity (iOS 18+)

Conform to IndexedEntity for Spotlight search. On iOS 26+, use indexingKey for structured metadata:

struct RecipeEntity: IndexedEntity {
    static let defaultQuery = RecipeQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Recipe"
    var id: String

    @Property(title: "Name", indexingKey: .title) var name: String   // iOS 26+
    @ComputedProperty(indexingKey: .description)                      // iOS 26+
    var summary: String { "\(name) -- a delicious recipe" }

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)")
    }
}

iOS 26 Additions

SnippetIntent

Display interactive snippets in system UI:

struct OrderStatusSnippet: SnippetIntent {
    static var title: LocalizedStringResource = "Order Status"
    func perform() async throws -> some IntentResult & ShowsSnippetView {
        let status = await OrderTracker.currentStatus()
        return .result(view: OrderStatusSnippetView(status: status))
    }
    static func reload() { /* notify system to refresh */ }
}

// A calling intent can display this snippet via:
// return .result(snippetIntent: OrderStatusSnippet())

IntentValueQuery (Visual Intelligence)

struct ProductValueQuery: IntentValueQuery {
    typealias Input = String
    typealias Result = ProductEntity
    func values(for input: String) async throws -> [ProductEntity] {
        ProductStore.shared.search(input).map { ProductEntity(from: $0) }
    }
}

Common Mistakes

Conforming core data models to AppEntity. Create dedicated shadow models instead. Core models carry persistence logic that conflicts with intent lifecycle.
Missing\(.applicationName) in phrases. Every AppShortcut phrase MUST include the application name token. Siri uses it for disambiguation.
Non-optional @Parameter without default. The system cannot preview or pre-fill such parameters. Make non-optional parameters have a default, or mark them optional.
```
// WRONG
@Parameter(title: "Count")
var count: Int

// CORRECT
@Parameter(title: "Count", default: 1)
var count: Int
```
Using Int raw value for AppEnum. AppEnum requires RawRepresentable where RawValue: LosslessStringConvertible. Use .

Review Checklist

Every AppIntent has a descriptive title (verb + noun, title case)
@Parameter types are optional or have defaults for system preview
AppEntity types are shadow models, not core data model conformances
AppEntity has displayRepresentation and typeDisplayRepresentation
EntityQuery.entities(for:) omits missing IDs; suggestedEntities() implemented
AppEnum uses raw value with

References

See references/appintents-advanced.md for @Parameter variants, EntityPropertyQuery, assistant schemas, focus filters, SiriKit migration, error handling, confirmation flows, authentication, URL-representable types, and Spotlight indexing details.

Weekly Installs

382

Repository

dpearson2699/sw…s-skills

GitHub Stars

269

First Seen

Mar 3, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykPass

Installed on

codex379

gemini-cli376

amp376

cline376

github-copilot376

kimi-cli376

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装

ForgettingsuggestedEntities(). Without it, the Shortcuts picker shows no defaults.

Throwing for missing entities inentities(for:). Omit missing entities instead.

Stale Spotlight index. Call updateAppShortcutParameters() when entity data changes.

MissingtypeDisplayRepresentation. Both AppEntity and AppEnum require it.

Using deprecated@AssistantEntity(schema:) / @AssistantEnum(schema:). Use @AppEntity(schema:) and @AppEnum(schema:) instead. Note: @AssistantIntent(schema:) is still active.

Blocking perform(). perform() is async -- use await for I/O.

caseDisplayRepresentations

AppShortcutsProvider phrases include \(.applicationName); parameterSummary defined

IndexedEntity properties use @Property(indexingKey:) on iOS 26+

Control Center intents conform to ControlConfigurationIntent; widget intents to WidgetConfigurationIntent

No deprecated @AssistantEntity / @AssistantEnum macros (note: @AssistantIntent(schema:) is still active)

perform() uses async/await (no blocking); runs in expected isolation context; intent types are Sendable

iOS App Intents 开发指南：集成 Siri、快捷指令、小组件与 Apple Intelligence

🇨🇳中文介绍

App Intents (iOS 26+)

目录

分类工作流

步骤 1：确定集成界面

相关 Skills

步骤 2：定义数据模型

步骤 3：实现意图

步骤 4：验证

AppIntent 协议

@Parameter

支持的值类型

常见的初始化器模式

AppEntity

EntityQuery (4 种变体)

1. EntityQuery (基础 —— 通过 ID 解析)

2. EntityStringQuery (自由文本搜索)

3. EnumerableEntityQuery (有限集合)

4. UniqueAppEntityQuery (单例，iOS 18+)

AppEnum

AppShortcutsProvider

短语规则

Siri 集成

捐赠意图

可预测意图

交互式小组件意图

WidgetConfigurationIntent

控制中心小组件 (iOS 18+)

聚焦搜索和 IndexedEntity (iOS 18+)

iOS 26 新增内容

SnippetIntent

IntentValueQuery (视觉智能)

常见错误

审查清单

参考资料

🇺🇸English

App Intents (iOS 26+)

Contents

Triage Workflow

Step 1: Identify the integration surface

Step 2: Define the data model

Step 3: Implement the intent

Step 4: Verify

AppIntent Protocol

@Parameter

Supported value types

Common initializer patterns

AppEntity

EntityQuery (4 Variants)

1. EntityQuery (base -- resolve by ID)

2. EntityStringQuery (free-text search)

3. EnumerableEntityQuery (finite set)

4. UniqueAppEntityQuery (singleton, iOS 18+)

AppEnum

AppShortcutsProvider

Phrase rules

Siri Integration

Donating intents

Predictable intents

Interactive Widget Intents

WidgetConfigurationIntent

Control Center Widgets (iOS 18+)

Spotlight and IndexedEntity (iOS 18+)

iOS 26 Additions

SnippetIntent

IntentValueQuery (Visual Intelligence)

Common Mistakes

Review Checklist

References

最新 Skills