Swift Academy · Урок

App Intents и быстрые команды

Предоставляйте действия для Siri и быстрых команд.

«App Intents и быстрые команды» — бесплатный урок Swift Academy на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Swift Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Swift Academy содержит 4 уроков всего.

Что такое App Intents

Фреймворк App Intents предоставляет системе действия Вашего приложения — Siri, «Командам», 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. Система запрашивает отсутствующие значения и проверяет их. У каждого параметра есть заголовок, отображаемый в редакторе «Команд».

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 описывает предложение, отображаемое в редакторе Shortcuts, встраивая параметры в естественный язык, например: «Добавить \(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 и Shortcuts предложить пользователю выбрать значение параметра из Ваших данных.

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

Запросы сущностей

EntityQuery сообщает системе, как находить Ваши сущности по идентификатору и как составлять список предложений. На этом основано окно выбора, которое пользователь видит при выборе значения в Shortcuts или при ответе 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:), элементом управления в Пункте управления или действием в Shortcuts — и всё это запускает Ваш 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:

Реализуйте AppIntent с помощью title и perform(); получайте входные данные через @Parameter и описывайте их с помощью parameterSummary.
Представляйте данные как AppEntity, используя EntityQuery для окон выбора и предложений.
Предоставляйте голосовые действия через фразы AppShortcut, содержащие \(.applicationName).
Один и тот же интент работает с Siri, Shortcuts, интерактивными виджетами и элементами управления, а также локализуется с помощью LocalizedStringResource.

Часто задаваемые вопросы

Урок «App Intents и быстрые команды» бесплатный?

Да — полный текст урока «App Intents и быстрые команды» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Swift Academy, подпишись на CoddyKit PRO. Курс Swift Academy содержит 4 уроков всего.

Чему я научусь в уроке «App Intents и быстрые команды»?

Предоставляйте действия для Siri и быстрых команд. Ты практикуешь Swift Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Swift Academy?

Предыдущий опыт не требуется. Swift Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.

Сколько времени занимает урок «App Intents и быстрые команды»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Swift Academy?

Да. Каждый урок Swift Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к Swift Academy